mbstowcs, mbstowcs_s
来自 cppreference.cn
| 定义于头文件 <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ß水🍌
