wcstombs, wcstombs_s
来自cppreference.com
| 定义于头文件 <stdlib.h>
|
||
| (1) | ||
| (C99 前) | ||
| (C99 起) | ||
| errno_t wcstombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz, const wchar_t *restrict src, rsize_t len ); |
(2) | (C11 起) |
1) 转换来自首元素为
src 所指向的数组到其始于初始迁移状态的多字节表示。转换出的字符被存储于 dst 所指向的数组的相继元素。写入目标数组的字节数不多于 len 。 如同以调用 wctomb 每个字符，除了 wctomb 的转换状态不受影响。若满足下列条件则转换停止：
* 转换并存储空字符 L'\0' 。此情况下存储的字节为无迁移序列（若需要）后随 '\0' ，
* 找到当前 C 本地环境中不对应合法字符的 wchar_t 。
* 下个要存储的多字节字符会超出
len 。 若
src 与 dst 重叠，则行为未指定。2) 同 (1) ，除了
* 函数将其结果作为输出参数
retval 返回 * 若转换停止而不写入控制符，则函数将在
dst 中的下个字符，可以是 dst[len] 或 dst[dstsz] 的先到来者，存储 '\0' （表示可能写入总计至多 len+1/dsz+1 个字符）。该情况下，空终止前不写入无迁移序列。 * 若
dst 是空指针，则将本会产生的字节数存储于 *retval * 函数从空终止起到
dstsz 前为止破坏目标数组 * 若
src 与 dst 重叠，则行为未指定。 * 在运行时检测下列错误，并调用当前安装的制约处理函数：
-
retval或src是空指针 -
dstsz或len大于 RSIZE_MAX （除非dst为空） -
dstsz非零（除非dst为空） -
len大于dstsz且直到抵达dstsz时，转换未于src数组遇到空字符或编码错误（除非dst为空）
-
- 同所有边界检查函数，
wcstombs_s仅若实现定义了 __STDC_LIB_EXT1__ ，且用户在包含stdlib.h前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。
注意
大多数实现中， wcstombs 在处理过字符串时更新 mbstate_t 类型的全局静态对象，而且不能为二个线程同时调用，这种情况下应使用 wcsrtombs 或 wcstombs_s 。
POSIX 指定一个常见扩展：若 dst 是空指针，则此函数返回假设转换则会写入 dst 的字节数。类似行为对于 wcsrtombs 和 wcstombs_s 是标准。
参数
| dst | - | 指向窄字符数组的指针，其中将存储多字节字符 |
| src | - | 指向要转换的空终止宽字符串首字符的指针 |
| len | - | dst 所指向数组中的可用字节数 |
| dstsz | - | 将写入的最大字节数（ dst 数组的大小）
|
| retval | - | 指向 size_t 对象的指针，其中将存储结果 |
返回值
2) 成功时返回零（该情况下，将被或本应写入
dst 的字节数，排除终止零，存储于 *retval ），错误时返回非零。运行时制约违规的情况下，存储 (size_t)-1 于 *retval （除非 retval 为空）并设置 dst[0] 为 '\0' （除非 dst 为空或 dstmax 为零或大于 RSIZE_MAX ）。示例
运行此代码
#include <stdio.h> #include <stdlib.h> #include <locale.h> int main(void) { // 4 wide characters const wchar_t src[] = L"z\u00df\u6c34\U0001f34c"; // 它们于 UTF-8 占用 10 个字节 char dst[11]; setlocale(LC_ALL, "en_US.utf8"); printf("wide-character string: '%ls'\n",src); for (size_t ndx=0; ndx < sizeof src/sizeof src[0]; ++ndx) printf(" src[%2zu] = %#8x\n", ndx, src[ndx]); int rtn_val = wcstombs(dst, src, sizeof dst); printf("rtn_val = %d\n", rtn_val); if (rtn_val > 0) printf("multibyte string: '%s'\n",dst); for (size_t ndx=0; ndx<sizeof dst; ++ndx) printf(" dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]); }
输出：
wide-character string: 'zß水🍌' src[ 0] = 0x7a src[ 1] = 0xdf src[ 2] = 0x6c34 src[ 3] = 0x1f34c src[ 4] = 0 rtn_val = 10 multibyte string: 'zß水🍌' dst[ 0] = 0x7a dst[ 1] = 0xc3 dst[ 2] = 0x9f dst[ 3] = 0xe6 dst[ 4] = 0xb0 dst[ 5] = 0xb4 dst[ 6] = 0xf0 dst[ 7] = 0x9f dst[ 8] = 0x8d dst[ 9] = 0x8c dst[10] = 0
引用
- C11 standard (ISO/IEC 9899:2011):
- 7.22.8.2 The wcstombs function (p: 360)
- K.3.6.5.2 The wcstombs_s function (p: 612-614)
- C99 standard (ISO/IEC 9899:1999):
- 7.20.8.2 The wcstombs function (p: 324)
- C89/C90 standard (ISO/IEC 9899:1990):
- 4.10.8.2 The wcstombs function
参阅
| (C95)(C11) |
给定状态，将宽字符串转换成窄多字节字符串 (函数) |
| (C11) |
将窄多字节字符串转换成宽字符串 (函数) |
