函式
<cstdlib>

wctomb

int wctomb (char* pmb, wchar_t wc);
將寬字元轉換成多位元組序列
寬字元 wc 被翻譯為其等效的多位元組字元,並存儲在 pmb 指向的陣列中。函式返回呼叫後 pmb 所指向的等效多位元組序列的位元組長度。

wctomb 擁有其自己的內部轉換狀態,該狀態僅在必要時由對該函式的呼叫來改變。以空指標作為 pmb 呼叫該函式會重置該狀態(並返回多位元組序列是否是狀態相關的)。

此函式的行為取決於所選 C localeLC_CTYPE 類別。

引數

pmb
指向一個足以容納多位元組序列的陣列的指標。
在當前區域設定中,一個字元的多位元組序列的最大長度是 MB_CUR_MAX 位元組。
或者,該函式也可以用空指標呼叫,在這種情況下,函式會將其內部轉換狀態重置為初始值,並返回多位元組序列是否使用狀態相關的編碼。
wc
wchar_t 型別的寬字元。

返回值

如果作為 pmb 傳遞的引數不是空指標,則返回寫入到 pmb 的字元的位元組大小。如果沒有對應的字元,則返回 -1

如果作為 pmb 傳遞的引數是空指標,並且多位元組字元編碼是狀態相關的,則函式返回一個非零值,否則返回零。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/* wctomb example */
#include <stdio.h>      /* printf */
#include <stdlib.h>     /* wctomb, wchar_t(C) */

int main() {
  const wchar_t str[] = L"wctomb example";
  const wchar_t* pt;
  char buffer [MB_CUR_MAX];
  int i,length;

  pt = str;
  while (*pt) {
    length = wctomb(buffer,*pt);
    if (length<1) break;
    for (i=0;i<length;++i) printf ("[%c]",buffer[i]);
    ++pt;
  }

  return 0;
}

該示例使用所選的區域設定(在本例中為預設的 "C" 區域設定),打印出寬字串轉換成的多位元組字元。

輸出

[w][c][t][o][m][b][ ][e][x][a][m][p][l][e]


資料競爭

該函式修改由 pmb 指向的陣列。
該函式還會訪問和修改一個內部狀態物件,這可能在併發呼叫此函式時導致資料競爭(請參閱 wcrtomb,這是一個可以使用外部狀態物件的替代方案)。
併發地更改 locale 設定也可能引入資料競爭。

異常 (C++)

無丟擲保證:此函式不會丟擲異常。

如果 pmb 既不是空指標,也不是指向一個足夠長的陣列以容納轉換後字元的指標,它將導致未定義行為

另見