`mbrtowc`

Článek
10/12/2023

Převede vícebajtový znak v aktuálním národním prostředí na ekvivalentní široký znak s možností restartování uprostřed vícebajtového znaku.

Syntaxe

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

Parametry

wchar
Adresa širokého znaku pro příjem převedeného řetězce širokého znaku (typ wchar_t). Tato hodnota může být nulový ukazatel, pokud není vyžadován žádný návratový široký znak.

mbchar
Adresa posloupnosti bajtů (vícebajtový znak).

count
Počet bajtů, které chcete zkontrolovat.

mbstate
Ukazatel na objekt stavu převodu Pokud je tato hodnota ukazatel null, funkce používá statický objekt stavu interního převodu. Protože interní mbstate_t objekt není bezpečný pro přístup z více vláken, doporučujeme vždy předat vlastní mbstate argument.

Vrácená hodnota

Jedna z následujících hodnot:

0 Další count nebo méně bajtů dokončí vícebajtový znak, který představuje široký znak null, který je uložen v wchar, pokud wchar není ukazatel null.

1 až count, včetně Další count nebo méně bajtů dokončí platný vícebajtový znak. Vrácená hodnota je počet bajtů, které dokončí vícebajtový znak. Ekvivalent širokého znaku je uložen v wchar, pokud wchar není nulový ukazatel.

(size_t) (-1) Došlo k chybě kódování. Další count nebo méně bajtů nepřispívá k úplnému a platnému vícebajtovém znaku. V tomto případě errno je nastavena hodnota EILSEQ a stav směny převodu není mbstate zadaný.

(size_t) (-2) Další count bajty přispívají k neúplné, ale potenciálně platné vícebajtové znaky a všechny count bajty byly zpracovány. Žádná hodnota se neukládá wchar, ale mbstate aktualizuje se, aby se funkce restartoval.

Poznámky

Pokud mbchar je ukazatel null, funkce je ekvivalentní volání:

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

V tomto případě se hodnoty wchar argumentů ignorují count .

Pokud mbchar není ukazatel null, funkce prozkoumá count bajty z mbchar a určí požadovaný počet bajtů, které jsou potřeba k dokončení dalšího vícebajtového znaku. Pokud je další znak platný, uloží se odpovídající vícebajtový znak, wchar pokud není ukazatelem null. Pokud je znak odpovídajícím širokým znakem null, výsledný stav mbstate je počáteční stav převodu.

Funkce mbrtowc se liší od mbtowcmožnosti _mbtowc_l restartování. Stav převodu se uloží mbstate pro následná volání stejných nebo jiných restartovatelných funkcí. Výsledky nejsou definovány při kombinování použití restartovatelných a nerestartovatelných funkcí. Například aplikace by měla místo toho, wcsrlenwcslen pokud se místo následného volání wcsrtombs použije wcstombs.

Ve výchozím nastavení je globální stav této funkce vymezen na aplikaci. Chcete-li toto chování změnit, přečtěte si téma Globální stav v CRT.

Příklad

Převede vícebajtový znak na jeho široký znak ekvivalent.

// 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);
}

Ukázkový výstup

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

Požadavky

Rutina	Požadovaný hlavičkový soubor
`mbrtowc`	<wchar.h>

Viz také

Převod dat
Národní prostředí
Interpretace vícebajtových sekvencí znaků

Sdílet prostřednictvím