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 不为空，则转换后的字符存储在 dst 指向的 char 数组的后续元素中。写入目标数组的字节数不超过 len。每个字符都如同调用 wcrtomb 一样进行转换。转换在以下情况下停止：

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

2) 与 (1) 相同，除了

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

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

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

参数

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

返回值

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

2) 成功时返回零（在这种情况下，写入或将要写入 dst 的字节数（不包括终止零）存储在 *retval 中），错误时返回非零值。如果发生运行时约束冲突，则在 *retval 中存储 (size_t)-1（除非 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