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

wcsrtombs函数

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

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


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

1、转换遇到没有对应有效多字节字符的宽字符。

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

每次转换都像是调用一次wcrtomb函数。（注：如果转换因为到达终止空宽字符而停止，存储的字节包括空字节前为达到初始移位状态所需的字节。）


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


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

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

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

参数：
char * restrict dst

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

const wchar_t ** restrict src

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

size_t len,

指定存入参数dst指向数组的多字节字符的总字节数。

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 
26 
27 
28 
29 
30 
31 
/*函数wcsrtombs范例*/

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

#define LENGTH 15

int main(void)
{
    setlocale(LC_ALL, "");
    
    const wchar_t *wStr = L"后生可畏";
    char str[LENGTH];
    static mbstate_t state;
    size_t n;

    /*宽字符序列转换为多字节字符序列。*/
    if((n = wcsrtombs(str, &wStr, LENGTH, &state)) == (size_t)(-1))
    {
        wprintf(L"遇到没有对应有效多字节字符的宽字符。\n");
        exit(EXIT_FAILURE);
    }
    
    for(size_t i=0; i<n; ++i)
        wprintf(L"%#X ", (unsigned char)str[i]);
    wprintf(L"\n");
        
    return 0;
}
输出：

0XE5 0X90 0X8E 0XE7 0X94 0X9F 0XE5 0X8F 0XAF 0XE7 0X95 0X8F

注：使用ideone编译。


后生可畏的UTF-8编码分别为E5 90 8E、E7 94 9F、E5 8F AF、E7 95 8F。

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