mbstowcs_s函数

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
errno_t mbstowcs_s(size_t * restrict retval,
      wchar_t * restrict dst, rsize_t dstmax,
      const char * restrict src, rsize_t len);

该函数将参数src指向数组中的以初始移位状态（initial shift state）开始的多字节字符序列转换为对应的宽字符序列。如果参数dst不是空指针，转换后的宽字符序列将存储到参数dst指向的数组中。转换持续至终止空字符（包括终止空字符）。

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

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

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

如果参数dst不是空指针，并且没有空宽字符存储到参数dst指向的数组，函数将dst[len]设置为空宽字符。每次转换都像是调用mbrtowc函数。

无论参数dst是否为空指针，如果输入转换遇到不能形成有效多字节字符的字节序列，将发生编码错误，函数将(size_t)(-1)存储到*retval；否则函数将成功转换的多字节字符数（不包括终止空字符）存储到*retval。

mbstowcs_s函数返回时，参数dst指向的数组中mbstowcs_s函数写入的终止空宽字符（如果有）之后的所有元素值都是未指定的。

如果复制发生在重叠对象之间，元素值是不确定的。

mbstowcs_s函数会受当前语言环境LC_CTYPE类别的影响。

参数retval和参数src不能是空指针。如果参数dst不是空指针，参数len和参数dstmax应不大于RSIZE_MAX/sizeof(wchar_t)。如果参数dst是空指针，参数dstmax应等于0。如果参数dst不是空指针，参数dstmax应不等于0。如果参数dst不是空指针，并且参数len不小于参数dstmax，空字符应出现在参数src指向数组的前dstmax个多字节字符中。

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

指向size_t类型对象的指针，指向的对象存储成功转换的多字节字符数。

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

参数dst指向数组可以写入宽字符的最大数量。

指向多字节字符序列的指针。

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

如果不存在运行约束冲突和编码错误，函数返回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 

/*安全函数mbstowcs_s范例*/

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

#define LENGTH 20

int main(void)
{
    setlocale(LC_ALL, "");
    
    const char str[] = "神州大地";
    wchar_t wStr[LENGTH];
    size_t retval;
    int i = 0;

    /*多字节字符序列转换成宽字符序列前。*/
    printf_s("多字节字符序列（不包括终止空字符）");
    printf_s("转换前占有%zu个字节，", strlen(str));
    printf_s("各个字节的值分别是：\n");
    while(str[i] != 0)
    {
        printf_s("%0X ", (unsigned char)str[i++]);
    }
    puts("");

    /*多字节字符序列转换成宽字符序列后。*/
    if(!mbstowcs_s(&retval, wStr, sizeof(wStr)/sizeof(wchar_t), str, LENGTH))
        printf_s("转换后得到%zu个宽字符，各个宽字符的值分别是：\n", retval-1);
    
    for(size_t i=0; i<retval-1; ++i)
    {
        printf_s("%X ", wStr[i]);
    }
    puts("");

    return 0;
}

注：使用Visual Studio编译。