`mbrtowc`

Статья
10/12/2023

Преобразуют многобайтовый символ в текущем языковом стандарте в эквивалентный расширенный символ с возможностью перезапуска в середине многобайтового символа.

Синтаксис

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

Параметры

wchar
Адрес расширенного символа для получения преобразованной строки расширенных символов (тип wchar_t). Это значение может быть пустым указателем, если не требуется возвращать расширенный символ.

mbchar
Адрес последовательности байтов (многобайтовый символ).

count
Число проверяемых байтов.

mbstate
Указатель на объект состояния преобразования. Если это значение является пустым указателем, функция использует статичный внутренний объект состояния преобразования. Так как внутренний mbstate_t объект не является потокобезопасной, рекомендуется всегда передавать собственный mbstate аргумент.

Возвращаемое значение

Одно из следующих значений:

0 Следующий count или меньше байт завершает многобайтовый символ, представляющий широкий символ NULL, который хранится в wchar, если wchar не является пустым указателем.

От 1 до count, включающее следующий count или меньше байтов, завершают допустимый многобайтовый символ. Возвращаемое значение равно количеству байтов, составляющих многобайтовый символ. Эквивалент широкого символа хранится в wchar, если wchar не является пустым указателем.

(size_t) (-1) Произошла ошибка кодирования. Следующие count или меньше байтов не вносят свой вклад в полный и допустимый многобайтовый символ. В этом случае значение errno будет EILSEQ, а состояние сдвига преобразования в mbstate будет не определено.

(size_t) (-2) Следующие count байты вносят неполный, но потенциально допустимый многобайтовый символ, и все count байты были обработаны. Значение в wchar не сохраняется, но mbstate обновляется для перезапуска функции.

Замечания

Если параметр mbchar является пустым указателем, функция эквивалентна вызову:

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

В этом случае значения wchar аргументов count игнорируются.

Если mbchar указатель не является пустым, функция проверяет count байты, mbchar чтобы определить требуемое количество байтов, необходимых для выполнения следующего многобайтового символа. Если следующий символ действителен, соответствующий многобайтовый символ хранится в wchar том случае, если он не является пустым указателем. Если символ соответствует расширенному нуль-символу, результирующее состояние mbstate является начальным состоянием преобразования.

Функция mbrtowc отличается от _mbtowc_lmbtowc ее перезапуска. Состояние преобразования хранится в переменной mbstate для последующих вызовов тех же или других перезапускаемых функций. При смешанном использовании перезапускаемых и неперезапускаемых функций результаты становятся неопределенными. Например, в приложении необходимо использовать функцию wcsrlen вместо функции wcslen, если в последующем вызове используется функция wcsrtombs, а не функция wcstombs.

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Пример

Преобразует многобайтовый символ в эквивалентный расширенный символ.

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

Пример полученных результатов

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

Требования

Маршрут	Обязательный заголовок
`mbrtowc`	<wchar.h>

См. также

Преобразование данных
Локаль
Интерпретация последовательностей многобайтовых символов

Share via