C++

參考

<cstdlib> (stdlib.h)

函式
<cstdlib>

mbtowc

int mbtowc (wchar_t* pwc, const char* pmb, size_t max);
將多位元組序列轉換為寬字元
pmb 所指向的多位元組字元被轉換為 wchar_t 型別的值，並存儲在 pwc 所指向的位置。函式返回多位元組字元的位元組長度。

mbtowc 有其自己的內部轉換狀態，該狀態僅在必要時由對該函式的呼叫來改變。使用空指標作為 pmb 來呼叫該函式會重置狀態（並返回多位元組字元是否依賴於狀態）。

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

引數

pwc
指向 wchar_t 型別物件的指標。
或者，此引數可以是空指標，在這種情況下，函式不儲存 wchar_t 轉換結果，但仍然返回多位元組字元的位元組長度。
pmb
指向多位元組字元第一個位元組的指標。
或者，此引數可以是空指標，在這種情況下，函式會將其內部轉換狀態重置為初始值，並返回多位元組字元是否具有依賴於狀態的編碼。
max
為多位元組字元要考慮的 pmb 的最大位元組數。
在任何情況下，檢查的字元都不會超過 MB_CUR_MAX 個。
size_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
21
22
23
24
25
26
27
 
/* mbtowc example */
#include <stdio.h>      /* printf */
#include <stdlib.h>     /* mbtowc, wchar_t(C) */

void printbuffer (const char* pt, size_t max)
{
  int length;
  wchar_t dest;

  mbtowc (NULL, NULL, 0);  /* reset mbtowc */

  while (max>0) {
    length = mbtowc(&dest,pt,max);
    if (length<1) break;
    printf ("[%lc]",dest);
    pt+=length; max-=length;
  }
}

int main()
{
  const char str [] = "mbtowc example";

  printbuffer (str,sizeof(str));

  return 0;
}

printbuffer逐個字元地列印多位元組字串。

該示例使用了一個簡單的字串和 "C" locale，但該函式支援能解釋多位元組字串的 locale。

輸出

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


資料競爭

該函式會訪問 pmb 指向的陣列，並修改 pwc 指向的物件（如果不為 null）。
該函式還會訪問和修改一個內部狀態物件，這可能在併發呼叫此函式時導致資料競爭（對於可以使用外部狀態物件的替代方案，請參見 mbrtowc）。
併發地更改 locale 設定也可能引入資料競爭。

異常 (C++)

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

如果 pwc 既不是空指標，也不指向有效的物件，或者如果 pmb 既不是空指標，也不是指向足夠長的陣列（如上所述）的指標，則會導致未定義行為。

另見

mblen
獲取多位元組字元的長度 (函式)
wctomb
將寬字元轉換為多位元組序列 (函式)
mbstowcs
將多位元組字串轉換為寬字串 (函式)
wcstombs
將寬字串轉換為多位元組字串 (函式)