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