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 所指向的字符数组的相接元素。不写入多于 len 个字节到目标数组。如同以调用 wcrtomb 转换每个字符。若遇到下列条件则停止转换：

转换并存储了空字符 L'\0'。此情况下存储的各字节为反迁移序列（若需要）后随 '\0'，设置 *src 为空指针值并令 *ps 表示初始迁移状态。
找到当前 C 本地环境中不对应合法字符的 wchar_t。设置 *src 指向首个未转换的宽字符。
下个多字节字符将超出 len。设置 *src 指向首个未转换的宽字符。若 dst 为空指针则不检查此条件。

2) 同 (1)，但

函数返回其结果为输出参数 retval
若转换停止而不写入空字符，则函数将存储 '\0' 于 dst 的下个字节，它可以是 dst[len] 或 dst[dstsz]，两者的先到来者（表示总共可能写入 len+1/dstsz+1 字节）。此情况下，在终止空字符前可以无反迁移序列。
函数破坏目标数组中从终止空字符 dstsz 到 dstsz 的内容
若 src 与 dst 重叠，则行为未指定。
在运行时检测下列错误并调用当前安装的制约处理函数：

retval、ps、src 或 *src 为空指针
dstsz 或 len 大于 RSIZE_MAX（除非 dst 为空）
dstsz 非零（除非 dst 为空）
len 大于 dstsz 且转换在抵达 dstsz 时于 src 数组中未遇到空字符或编码错误（除非 dst 为空）

同所有边界检查函数，wcsrtombs_s，仅若实现定义 __STDC_LIB_EXT1__ 且用户在包含 <wchar.h> 前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。

参数

dst	-	指向窄字符数组的指针，其中将存储多字节字符
src	-	指向指向空终止宽字符串首元素的指针的指针
len	-	`dst` 所指向的数组中可用的字节数
ps	-	指向转换状态对象的指针
dstsz	-	将写入的最大字节数（ `dst` 数组的大小）
retval	-	指向将存储结果于其中的 `size_t` 对象的指针

返回值

1) 成功时，返回写入首元素为 dst 所指向的字符数组的字节数（包含任何迁移序列，但不包含终止 '\0'）。若 ds 为空指针，则返回本会写入的字节数。错误时（若遇到非法宽字符），返回 (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': %d\n", len);
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001f34c"); // 或 L"zß水🍌"
}

输出：

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

引用

C17 标准（ISO/IEC 9899:2018）：

7.29.6.4.2 The wcsrtombs function （第 324-325 页）

K.3.9.3.2.2 The wcsrtombs_s function （第 471-472 页）

C11 标准（ISO/IEC 9899:2011）：

7.29.6.4.2 The wcsrtombs function （第 446 页）

K.3.9.3.2.2 The wcsrtombs_s function （第 649-651 页）

C99 标准（ISO/IEC 9899:1999）：

7.24.6.4.2 The wcsrtombs function （第 392 页）

参阅

wcstombswcstombs_s (C11)	将宽字符串转换成窄多字节字符串 (函数)
wcrtombwcrtomb_s (C95)(C11)	给定状态，将宽字符转换成其多字节表示 (函数)
mbsrtowcsmbsrtowcs_s (C95)(C11)	给定状态，将窄多字节字符串转换成宽字符串 (函数)

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

wcsrtombs, wcsrtombs_s

参数

返回值

示例

引用

参阅

导航