mbstowcs、_mbstowcs_lmbstowcs, _mbstowcs_l

将多字节字符序列转换为对应的宽字符序列。Converts a sequence of multibyte characters to a corresponding sequence of wide characters. 提供这些函数的更多安全版本;请参阅 mbstowcs_s、_mbstowcs_s_lMore secure versions of these functions are available; see mbstowcs_s, _mbstowcs_s_l.

语法Syntax

size_t mbstowcs(
   wchar_t *wcstr,
   const char *mbstr,
   size_t count
);
size_t _mbstowcs_l(
   wchar_t *wcstr,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t mbstowcs(
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
size_t _mbstowcs_l(
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

参数Parameters

wcstrwcstr
宽字符序列的地址。The address of a sequence of wide characters.

mbstrmbstr
Null 终止的多字节字符序列的地址。The address of a sequence of null terminated multibyte characters.

countcount
要转换的多字节字符的最大数量。The maximum number of multibyte characters to convert.

localelocale
要使用的区域设置。The locale to use.

返回值Return Value

如果mbstowcs成功转换了源字符串,它将返回已转换多字节字符数。If mbstowcs successfully converts the source string, it returns the number of converted multibyte characters. 如果wcstr自变量是NULL,该函数返回的目标字符串所需的大小 (以宽字符为单位)。If the wcstr argument is NULL, the function returns the required size (in wide characters) of the destination string. 如果mbstowcs遇到无效的多字节字符,则返回-1。If mbstowcs encounters an invalid multibyte character, it returns -1. 如果返回值是计数,宽字符字符串不以 null 结尾。If the return value is count, the wide-character string is not null-terminated.

重要

絋粄wcstrmbstr未重叠,并且计数正确反映了要转换的多字节字符的数量。Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of multibyte characters to convert.

备注Remarks

Mbstowcs函数将转换到的最大数目计数指向多字节字符mbstr为相应的宽字符的字符串由当前区域设置确定。The mbstowcs function converts up to a maximum number of count multibyte characters pointed to by mbstr to a string of corresponding wide characters that are determined by the current locale. 它将存储生成的宽字符字符串表示的地址处wcstrIt stores the resulting wide-character string at the address represented by wcstr. 结果是类似于对一系列mbtowcThe result is similar to a series of calls to mbtowc. 如果mbstowcs遇到单字节 null 字符 (\0) 之前或当计数发生,它会将转换为宽字符 null 字符 (L '\0) 的 null 字符并停止。If mbstowcs encounters the single-byte null character ('\0') either before or when count occurs, it converts the null character to a wide-character null character (L'\0') and stops. 因此处的宽字符字符串wcstr是 null 终止的仅当在转换期间遇到 null 字符。Thus the wide-character string at wcstr is null-terminated only if a null character is encountered during conversion. 如果指向的序列wcstrmbstr重叠,该行为不确定。If the sequences pointed to by wcstr and mbstr overlap, the behavior is undefined.

如果wcstr自变量是NULLmbstowcs返回得出的转换,不包括 null 终止符的宽字符数。If the wcstr argument is NULL, mbstowcs returns the number of wide characters that would result from conversion, not including a null terminator. 源字符串必须以 null 结尾才能返回正确的值。The source string must be null-terminated for the correct value to be returned. 如果需要生成以 null 结尾的宽字符串,请向返回的值添加一个。If you need the resulting wide character string to be null-terminated, add one to the returned value.

如果mbstr自变量是NULL,或者,如果计数是 > INT_MAX,将调用无效参数处理程序,如中所述参数验证If the mbstr argument is NULL, or if count is > INT_MAX, the invalid parameter handler is invoked, as described in Parameter Validation . 如果允许执行继续,将 errno 设置为EINVAL和该函数将返回-1。If execution is allowed to continue, errno is set to EINVAL and the function returns -1.

mbstowcs的任何区域设置相关的行为; 使用当前区域设置 _mbstowcs_l是完全相同,只不过它改用已传入的区域设置。mbstowcs uses the current locale for any locale-dependent behavior; _mbstowcs_l is identical except that it uses the locale passed in instead. 有关详细信息,请参阅 LocaleFor more information, see Locale.

在 C++ 中,这些函数具有模板重载,以调用这些函数的更新、更安全副本。In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. 有关详细信息,请参阅 Secure Template OverloadsFor more information, see Secure Template Overloads.

要求Requirements

例程所返回的值Routine 必需的标头Required header
mbstowcsmbstowcs <stdlib.h><stdlib.h>
_mbstowcs_l_mbstowcs_l <stdlib.h><stdlib.h>

有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.

示例Example

// crt_mbstowcs.c
// compile with: /W3
// illustrates the behavior of the mbstowcs function

#include <stdlib.h>
#include <stdio.h>
#include <locale.h>

int main( void )
{
    size_t size;
    int nChar = 2; // number of characters to convert
    int requiredSize;

    unsigned char    *pmbnull  = NULL;
    unsigned char    *pmbhello = NULL;
    char* localeInfo;

    wchar_t *pwchello = L"\x3042\x3043"; // 2 Hiragana characters
    wchar_t *pwc;

    /* Enable the Japanese locale and codepage */
    localeInfo = setlocale(LC_ALL, "Japanese_Japan.932");
    printf("Locale information set to %s\n", localeInfo);

    printf( "Convert to multibyte string:\n" );

    requiredSize = wcstombs( NULL, pwchello, 0); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    printf("   Required Size: %d\n", requiredSize);

    /* Add one to leave room for the null terminator. */
    pmbhello = (unsigned char *)malloc( requiredSize + 1);
    if (! pmbhello)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = wcstombs( pmbhello, pwchello, requiredSize + 1); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    if (size == (size_t) (-1))
    {
        printf("Couldn't convert string. Code page 932 may"
                " not be available.\n");
        return 1;
    }
    printf( "   Number of bytes written to multibyte string: %u\n",
            (unsigned int) size );
    printf( "   Hex values of the" );
    printf( " multibyte characters: %#.2x %#.2x %#.2x %#.2x\n",
            pmbhello[0], pmbhello[1], pmbhello[2], pmbhello[3] );
    printf( "   Codepage 932 uses 0x81 to 0x9f as lead bytes.\n\n");

    printf( "Convert back to wide-character string:\n" );

    /* Assume we don't know the length of the multibyte string.
     Get the required size in characters, and allocate enough space. */

    requiredSize = mbstowcs(NULL, pmbhello, 0); // C4996
    /* Add one to leave room for the null terminator */
    pwc = (wchar_t *)malloc( (requiredSize + 1) * sizeof( wchar_t ));
    if (! pwc)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = mbstowcs( pwc, pmbhello, requiredSize + 1); // C4996
    if (size == (size_t) (-1))
    {
       printf("Couldn't convert string--invalid multibyte character.\n");
    }
    printf( "   Characters converted: %u\n", (unsigned int)size );
    printf( "   Hex value of first 2" );
    printf( " wide characters: %#.4x %#.4x\n\n", pwc[0], pwc[1] );
    free(pwc);
    free(pmbhello);
}
Locale information set to Japanese_Japan.932
Convert to multibyte string:
   Required Size: 4
   Number of bytes written to multibyte string: 4
   Hex values of the  multibyte characters: 0x82 0xa0 0x82 0xa1
   Codepage 932 uses 0x81 to 0x9f as lead bytes.

Convert back to wide-character string:
   Characters converted: 2
   Hex value of first 2 wide characters: 0x3042 0x3043

请参阅See also

数据转换Data Conversion
区域设置Locale
多字节字符序列的解释Interpretation of Multibyte-Character Sequences
_mbclen、mblen、_mblen_l_mbclen, mblen, _mblen_l
mbtowc、_mbtowc_lmbtowc, _mbtowc_l
wcstombs、_wcstombs_lwcstombs, _wcstombs_l
wctomb、_wctomb_lwctomb, _wctomb_l
MultiByteToWideCharMultiByteToWideChar