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 指向的 char 数组的连续元素中。写入目标数组的字节数不超过 len 个。 每个字符的转换方式就像调用了 wctomb 一样，除了 wctomb 的转换状态不受影响。如果满足以下条件，则转换停止：
* 空字符 L'\0' 已转换并存储。在这种情况下存储的字节是未移位序列（如果需要）后跟 '\0'，
* 找到一个 wchar_t，它与当前 C 本地化中的有效字符不对应。
* 要存储的下一个多字节字符将超过
len。 如果
src 和 dst 重叠，则行为未定义。2) 与 (1) 相同，除了：
* 该函数将其结果作为输出参数
retval 返回 * 如果转换在没有写入空字符的情况下停止，则该函数将在
dst 中的下一个字节中存储 '\0'，该字节可能是 dst[len] 或 dst[dstsz]，以先到者为准（意味着最多可以写入 len+1/dstsz+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"; // they occupy 10 bytes in UTF-8 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
