当前位置： C语言 -- 标准库 -- <wchar.h> -- mbsrtowcs

mbsrtowcs函数

概要： 
#include <wchar.h>
size_t mbsrtowcs(wchar_t * restrict dst,
      const char ** restrict src,
      size_t len,
      mbstate_t * restrict ps);
描述：

该函数将参数src间接指向的数组中多字节字符序列转换为对应的宽字符序列（多字节字符序列开始时的转换状态使用参数ps指向的对象描述。）。如果参数dst不是空指针，转换得到的宽字符将存入参数dst指向的数组；转换直至并包括终止空字符，转换得到的终止空宽字符也会被保存。


两种情况下转换会提前终止：

1、转换遇到不能形成有效多字节字符的字节序列。

2、如果参数dst不是空指针，已有len个宽字符存入参数dst指向的数组。

注：如果参数dst是空指针，参数len值可被忽略。


每次转换都像调用一次mbrtowc函数。如果参数dst不是空指针，参数src指向的指针对象会被赋值空指针（如果转换由于到达终止空字符而停止。）或者紧跟转换的最后一个多字节字符的字符地址（如果存在。）。如果转换由于到达终止空字符而停止，并且如果参数dst不是空指针，*ps描述的结果状态将是初始转换状态。


与mbstowcs函数不同，mbsrtowcs函数存在一个额外参数ps，参数ps指向对象完整地描述了关联多字节字符序列的当前转换状态。如果参数ps是空指针，函数会使用内部mbstate_t对象，该对象在程序启动时初始化为初始转换状态；这种情况下，mbsrtowcs函数不要求避免与其它mbsrtowcs函数调用发生数据竞争。实现应像没有库函数使用ps空指针调用mbsrtowcs函数一样。

参数src是个指向指针的指针；当函数存储转换结果时（也就是说，参数dst不是空指针。），参数src指向的指针对象会更新，以反映函数调用处理的源数据的数量。

ISO/IEC 9899:2018标准定义了该函数的安全版本mbsrtowcs_s。

参数：
wchar_t * restrict dst

指向wchar_t类型数组的指针，转换得到的宽字符将存入其指向的数组中。

const char ** restrict src

间接指向被转换的多字节字符序列的指针。

size_t len

指定最多可以存储的宽字符数。

mbstate_t * restrict ps

指向mbstate_t类型对象的指针，指向的对象记录关联多字节字符序列的当前转换状态。

返回值：

如果转换遇到不能形成有效多字节字符的字节序列，将发生编码错误，函数将宏EILSEQ存入errno，并返回(size_t)(-1)，转换状态是不明确的；否则函数返回成功转换的多字节字符数，不包括终止空字符（如果存在）。

范例： 
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 
/*函数mbsrtowcs范例*/

#include <locale.h>
#include <wchar.h>

#define LENGTH 5

int main(void)
{
    setlocale(LC_ALL, "");
    
    const char *ptr = "\u7231\u6211\u4E2D\u534E";
    wchar_t wStr[LENGTH];
    static mbstate_t state;
    size_t n;
    
    /*多字节字符序列转换为宽字符序列。*/
    if((n = mbsrtowcs(wStr, &ptr, LENGTH, &state)) == (size_t)(-1))
        wprintf(L"存在不能形成有效多字节字符的字符序列。\n");
    else
        wprintf(L"%ls\n", wStr);

    return 0;
}
输出：

爱我中华

注：使用ideone编译。

相关内容：
wcsrtombs 将宽字符序列转换为多字节字符序列的函数。