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 結束。

重要

確定 wcstr 和 mbstr 沒有重疊，而且 count 正確反映要轉換的多位元組字元數。

備註

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

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

如果自 mbstr 變數為 ，或 如果 count 為 >NULLINT_MAX ，則會叫用不正確參數處理常式，如參數驗證 中所述。 如果允許繼續執行， 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