wcsrtombs

將寬字元字串轉換為其多位元組字元字串表示法。 此函式有更安全的版本可供使用;請參閱 wcsrtombs_s。

語法

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

參數

mbstr
產生的已轉換多位元組字串的位址位置。

wcstr
間接指向要轉換的寬字元字串位置。

count
要轉換的字元數。

mbstate
mbstate_t 轉換狀態物件的指標。

傳回值

傳回成功轉換的位元組數，不含 Null 終止 Null 位元組 (如果有的話)，如果發生錯誤則為 -1。

備註

wcsrtombs 函式會轉換寬字元字串，從 mbstate 包含的指定轉換狀態開始，從 wcstr 中間接指向的值，變成 mbstr 的位址。 每個字元都會轉換，一直持續到︰遇到以 Null 終止的寬字元後、遇到非對應的字元時，或下一個字元會超過 count 包含的限制時。 如果在 count 發生前或發生時，wcsrtombs 遇到寬字元 Null 字元 (L'\0')，就會將它轉換成 8 位元的 0 並停止。

因此，只有當 wcsrtombs 在轉換期間遇到寬字元的 Null 字元時，mbstr 的多位元組字元字串才能以 Null 終止。 如果 wcstr 和 mbstr 所指向的序列重疊，wcsrtombs 的行為不明。 wcsrtombs 受到目前地區設定之 LC_TYPE 分類的影響。

函式wcsrtombs與 _wcstombs_lwcstombs 不同之處在於其可重新啟動性。 針對相同或其他可重新啟動的函式的後續呼叫，轉換狀態會儲存在 mbstate 中。 混合使用可重新啟動和不可重新啟動之函式的結果不明。 例如，如果使用了 wcsrtombs 的後續呼叫，而不是 wcstombs，應用程式應該使用 wcsrlen，而不是 wcsnlen。

如果 mbstr 引數為 NULL，則 wcsrtombs 會傳回目的字串所需的大小 (以位元組為單位)。 如果 mbstate 為 Null，則使用內部的 mbstate_t 轉換狀態。 如果字元序列 wchar 沒有對應的多位元組字元表示法，則會傳回 -1，並將 errno 設定為 EILSEQ。

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

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

例外狀況

wcsrtombs只要此函式正在執行mbstate且 不是 Null 時，目前的線程呼叫setlocale中沒有任何函式，函式就會是多線程安全。

範例

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfuly converted.\n" );
    }
}

The string was successfuly converted.

需求

常式	必要的標頭
wcsrtombs	<wchar.h>

另請參閱

資料轉換
地區設定
多位元組字元序列的解譯
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit