wctomb, wctomb_s

 

C

編譯器支援

語言

標頭檔案

型別支援

程式工具

變參函式支援

錯誤處理

動態記憶體管理

字串庫

演算法

數值

日期和時間工具

輸入/輸出支援

本地化支援

併發支援 (C11)

技術規範

符號索引

 

字串庫

空終止位元組字串

空終止多位元組字串

空終止寬字串

 

空終止多位元組字串

函式
寬字元/多位元組轉換
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)   mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
型別
mbstate_t (C95) char8_t (C23)	char16_t (C11) char32_t (C11)
宏
MB_LEN_MAX	MB_CUR_MAX

 

在標頭檔案 <stdlib.h> 中定義
int wctomb( char *s, wchar_t wc );	(1)
errno_t wctomb_s( int *restrict status, char *restrict s, rsize_t ssz, wchar_t wc );	(2)	(C11 起)

1) 將寬字元 wc 轉換為多位元組編碼並將其（包括任何移位序列）儲存在 s 所指向的字元陣列的第一個元素中。儲存的字元不超過 MB_CUR_MAX 個。轉換受當前 locale 的 LC_CTYPE 類別影響。

如果 wc 是空字元，則將空位元組寫入 s，前面是恢復初始移位狀態所需的任何移位序列。

如果 s 是空指標，此函式將重置全域性轉換狀態並確定是否使用移位序列。

2) 與 (1) 相同，除了結果在輸出引數 status 中返回，並且在執行時檢測到以下錯誤並呼叫當前安裝的 約束處理程式 函式：

• ssz 小於將寫入的位元組數（除非 s 為空）
• ssz 大於 RSIZE_MAX（除非 s 為空）
• s 是空指標但 ssz 不為零

與所有邊界檢查函式一樣，只有當實現定義了 __STDC_LIB_EXT1__ 並且使用者在包含 <stdlib.h> 之前將 __STDC_WANT_LIB_EXT1__ 定義為整數常量 1 時，才能保證 wctomb_s 可用。

注意

每次呼叫 wctomb 都會更新內部全域性轉換狀態（一個型別為 mbstate_t 的靜態物件，僅此函式可知）。如果多位元組編碼使用移位狀態，則此函式不可重入。在任何情況下，多個執行緒在沒有同步的情況下不應呼叫 wctomb：可以使用 wcrtomb 或 wctomb_s 代替。

與大多數邊界檢查函式不同，wctomb_s 不會以 null 終止其輸出，因為它設計用於逐字元處理字串的迴圈中。

引數

s	-	指向輸出字元陣列的指標
wc	-	要轉換的寬字元
ssz	-	寫入 s 的最大位元組數（陣列 s 的大小）
status	-	指向輸出引數的指標，結果（多位元組序列的長度或移位序列狀態）將儲存在此處

返回值

1) 如果 s 不是空指標，則返回 wc 的多位元組表示中包含的位元組數，如果 wc 不是有效字元，則返回 -1。

如果 s 是空指標，則將其內部轉換狀態重置為表示初始移位狀態，如果當前多位元組編碼不依賴於狀態（不使用移位序列），則返回 ​0​，如果當前多位元組編碼依賴於狀態（使用移位序列），則返回非零值。

2) 成功時返回零，在這種情況下，wc 的多位元組表示儲存在 s 中，其長度儲存在 *status 中，或者，如果 s 為空，則移位序列狀態儲存在 status 中）。編碼錯誤或執行時約束衝突時返回非零值，在這種情況下，(size_t)-1 儲存在 *status 中。*status 中儲存的值永遠不超過 MB_CUR_MAX。

示例

執行此程式碼

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
 
void demo(wchar_t wc)
{
    const char* dep = wctomb(NULL, wc) ? "Yes" : "No";
    printf("State-dependent encoding? %s.\n", dep);
 
    char mb[MB_CUR_MAX];
    int len = wctomb(mb, wc);
    printf("wide char '%lc' -> multibyte char [", wc);
    for (int idx = 0; idx < len; ++idx)
        printf("%s%#2x", idx ? " " : "", (unsigned char)mb[idx]);
    printf("]\n");
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX);
    demo(L'A');
    demo(L'\u00df');
    demo(L'\U0001d10b');
}

可能的輸出

MB_CUR_MAX = 6
State-dependent encoding? No.
wide char 'A' -> multibyte char [0x41]
State-dependent encoding? No.
wide char 'ß' -> multibyte char [0xc3 0x9f]
State-dependent encoding? No.
wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]

參考

• C17 標準 (ISO/IEC 9899:2018)

• 7.22.7.3 wctomb 函式 (p: 261)

• K.3.6.4.1 wctomb_s 函式 (p: 443)

• C11 標準 (ISO/IEC 9899:2011)

• 7.22.7.3 wctomb 函式 (p: 358-359)

• K.3.6.4.1 wctomb_s 函式 (p: 610-611)

• C99 標準 (ISO/IEC 9899:1999)

• 7.20.7.3 wctomb 函式 (p: 322-323)

• C89/C90 標準 (ISO/IEC 9899:1990)

• 4.10.7.3 wctomb 函式

另請參閱

mbtowc	將下一個多位元組字元轉換為寬字元 (函式)
wcrtombwcrtomb_s (C95)(C11)	將寬字元轉換為其多位元組表示，給定狀態 (函式)
C++ 文件 for wctomb