mbstowcs, mbstowcs_s
来自 cppreference.com
| 定义在头文件 <stdlib.h> 中 |
||
| (1) | ||
| (直到 C99) | ||
| (自 C99) | ||
| errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrict dst, rsize_t dstsz, const char *restrict src, rsize_t len); |
(2) | (自 C11) |
1) 将从其第一个元素由
src 指向的数组中获取的多字节字符字符串转换为其宽字符表示形式。转换后的字符存储在由 dst 指向的数组的连续元素中。写入目标数组的宽字符数不超过 len。 每个字符的转换方式与调用 mbtowc 相同，但 mbtowc 转换状态不受影响。转换在以下情况下停止：
* 转换并存储了多字节空字符。
* 遇到了无效的（在当前 C 本地化中）多字节字符。
* 要存储的下一个宽字符将超过
len。 如果
src 和 dst 重叠，则行为未定义。2) 与 (1) 相同，但
* 函数将其结果作为输出参数
retval 返回。 * 如果在写入
len 个宽字符后未将空字符写入 dst，则将 L'\0' 存储在 dst[len] 中，这意味着总共写入 len+1 个宽字符。 * 如果
dst 是一个空指针，则将要生成的宽字符数存储在 *retval 中。 * 函数从终止的空字符开始一直到
dstsz 对目标数组进行覆盖。 * 如果
src 和 dst 重叠，则行为未指定。 * 以下错误在运行时检测到并调用当前安装的 约束处理程序 函数。
-
retval或src是空指针。 -
dstsz或len大于 RSIZE_MAX/sizeof(wchar_t)（除非dst为空）。 -
dstsz不为零（除非dst为空）。 src数组中前dstsz个多字节字符中没有空字符，并且len大于dstsz（除非dst为空）。
-
- 与所有边界检查函数一样，仅当实现定义了 __STDC_LIB_EXT1__ 且用户在包含 <stdlib.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时，才保证
mbstowcs_s可用。
内容 |
[编辑] 注释
在大多数实现中，mbstowcs 会更新类型为 mbstate_t 的全局静态对象，因为它会处理整个字符串，并且不能被两个线程同时调用，在这种情况下应使用 mbsrtowcs。
POSIX 指定了一个常见扩展：如果 dst 是一个空指针，则此函数将返回将写入 dst 的宽字符数（如果转换）。类似的行为在 mbstowcs_s 和 mbsrtowcs 中是标准的。
[编辑] 参数
| dst | - | 指向将存储宽字符串的宽字符数组的指针。 |
| src | - | 指向要转换的以空字符结尾的多字节字符串的第一个元素的指针。 |
| len | - | 由 dst 指向的数组中可用的宽字符数。 |
| dstsz | - | 将要写入的最大宽字符数（dst 数组的大小）。 |
| retval | - | 指向将存储结果的 size_t 对象的指针。 |
[编辑] 返回值
2) 成功时为零（在这种情况下，将要写入（或将要写入）
dst 的宽字符数（不包括终止的零）存储在 *retval 中），错误时为非零值。在发生运行时约束冲突的情况下，将在 *retval 中存储 (size_t)-1（除非 retval 为空），并将 dst[0] 设置为 L'\0'（除非 dst 为空或 dstmax 为零或大于 RSIZE_MAX）。[编辑] 示例
运行此代码
#include <stdio.h> #include <locale.h> #include <stdlib.h> #include <wchar.h> int main(void) { setlocale(LC_ALL, "en_US.utf8"); const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌" wchar_t wstr[5]; mbstowcs(wstr, mbstr, 5); wprintf(L"MB string: %s\n", mbstr); wprintf(L"Wide string: %ls\n", wstr); }
输出
MB string: zß水🍌 Wide string: zß水🍌
[编辑] 参考
- C11 标准 (ISO/IEC 9899:2011)
- 7.22.8.1 mbstowcs 函数 (p: 359)
- K.3.6.5.1 mbstowcs_s 函数 (p: 611-612)
