`mbrtowc`

Artykuł
10/12/2023

Przekonwertuj znak wielobajtowy w bieżących ustawieniach regionalnych na odpowiedni znak szeroki, a możliwość ponownego uruchomienia w środku znaku wielobajtowego.

Składnia

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

Parametry

wchar
Adres szerokiego znaku, który ma otrzymać przekonwertowany ciąg znaków szeroki (typ wchar_t). Ta wartość może być wskaźnikiem o wartości null, jeśli nie jest wymagany żaden znak szeroki.

mbchar
Adres sekwencji bajtów (znak wielobajtowy).

count
Liczba bajtów do sprawdzenia.

mbstate
Wskaźnik do obiektu stanu konwersji. Jeśli ta wartość jest wskaźnikiem o wartości null, funkcja używa statycznego obiektu stanu konwersji wewnętrznej. Ponieważ obiekt wewnętrzny mbstate_t nie jest bezpieczny wątkowo, zalecamy, aby zawsze przekazywać własny mbstate argument.

Wartość zwracana

Jedna z następujących wartości:

0 Następne count lub mniejsze bajty zakończą znak wielobajtowy, który reprezentuje znak szeroki o wartości null, który jest przechowywany w wcharobiekcie , jeśli wchar nie jest wskaźnikiem o wartości null.

Od 1 do count, włącznie następne count lub mniej bajtów kończy prawidłowy znak wielobajtowy. Zwracana wartość to liczba bajtów, które zakończą znak wielobajtowy. Odpowiednik znaku szerokiego jest przechowywany w wcharelemencie , jeśli wchar nie jest wskaźnikiem o wartości null.

(size_t) (-1) Wystąpił błąd kodowania. count Kolejne lub mniejsze bajty nie przyczyniają się do kompletnego i prawidłowego znaku wielobajtowego. W takim przypadku jest ustawiona wartość EILSEQ, errno a stan zmiany konwersji w mbstate pliku jest nieokreślony.

(size_t) (-2) count Następne bajty przyczyniają się do niekompletnego, ale potencjalnie prawidłowego znaku wielobajtowego, a wszystkie count bajty zostały przetworzone. Żadna wartość nie jest przechowywana w wcharpliku , ale mbstate jest aktualizowana w celu ponownego uruchomienia funkcji.

Uwagi

Jeśli mbchar jest wskaźnikiem o wartości null, funkcja jest równoważna wywołaniu:

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

W takim przypadku wartości argumentów wchar i count są ignorowane.

Jeśli mbchar nie jest wskaźnikiem o wartości null, funkcja sprawdza bajty count z mbchar , aby określić wymaganą liczbę bajtów wymaganych do ukończenia następnego znaku wielobajtowego. Jeśli następny znak jest prawidłowy, odpowiedni znak wielobajtowy jest przechowywany, wchar jeśli nie jest to wskaźnik o wartości null. Jeśli znak jest odpowiednim szerokim znakiem null, wynikowy stan jest stanem mbstate konwersji początkowej.

Funkcja mbrtowc różni się od mbtowcfunkcji , _mbtowc_l dzięki możliwości ponownego uruchamiania. Stan konwersji jest przechowywany dla mbstate kolejnych wywołań do tych samych lub innych funkcji możliwych do ponownego uruchomienia. Wyniki są niezdefiniowane podczas mieszania funkcji możliwych do ponownego uruchomienia i niezwiązanych z uruchamianiem. Na przykład aplikacja powinna używać wcsrlen zamiast wcslen , jeśli kolejne wywołanie wcsrtombs metody jest używane zamiast wcstombs.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Przykład

Konwertuje znak wielobajtowy na jego szeroki odpowiednik znaków.

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

Przykładowe dane wyjściowe

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

Wymagania

Procedura	Wymagany nagłówek
`mbrtowc`	<wchar.h>

Zobacz też

Konwersja danych
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych

Share via