mbsrtowcs, mbsrtowcs_s
来自cppreference.com
| 定义于头文件 <wchar.h>
|
||
| (1) | ||
| (C95 起) (C99 前) |
||
| (C99 起) | ||
| (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 standard (ISO/IEC 9899:2011):
- 7.29.6.4.1 The mbsrtowcs function (p: 445)
- K.3.9.3.2.1 The mbsrtowcs_s function (p: 648-649)
- C99 standard (ISO/IEC 9899:1999):
- 7.24.6.4.1 The mbsrtowcs function (p: 391)
参阅
| (C11) |
将窄多字节字符串转换成宽字符串 (函数) |
| (C95) |
给定状态，将下一个多字节字符转换成宽字符 (函数) |
| (C95)(C11) |
给定状态，将宽字符串转换成窄多字节字符串 (函数) |
