mbsrtowcs, mbsrtowcs_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 mbsrtowcs(wchar_t* dst, constchar** src, size_t len, mbstate_t* ps );			(C95 起) (C99 前)
size_t mbsrtowcs(wchar_t*restrict dst, constchar**restrict src, size_t len,                   mbstate_t*restrict ps );			(C99 起)
errno_t mbsrtowcs_s(size_t*restrict retval,                      wchar_t*restrict dst, rsize_t dstsz,                      constchar**restrict src, rsize_t len,                      mbstate_t*restrict ps);		(2)	(C11 起)

1) 将来自首元素为 *src 所指向的数组的空终止多字节字符序列（它始于 *ps 所描述的转换状态），转换为其宽字符表示。若 dst 非空，则存储转换后的字符于 dst 所指向的 wchar_t 数组的相继元素。不会向目标数组写入多于 len 个宽字符。如同以调用 mbrtowc 一样转换每个多字节字符。若满足下列条件则转换终止：

• 转换并存储了多字节空字符。设置 *src 为空指针值并令 *ps 表示初始迁移状态。
• 遇到任何非法多字节字符（按照当前 C 本地环境）。设置 *src 指向首个未转换的多字节字符的起始。
• 将存储的下个宽字符将超出 len。设置 *src 指向首个未转换的多字节字符的起始。若 dst 为空指针则不检查此条件。

2) 同 (1)，但

• 函数以输出参数 retval 返回其结果
• 若在写入 len 个宽字符后未写入宽字符到 dst，则存储 L'\0' 于 dst[len]，这表示写入总计 len+1 个宽字符
• 函数破坏从空终止符到 dstsz 之间的目标数组内容
• 若 src 与 dst 重叠，则行为未指定。
• 在运行时检测下列错误并调用当前安装的制约处理函数：

• retval、ps、src 或 *src 为空指针
• dstsz 或 len 大于 RSIZE_MAX/sizeof(wchar_t)（除非 dst 为空）
• dstsz 非空（除非 dst 为空）
• *src 数组中的前 dstsz 个多字节字符中无空字符，且 len 大于 dstsz（除非 dst 为空）

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

参数

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

返回值

1) 成功时返回写入字符数组的宽字符数，排除终止的 L'\0'。若 dst 为空指针，则返回假如给定无限定长度则本会写入的宽字符数。转换错误时（若遇到非法多字节字符）返回 (size_t)-1，存储 EILSEQ 于 errno，并令 *ps 留在未指定状态。

2) 成功时为零（该情况下将写入或本会写入 dst 的宽字符数存储于 *retval），错误时为非零。在运行时制约违规的情况下，存储 (size_t)-1 于 *retval（除非 retval 为空）并设置 dst[0] 为 L'\0'（除非 dst 为空或者 dstmax 为零或大于 RSIZE_MAX）。

示例

运行此代码

#include <stdio.h>#include <locale.h>#include <wchar.h>#include <string.h>   void print_as_wide(constchar* mbstr){mbstate_t state;memset(&state, 0, sizeof state);size_t len =1+ mbsrtowcs(NULL, &mbstr, 0, &state);wchar_t wstr[len]; mbsrtowcs(&wstr[0], &mbstr, len, &state);wprintf(L"宽字符串：%ls \n", wstr);wprintf(L"含 L'\\0' 长度：%d\n", len);}   int main(void){setlocale(LC_ALL, "en_US.utf8"); print_as_wide(u8"z\u00df\u6c34\U0001f34c");// u8"zß水🍌"}

输出：

宽字符串：zß水🍌 含 L'\0' 长度：5

引用

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

• 7.29.6.4.1 The mbsrtowcs function （第 445 页）

• K.3.9.3.2.1 The mbsrtowcs_s function （第 648-649 页）

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

• 7.24.6.4.1 The mbsrtowcs function （第 391 页）

参阅

mbstowcsmbstowcs_s (C11)	转换窄多字节字符串为宽字符串 (函数)
mbrtowc (C95)	给定状态，转换下一个多字节字符为宽字符 (函数)
wcsrtombswcsrtombs_s (C95)(C11)	给定状态，转换宽字符串为窄多字节字符串 (函数)
mbsrtowcs 的 C++ 文档