mbrtowcmbrtowc

将当前区域设置中的多字节字符转换为等效的宽字符,使其重启功能位于多字节字符的中间。Convert a multibyte character in the current locale into the equivalent wide character, with the capability of restarting in the middle of a multibyte character.

语法Syntax

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

参数Parameters

wcharwchar
若要接收已转换的宽字符字符串的宽字符的地址 (类型wchar_t)。Address of a wide character to receive the converted wide character string (type wchar_t). 如果不需要返回任何宽字符,则此值可为 null 指针。This value can be a null pointer if no return wide character is required.

mbcharmbchar
字节(多字节字符)序列的地址。Address of a sequence of bytes (a multibyte character).

countcount
要检查的字节数。Number of bytes to check.

mbstatembstate
指向转换状态对象的指针。Pointer to conversion state object. 如果此值为 null 指针,则函数使用静态的内部转换状态对象。If this value is a null pointer, the function uses a static internal conversion state object. 因为内部mbstate_t对象不是线程安全,我们建议始终传递你自己mbstate自变量。Because the internal mbstate_t object is not thread-safe, we recommend that you always pass your own mbstate argument.

返回值Return Value

以下值之一:One of the following values:

0 下一步计数或更少字节将填充表示 null 宽字符,它存储在多字节字符wchar,如果wchar不是 null 指针。0 The next count or fewer bytes complete the multibyte character that represents the null wide character, which is stored in wchar, if wchar is not a null pointer.

1 到计数(含) 之间的下一步计数或更少的字节填充有效多字节字符。1 to count, inclusive The next count or fewer bytes complete a valid multibyte character. 返回的值是填充多字节字符的字节数。The value returned is the number of bytes that complete the multibyte character. 等效的宽字符存储在wchar,如果wchar不是 null 指针。The wide character equivalent is stored in wchar, if wchar is not a null pointer.

(size_t)(-1)发生编码错误。(size_t)(-1) An encoding error occurred. 下一步计数或更少字节数不有利于实现完整且有效的多字节字符。The next count or fewer bytes do not contribute to a complete and valid multibyte character. 在这种情况下, errno设置为 EILSEQ 且中的转换位移状态mbstate未指定。In this case, errno is set to EILSEQ and the conversion shift state in mbstate is unspecified.

(size_t)(-2)下一步计数字节数有利于实现不完整但可能有效的多字节字符,并且所有计数已处理的字节数。(size_t)(-2) The next count bytes contribute to an incomplete but potentially valid multibyte character, and all count bytes have been processed. 中存储任何值wchar,但mbstate被更新,以重新启动该函数。No value is stored in wchar, but mbstate is updated to restart the function.

备注Remarks

如果mbchar是 null 指针,该函数等效于调用:If mbchar is a null pointer, the function is equivalent to the call:

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

在此情况下,这些参数的值wchar计数将被忽略。In this case, the value of the arguments wchar and count are ignored.

如果mbchar不是 null 指针,该函数将检查计数个字节从mbchar以确定所需完成下一步所需的字节数多字节字符。If mbchar is not a null pointer, the function examines count bytes from mbchar to determine the required number of bytes that are required to complete the next multibyte character. 如果下一个字符是有效的将相应的多字节字符存储在wchar如果它不是 null 指针。If the next character is valid, the corresponding multibyte character is stored in wchar if it is not a null pointer. 如果字符是相应的宽 null 字符,结果状态的mbstate是初始转换状态。If the character is the corresponding wide null character, the resulting state of mbstate is the initial conversion state.

Mbrtowc函数不同于mbtowc、 _mbtowc_l通过其可重启性。The mbrtowc function differs from mbtowc, _mbtowc_l by its restartability. 转换状态存储在mbstate以便后续调用相同的或其他可重启函数。The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. 混合使用可重启函数和不可重启函数时,结果不确定。Results are undefined when mixing the use of restartable and nonrestartable functions. 例如,应用程序应使用wcsrlen而不是wcslen如果的后续调用wcsrtombs而不是使用wcstombs.For example, an application should use wcsrlen instead of wcslen if a subsequent call to wcsrtombs is used instead of wcstombs.

示例Example

将多字节字符转换为其等效的宽字符。Converts a multibyte character to its wide character equivalent.

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

示例输出Sample Output

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

要求Requirements

例程Routine 必需的标头Required header
mbrtowcmbrtowc <wchar.h><wchar.h>

请参阅See also

数据转换Data Conversion
区域设置Locale
多字节字符序列的解释Interpretation of Multibyte-Character Sequences