`mbrtowc`

Article
10/12/2023

Convertir un caractère multioctet dans les paramètres régionaux actuels en un caractère large équivalent, avec la possibilité de redémarrer au milieu d'un caractère multioctet.

Syntaxe

size_t mbrtowc(
   wchar_t *wchar,
   const char *mbchar,
   size_t count,
   mbstate_t *mbstate
);

Paramètres

wchar
Adresse d'un caractère large pour recevoir la chaîne de caractères larges convertie (type wchar_t). Cette valeur peut être un pointeur null si un caractère large n'est pas requis en retour.

mbchar
Adresse d'une séquence d'octets (un caractère multioctet).

count
Nombre d'octets à vérifier.

mbstate
Pointeur vers un objet d'état de conversion. Si cette valeur est un pointeur null, la fonction utilise un objet d'état de conversion interne statique. Étant donné que l’objet interne mbstate_t n’est pas thread-safe, nous vous recommandons de toujours passer votre propre mbstate argument.

Valeur retournée

L’une des valeurs suivantes :

0 Les octets suivants count ou moins terminent le caractère multioctet qui représente le caractère large Null, qui est stocké dans wchar, si wchar ce n’est pas un pointeur Null.

1 à count, inclus Les octets suivants count ou moins terminent un caractère multioctet valide. La valeur retournée est le nombre d'octets qui terminent le caractère multioctet. L’équivalent de caractère large est stocké dans wchar, s’il wchar n’est pas un pointeur Null.

(size_t) (-1) Une erreur d’encodage s’est produite. Les octets suivants count ou moins ne contribuent pas à un caractère multioctet complet et valide. Dans ce cas, errno est défini à EILSEQ et l'état du décalage de la conversion dans mbstate n'est pas spécifié.

(size_t) (-2) Les octets suivants count contribuent à un caractère multioctet incomplet mais potentiellement valide, et tous les count octets ont été traités. Aucune valeur n'est stockée dans wchar, mais mbstate est mis à jour pour redémarrer la fonction.

Notes

Si mbchar est un pointeur null, la fonction est équivalente à l'appel :

mbrtowc(NULL, "", 1, &mbstate)

Dans ce cas, les valeurs des wchar arguments et count des arguments sont ignorées.

Si mbchar ce n’est pas un pointeur Null, la fonction examine les octets count de mbchar pour déterminer le nombre requis d’octets requis pour terminer le caractère multioctet suivant. Si le caractère suivant est valide, le caractère multioctet correspondant est stocké s’il wchar n’est pas un pointeur Null. Si le caractère est le caractère null large correspondant, l'état résultant de mbstate est l'état de la conversion initiale.

La mbrtowc fonction diffère de , _mbtowc_l par mbtowcsa capacité de redémarrage. L'état de la conversion est stocké dans mbstate pour les appels suivants à la même ou à d'autres fonctions redémarrables. Les résultats ne sont pas définis quand l'utilisation de fonctions redémarrables est combinée avec l'utilisation de fonctions non redémarrables. Par exemple, une application doit utiliser wcsrlen au lieu de wcslen si un appel ultérieur à wcsrtombs est utilisé à la place de wcstombs

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Exemple

Convertit un caractère multioctet en son équivalent en caractère large.

// crt_mbrtowc.cpp

#include <stdio.h>
#include <mbctype.h>
#include <string.h>
#include <locale.h>
#include <wchar.h>

#define BUF_SIZE 100

int Sample(char* szIn, wchar_t* wcOut, int nMax)
{
    mbstate_t   state = {0}; // Initial state
    size_t      nConvResult,
                nmbLen = 0,
                nwcLen = 0;
    wchar_t*    wcCur = wcOut;
    wchar_t*    wcEnd = wcCur + nMax;
    const char* mbCur = szIn;
    const char* mbEnd = mbCur + strlen(mbCur) + 1;
    char*       szLocal;

    // Sets all locale to French_Canada.1252
    szLocal = setlocale(LC_ALL, "French_Canada.1252");
    if (!szLocal)
    {
        printf("The fuction setlocale(LC_ALL, \"French_Canada.1252\") failed!\n");
        return 1;
    }

    printf("Locale set to: \"%s\"\n", szLocal);

    // Sets the code page associated current locale's code page
    // from a previous call to setlocale.
    if (_setmbcp(_MB_CP_SBCS) == -1)
    {
        printf("The fuction _setmbcp(_MB_CP_SBCS) failed!");
        return 1;
    }

    while ((mbCur < mbEnd) && (wcCur < wcEnd))
    {
        //
        nConvResult = mbrtowc(wcCur, mbCur, 1, &state);
        switch (nConvResult)
        {
            case 0:
            {  // done
                printf("Conversion succeeded!\nMultibyte String: ");
                printf(szIn);
                printf("\nWC String: ");
                wprintf(wcOut);
                printf("\n");
                mbCur = mbEnd;
                break;
            }

            case -1:
            {  // encoding error
                printf("The call to mbrtowc has detected an encoding error.\n");
                mbCur = mbEnd;
                break;
            }

            case -2:
            {  // incomplete character
                if   (!mbsinit(&state))
                {
                    printf("Currently in middle of mb conversion, state = %x\n", state);
                    // state will contain data regarding lead byte of mb character
                }

                ++nmbLen;
                ++mbCur;
                break;
            }

            default:
            {
                if   (nConvResult > 2) // The multibyte should never be larger than 2
                {
                    printf("Error: The size of the converted multibyte is %d.\n", nConvResult);
                }

                ++nmbLen;
                ++nwcLen;
                ++wcCur;
                ++mbCur;
            break;
            }
        }
    }

   return 0;
}

int main(int argc, char* argv[])
{
    char    mbBuf[BUF_SIZE] = "AaBbCc\x9A\x8B\xE0\xEF\xF0xXyYzZ";
    wchar_t wcBuf[BUF_SIZE] = {L''};

    return Sample(mbBuf, wcBuf, BUF_SIZE);
}

Exemple de sortie

Locale set to: "French_Canada.1252"
Conversion succeeded!
Multibyte String: AaBbCcÜïα∩≡xXyYzZ
WC String: AaBbCcÜïα∩≡xXyYzZ

Spécifications

Routine	En-tête requis
`mbrtowc`	<wchar.h>

Voir aussi

Conversion de données
Paramètres régionaux
Interprétation des séquences de caractères multioctets

Partager via