mbrtowc-c和c++标准函数

C&C++标准库

mbrtowc

函数 <cwchar>

size_t mbrtowc (wchar_t* pwc, const char* pmb, size_t max, mbstate_t* ps);
转换多字节序列为宽字符

pmb指向的多字节字符被转换为类型为wchar_t的值，并存储在pwc指向的位置。函数返回多字节字符的字节宽度。

该函数使用(并更新)由ps描述的转换状态。如果ps是一个空指针，则该函数使用自己的内部转换状态，只有调用该函数才会在必要时改变该状态。

如果pmb指向一个空字符，该函数将重置转换状态，并在pwc存储宽空字符后返回零。

用空指针作为pmb调用该函数也会重置转换状态，忽略参数pwc和max(没有字符存储在pwc中)。

这个函数的行为取决于所选C语言环境的LC_CTYPE类型。

这是mbtowc (<cstdlib>)的 restartable 版本。

☲ 参数

pwc
指向wchar_t类型对象的指针。
或者，这个参数可以是一个空指针，在这种情况下，函数不存储wchar_t转换的值，但仍然返回多字节字符的宽度。

pmb
指向多字节字符的第一个字节的指针。
或者，可以使用空指针调用函数，在这种情况下，函数将转换状态(ps或它自己的内部状态)重置为初始状态并返回0。

max
需要查找pmb的最大字节数。
宏常量MB_CUR_MAX定义了在当前区域设置下可以形成多字节字符的最大字符宽度(每个多字节字符包含的字节数)。
size_t是一个无符号整型。

ps
指向定义转换状态的mbstate_t对象的指针。

☉ 返回值

从pmb中用于生成宽字符的字节数。
如果这是空宽字符，或者pmb是空指针，函数返回0(在第一种情况下，空宽字符存储在pwc)。

如果pmb的最大字节数不能构成一个完整(但可能有效)的多字节字符，函数返回(size_t)-2(没有值存储在pwc)。

如果pmb指向的字符不能形成有效的多字节字符(或不是一个多字节字符的开头)，函数返回(size_t)-1并将errno设置为EILSEQ(没有值存储在pwc)。

注意，size_t是一个无符号整型，因此返回的值可能都不小于零。

☣ 示例

/* mbrtowc example */
#include <wchar.h>

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

  mbrlen ( NULL, 0, &mbs );  /* initialize mbs */

  while (max>0) {
    length = mbrtowc(&dest,pt,max,&mbs);
    if ((length==0)||(length>max)) break;
    wprintf (L"[%lc]",dest);
    pt+=length; max-=length;
  }
}

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

  printbuffer (str,sizeof(str));

  return 0;
}

函数printbuffer 的作用是:一个字符一个字符地打印一个多字节的字符串。
该示例在“C”区域设置中使用了一个简单的字符串，但是该函数支持支持多字节字符串的区域设置。
输出:

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

🍄 另请参阅

wcrtomb	将宽字符转换为多字节序列(function )
mbrlen	获取多字节字符的宽度(function )
mbsrtowcs	转换多字节字符串到宽字符字符串(function )
wcsrtombs	转换宽字符字符串多字节字符串(function )