wcsrtombs, wcsrtombs_s

定义在头文件 `<wchar.h>` 中
	(1)
size_t wcsrtombs( char dst, const wchar_t src, size_t len, mbstate_t ps );			(自 C95 起) (直到 C99)
size_t wcsrtombs( char restrict dst, const wchar_t restrict src, size_t len, mbstate_t restrict ps );			(自 C99 起)
errno_t wcsrtombs_s( size_t restrict retval, char restrict dst, rsize_t dstsz, const wchar_t *restrict src, rsize_t len, mbstate_t restrict ps );		(2)	(自 C11 起)

1) 将由 *src 指向的第一个元素指向的数组中的宽字符序列转换为其窄多字节表示形式，该表示形式以 *ps 描述的转换状态开头。如果 dst 不为空，则转换后的字符将存储在 dst 指向的 char 数组的连续元素中。写入目标数组的字节数不超过 len。每个字符的转换方式与调用 wcrtomb 相同。转换将在以下情况下停止：

空字符 L'\0' 已转换并存储。在这种情况下存储的字节是未移位序列（如果需要）后跟 '\0'，*src 设置为 null 指针值，*ps 表示初始移位状态。
找到一个 wchar_t 不对应于当前 C 本地化中的有效字符。 *src 设置为指向第一个未转换的宽字符。
要存储的下一个多字节字符将超过 len。 *src 设置为指向第一个未转换的宽字符。如果 dst 是一个空指针，则不会检查此条件。

2) 与 (1) 相同，但

该函数将其结果作为输出参数 retval 返回
如果转换在没有写入空字符的情况下停止，该函数将在 dst 中的下一个字节中存储 '\0'，该字节可能是 dst[len] 或 dst[dstsz]，以先到者为准（意味着最多可以写入 len+1/dstsz+1 个总字节）。在这种情况下，在终止 null 之前可能没有写入任何未移位序列。
该函数从终止 null 到 dstsz 覆盖目标数组。
如果 src 和 dst 重叠，行为是不确定的。
以下错误在运行时被检测到，并调用当前安装的约束处理程序函数

retval、ps、src 或 *src 是一个空指针
dstsz 或 len 大于 RSIZE_MAX（除非 dst 为空）
dstsz 不为零（除非 dst 为空）
len 大于 dstsz 并且转换在达到 dstsz 时在 src 数组中没有遇到空值或编码错误（除非 dst 为空）

与所有带边界检查的函数一样，仅当实现定义了 __STDC_LIB_EXT1__ 并且用户在包含 <wchar.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时，wcsrtombs_s 才保证可用。

[编辑] 参数

dst	-	指向将存储多字节字符的窄字符数组的指针
src	-	指向指向以空字符结尾的宽字符串的第一个元素的指针的指针
len	-	`dst` 指向的数组中可用的字节数
ps	-	指向转换状态对象的指针
dstsz	-	将写入的最大字节数（`dst` 数组的大小）
retval	-	指向将存储结果的 size_t 对象的指针

[编辑] 返回值

1) 成功时，返回写入指向 dst 的第一个元素的字符数组的字节数（包括任何移位序列，但不包括终止的 '\0'）。如果 dst 是一个空指针，则返回将要写入的字节数。如果转换错误（如果遇到无效的宽字符），则返回 (size_t)-1，将 EILSEQ 存储在 errno 中，并将 *ps 保留在不确定的状态。

2) 成功时返回零（在这种情况下，写入 dst 的字节数（不包括终止零）将存储在 *retval 中），错误时返回非零值。如果发生运行时约束违规，则将 (size_t)-1 存储在 *retval 中（除非 retval 为空），并将 dst[0] 设置为 '\0'（除非 dst 为空或 dstmax 为零或大于 RSIZE_MAX）

[编辑] 示例

运行此代码

#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
 
void print_wide(const wchar_t* wstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state);
    char mbstr[len];
    wcsrtombs(mbstr, &wstr, len, &state);
    printf("Multibyte string: %s\n", mbstr);
    printf("Length, including '\\0': %zu\n", len);
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001f34c"); // or L"zß水🍌"
}

输出

Multibyte string: zß水🍌
Length, including '\0': 11

[编辑] 参考文献

C17 标准 (ISO/IEC 9899:2018)

7.29.6.4.2 wcsrtombs 函数 (p: 324-325)

K.3.9.3.2.2 wcsrtombs_s 函数 (p: 471-472)

C11 标准 (ISO/IEC 9899:2011)

7.29.6.4.2 wcsrtombs 函数 (p: 446)

K.3.9.3.2.2 wcsrtombs_s 函数 (p: 649-651)

C99 标准 (ISO/IEC 9899:1999)

7.24.6.4.2 wcsrtombs 函数 (p: 392)

[编辑] 另请参阅

wcstombswcstombs_s (C11)	将宽字符串转换为窄多字节字符字符串 (函数) [编辑]
wcrtombwcrtomb_s (C95)(C11)	将宽字符转换为其多字节表示形式，给定状态 (函数) [编辑]
mbsrtowcsmbsrtowcs_s (C95)(C11)	将窄多字节字符字符串转换为宽字符串，给定状态 (函数) [编辑]
C++ 文档 for wcsrtombs

编译器支持
语言
头文件
类型支持
程序工具
可变参数函数支持
错误处理
动态内存管理
字符串库
算法
数值
日期和时间工具
输入/输出支持
本地化支持
并发支持 (C11)
技术规范
符号索引

cppreference.com

命名空间

变体

视图

操作