mbsrtowcs, mbsrtowcs_s

在标头 `<wchar.h>` 定义
	(1)
size_t mbsrtowcs( wchar_t* dst, const char** src, size_t len, mbstate_t* ps );			(C95 起) (C99 前)
size_t mbsrtowcs( wchar_t restrict dst, const char 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, const char *restrict src, rsize_t len, mbstate_t restrict ps);		(2)	(C11 起)

1) 转换始于 *ps 所描述的转换状态，来自首元素为 *src 所指向的数组的空终止多字节字符序列，到其宽字符表示。若 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(const char* 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"Wide string: %ls \n", wstr);
    wprintf(L"The length, including L'\\0': %d\n", len);
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_as_wide(u8"z\u00df\u6c34\U0001f34c"); // u8"zß水🍌"
}

输出：

Wide string: zß水🍌
The length, including 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)	给定状态，将宽字符串转换成窄多字节字符串 (函数)

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

mbsrtowcs, mbsrtowcs_s

参数

返回值

示例

引用

参阅

导航