共用方式為


mbstowcs, _mbstowcs_l

將多位元組字元序列轉換成對應的寬字元序列。 這些函式已有更安全的版本可用,請參閱 mbstowcs_s_mbstowcs_s_l

語法

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

參數

wcstr
寬字元序列的位址。

mbstr
以 Null 結束之多位元組字元序列的位址。

count
要轉換的多位元組字元數上限。

locale
要使用的地區設定。

傳回值

如果 mbstowcs 成功轉換來源字串,則會傳回已轉換的多位元組字元數。 如果 wcstr 引數為 NULL,函式會傳回目的字串所需的大小 (以寬字元為單位)。 如果 mbstowcs 遇到無效的多位元組位元,則會傳回 -1。 如果傳回值為 count,則寬字元字串不會以 Null 結束。

重要

確定 wcstrmbstr 沒有重疊,而且 count 正確反映要轉換的多位元組字元數。

備註

mbstowcs 函式最多可將 mbstr 所指向的 count 個多位元組字元,轉換成目前地區設定所決定的對應寬字元字串。 它會將產生的寬字元字串儲存在 所 wcstr表示的位址。 結果會類似於對 mbtowc 的一連串呼叫。 如果在 mbstowcs 發生之前或發生時 count 遇到單一位元組 Null 字元 ('\0'),則會將 Null 字元轉換成寬字元 Null 字元 (L'\0') 並停止。 因此,只有在轉換期間遇到 Null 字元時,wcstr 的寬字元字串才會以 Null 結束。 如果 wcstrmbstr 所指向的序列重疊,則行為是未定義的。

如果 wcstr 引數為 NULLmbstowcs 會傳回轉換所產生的寬字元數,但不包括 Null 結束字元。 來源字串必須以 Null 結束,才能傳回正確的值。 如果您需要產生的寬字元字串以 Null 結束,請將一個 Null 新增至傳回的值。

如果自mbstr變數為 ,或 如果 count 為 >INT_MAXNULL,則會叫用無效的參數處理程式,如參數驗證中所述。 如果允許繼續執行, errno 會設定為 EINVAL ,且此函式會傳回 -1。

mbstowcs 會針對任何與地區設定相關的行為使用目前的地區設定;_mbstowcs_l 與其相同,只不過它會改用傳入的地區設定。 如需詳細資訊,請參閱 Locale

在 C++ 中,這些函式具有樣板多載,可以叫用這些函式的更新且安全的對應版本。 如需詳細資訊,請參閱安全範本多載

根據預設,此函式的全域狀態會限定於應用程式。 若要變更此行為,請參閱 CRT 中的全域狀態

需求

常式 必要的標頭
mbstowcs <stdlib.h>
_mbstowcs_l <stdlib.h>

如需相容性詳細資訊,請參閱相容性

範例

// 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

另請參閱

資料轉換
地區設定
多位元組字元序列的解譯
_mbclen、 、 mblen_mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar