wcsrtombs, wcsrtombs_s

 

C

编译器支持

语言

头文件

类型支持

程序工具

变参函数支持

错误处理

动态内存管理

字符串库

算法

数值

日期和时间工具

输入/输出支持

本地化支持

并发支持 (C11)

技术规范

符号索引

 

字符串库

空终止字节字符串

空终止多字节字符串

空终止宽字符串

 

空终止多字节字符串

函数
宽字符/多字节转换
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)   mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
类型
mbstate_t (C95) char8_t (C23)	char16_t (C11) char32_t (C11)
宏
MB_LEN_MAX	MB_CUR_MAX

 

在头文件 <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 不为 null，则转换后的字符存储在 dst 指向的 char 数组的连续元素中。写入目标数组的字节数不超过 len。每个字符都像通过调用 wcrtomb 转换一样。转换停止，如果

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

2) 与(1)相同，但：

• 函数将其结果作为输出参数 retval 返回。
• 如果转换停止而未写入空字符，函数将在 dst 中的下一个字节（可能是 dst[len] 或 dst[dstsz]，以先到达者为准，这意味着最多可写入 len+1/dstsz+1 总字节）中存储 '\0'。在这种情况下，在终止空字符之前可能没有写入解除移位序列。
• 函数从终止空字符开始，直到 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)	将宽字符串转换为窄多字节字符字符串 (function)
wcrtombwcrtomb_s (C95)(C11)	将宽字符转换为其多字节表示，给定状态 (function)
mbsrtowcsmbsrtowcs_s (C95)(C11)	将窄多字节字符字符串转换为宽字符串，给定状态 (function)
C++ 文档 for wcsrtombs