wcstombs_s函数
概要:
#define __STDC_WANT_LIB_EXT1__ 1 #include <stdlib.h> errno_t wcstombs_s(size_t * restrict retval, char * restrict dst, rsize_t dstmax, const wchar_t * restrict src, rsize_t len);
描述:
该函数将参数src指向数组中的宽字符序列转换为以初始移位状态(initial shift state)开始的对应多字节字符序列。如果参数dst不是空指针,转换后的字符将存储到参数dst指向的数组。转换持续至终止空宽字符(包括终止空宽字符)。
两种情况下转换会提前终止:
1、遇到没有对应有效多字节字符的宽字符。
2、如果参数dst不是空指针,下一个多字节字符将超出存储到参数dst指向数组的n个总字节的限制。(如果转换宽字符是空宽字符,n是len和dstmax中的较小者;否则n是len和dstmax-1中的较小者。)
如果参数dst不是空指针并且在没有转换空宽字符的情况下转换终止,函数将向已存储到参数dst指向数组的多字节字符后添加空字符。每次转换都像是调用wcrtomb函数。如果转换是由于到达终止空宽字符而停止,存储的字节包括空字节前到达初始转换状态所需的字节;如果到达终止空宽字符前停止转换,结果将以空字符终止,但可能不会以初始转换状态结束。
无论参数dst是否为空指针,如果输入转换遇到没有对应有效多字节字符的宽字符,将发生编码错误,函数将(size_t)(-1)存储到*retval;否则函数将生成的多字节字符序列的字节数(不包括终止空字符)存储到*retval。
wcstombs_s函数返回时,参数dst指向的数组中wcstombs_s函数写入的终止空字符(如果有)之后的所有元素值都是未指定的。
如果复制发生在重叠对象之间,元素值是不确定的。
wcstombs_s函数会受当前语言环境LC_CTYPE类别的影响。
运行约束:
参数retval和参数src不能是空指针。如果参数dst不是空指针,参数len应不大于RSIZE_MAX/sizeof(wchar_t),参数dstmax应为非0值,且不大于宏RSIZE_MAX。如果参数dst是空指针,参数dstmax应等于0。如果参数dst不是空指针,并且参数len不小于参数dstmax,当遇到终止空宽字符或者发生编码错误时函数会停止转换。
如果存在运行约束冲突,wcstombs_s函数执行以下操作:如果参数retval不是空指针,函数将*retval设置为(size_t)(-1);如果参数dst不是空指针,并且参数dstmax大于0且不大于RSIZE_MAX,函数将dst[0]设置为空字符。
参数:
指向size_t类型对象的指针,指向的对象存储转换得到的多字节字符序列的字节数。
指向char类型数组的指针,转换得到的多字节字符将存入该数组中。
参数dst指向数组可以写入多字节字符序列的最大字节数。
指向宽字符序列的指针。
存入数组的多字节字符序列的最大字节数。
返回值:
如果不存在运行约束冲突或者编码错误,函数返回0;否则函数返回非0值。
范例:
|
|
输出:
转换前宽字符序列(不包括终止空宽字符)共4个宽字符,各个宽字符的值分别是:
4E2D 534E 513F 5973
转换后得到的多字节字符序列占有8个字节,各个字节的值分别是:
D6 D0 BB AA B6 F9 C5 AE
注:使用Visual Studio编译。
相关内容:
wcstombs | 将宽字符序列转换为多字节字符序列的函数。 |
mbstowcs_s | 将多字节字符序列转换为宽字符序列的安全函数。 |
wctomb_s | 将宽字符转换为多字节字符序列的安全函数。 |
wcrtomb | 将宽字符转换为多字节字符序列的函数。 |