Share via

wcstombs, _wcstombs_l

  • 發行項

將一連串的寬字元轉換為對應的一連串多位元組字元。 這些函式有更安全的版本可供使用;請參閱 wcstombs_s 、 _wcstombs_s_l 。

語法

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

參數

mbstr
多位元組字元序列的位址。

wcstr
寬字元序列的位址。

count
可以儲存在多位元組輸出字串的最大位元組數。

locale
要使用的地區設定。

傳回值

如果 wcstombs 成功轉換多位元組字串，即會傳回寫入多位元組輸出字串的位元組數目，不包括終止的 NULL (如果有的話)。 如果 mbstr 引數為 NULL，則 wcstombs 會傳回目的字串所需的大小 (以位元組為單位)。 如果 wcstombs 遇到寬字元，它無法轉換成多位元組字元，則會傳回 -1 轉換成 類型 size_t ，並將 設定 errno 為 EILSEQ 。

備註

wcstombs 函式會將 wcstr 指向的寬字元字串轉換成對應的多位元組字元，並將結果儲存在 mbstr 陣列中。 count 參數指出可以儲存在多位元組輸出字串的最大位元組數 (亦即 mbstr 的大小)。 一般而言，在轉換寬字元字串時，並不知道需要多少個位元組。 某些寬字元只需要輸出字串中的單一位元組;其他則需要 2 個位元組。 如果輸入字串中每一個寬字元的多位元組輸出字串中有 2 個位元組（包括寬字元 NULL ），則結果保證符合。

從 Windows 10 版本 1803 （10.0.17134.0）開始，通用 C 執行時間支援使用 UTF-8 字碼頁。 使用 wcstombs(NULL, wcstr, 0) 來取得轉換所需的正確大小，因為假設每個寬字元都需要兩個位元組可能不夠。 如需 UTF-8 支援的詳細資訊，請參閱 UTF-8 支援

如果在 wcstombs 發生之前或發生時 count 遇到寬字元 NULL 字元 （L'\0'），則會將它轉換成 8 位 0 並停止。 因此，只有在 wcstombs 轉換期間遇到寬字元 NULL 字元時，位於 的多位元組字元字串 mbstr 才會以 null 終止。 如果 wcstr 和 mbstr 所指向的序列重疊，wcstombs 的行為不明。

如果 mbstr 引數為 NULL，則 wcstombs 會傳回目的字串所需的大小 (以位元組為單位)。

wcstombs 會驗證其參數。 如果 wcstr 為 NULL ，或 如果 count 大於 INT_MAX ，則此函式會叫用不正確參數處理常式，如參數驗證 中所述 。 如果允許繼續執行，則函式會將 errno 設定為 EINVAL 並傳回 -1。

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

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

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

需求

常式 必要的標頭
wcstombs <stdlib.h>
_wcstombs_l <stdlib.h>

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

範例

此程式說明 wcstombs 函式的行為。

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of
// multibyte characters.

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

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

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

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}

Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

另請參閱

資料轉換
地區設定
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb, _wctomb_l
WideCharToMultiByte