当前位置： C语言 -- 附录 -- wcrtomb_s

wcrtomb_s函数

概要： 
#define __STDC_WANT_LIB_EXT1__ 1
#include <wchar.h>
errno_t wcrtomb_s(size_t * restrict retval,
      char * restrict s, rsize_t smax,
      wchar_t wc, mbstate_t * restrict ps);
描述：

该函数确定表示与参数wc对应的多字节字符所需的字节数（包括移位序列），并将多字节字符的表示形式存入参数s指向的数组。

如果参数s是空指针，wcrtomb_s函数等价于

wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps)

其中retval和buf为内部变量，并且buf应大于宏MB_CUR_MAX。


如果参数s不是空指针，函数确定表示与参数wc指定的宽字符对应的多字节字符所需的字节数（包括移位序列），并将多字节字符的表示形式存储到参数s指向的数组中。最多可以存入MB_CUR_MAX个字节。如果参数wc是空宽字符，将存入空字节，该空字节会被前置用以恢复初始移位状态（initial shift state）所需的移位序列，结果状态是初始转换状态。


如果参数wc没有对应的有效多字节字符，将发生编码错误，函数向*retval中存入值(size_t)(-1)，并且转换状态是不确定的；否则函数向*retval中存入存储到参数s指向数组的字节数（包括移位序列）。

运行约束：

参数retval和参数ps不能是空指针。如果参数s不是空指针，参数smax应不等于0且不大于宏RSIZE_MAX。如果参数s不是空指针，参数smax应不小于存入参数s指向数组的字节数。如果参数s是空指针，参数smax应等于0。

如果存在运行约束冲突，wcrtomb_s函数执行以下操作：如果参数retval不是空指针，函数将*retval设置为(size_t)(-1)；如果参数s不是空指针，并且参数smax大于0且不大于宏RSIZE_MAX，函数将s[0]设置为空字符。

参数：
size_t * restrict retval

指向size_t类型对象的指针，指向的对象存储对应的多字节字符的字节数。

char * restrict s

指向数组的指针，指向数组应足以容纳对应的多字节字符。当前语言环境多字节字符的最大字节数为MB_CUR_MAX。

rsize_t smax

参数s指向数组可以访问的最大字节数。

wchar_t wc

wchar_t类型的宽字符。

mbstate_t * restrict ps

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

返回值：

如果不存在运行约束冲突和编码错误，函数返回0；否则函数返回非0值。

范例： 
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 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
/*安全函数wcrtomb_s范例*/

#define __STDC_WANT_LIB_EXT1__ 1
#include <locale.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>

#define LENGTH 100

int main(void)
{
    setlocale(LC_ALL, "");

    mbstate_t state;
    wchar_t wStr[] = L"中华儿女";
    char temp[LENGTH];
    char *ptr = temp;
    size_t retval;

    memset(&state, 0, sizeof(state));

    /*转换前。*/
    puts("转换前：");
    for(size_t i=0; i<sizeof(wStr)/sizeof(wchar_t); ++i)
        printf("%#X ", (unsigned int)wStr[i]);
    puts("");

    /*宽字符转换为多字节字符。*/
    for(size_t i=0; i<sizeof(wStr)/sizeof(wchar_t); ++i)
    {
        wcrtomb_s(&retval, ptr, LENGTH, wStr[i], &state);
        if(retval == (size_t)(-1))
        {
            puts("非法序列。");
            exit(EXIT_FAILURE);
        }
        ptr += retval;
    }

    /*转换后。*/
    puts("转换后：");
    for(ptrdiff_t i=0; i<(ptr - temp); ++i)
        printf("%#X ", (unsigned char)temp[i]);
    puts("");
    
    return 0;
}
输出：

转换前：

0X4E2D 0X534E 0X513F 0X5973 0

转换后：

0XD6 0XD0 0XBB 0XAA 0XB6 0XF9 0XC5 0XAE 0

注：使用Visual Studio编译。

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