wcrtomb

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

語法

size_t wcrtomb(
   char *mbchar,
   wchar_t wchar,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcrtomb(
   char (&mbchar)[size],
   wchar_t wchar,
   mbstate_t *mbstate
); // C++ only

參數

mbchar
產生的多位元組轉換字元。

wchar
要轉換的寬字元。

mbstate
mbstate_t 物件的指標。

傳回值

傳回代表已轉換多位元組字元的必要位元組數，如果發生錯誤則為 -1。

備註

wcrtomb 函式會轉換寬字元，從 mbstate 包含的指定轉換狀態開始，從 wchar 包含的值中，變成 mbchar 代表的位址。 傳回值是表示對應的多位元組字元所需的位元組數目，但它不會傳回超過 MB_CUR_MAX 個位元組。

如果 mbstate 為 Null，則使用包含 mbchar 轉換狀態的內部 mbstate_t 物件。 如果字元序列 wchar 沒有對應的多位元組字元表示法，則會傳回 -1，並將 errno 設定為 EILSEQ。

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

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

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

例外狀況

wcrtomb 函式是安全多執行緒，但前提是當這個函式執行中、且 mbstate 為 Null 時，目前執行緒中沒有任何函式呼叫 setlocale。

範例

// crt_wcrtomb.c
// compile with: /W3
// This program converts a wide character
// to its corresponding multibyte character.

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    size_t      sizeOfCovertion = 0;
    mbstate_t   mbstate;
    char        mbStr = 0;
    wchar_t*    wcStr = L"Q";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    sizeOfCovertion = wcrtomb(&mbStr, *wcStr, &mbstate); // C4996
    // Note: wcrtomb is deprecated; consider using wcrtomb_s instead
    if (sizeOfCovertion > 0)
    {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wcStr);
        printf(" was converted to the \"%c\" ", mbStr);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to the "Q" multibyte character.

需求

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

另請參閱

資料轉換
地區設定
多位元組字元序列的解譯
mbsinit