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
将宽字符串转换为多字节字符串 (函数)