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
为空)
-
- 同所有边界检查函数,
mbstowcs_s
仅若实现定义了 __STDC_LIB_EXT1__ ,且用户在包含stdlib.h
前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。
注意
多数实现中, mbstowcs
更新 mbstate_t 类型的全局静态对象,因为它通过字符串处理,而且不能由二个线程同时调用, mbsrtowcs 应当用于这种情况。
POSIX 指定一个常见扩展:若 dst
是空指针,则此函数返回假若转换则写入 dst
的宽字符数。同样的行为对于 mbstowcs_s
和 mbsrtowcs 是标准。
参数
dst | - | 指向要存储宽字符串的宽字符数组的指针 |
src | - | 指向要转换的空终止多字节字符串的首元素的指针 |
len | - | dst 所指向的数组中的可用宽字节数 |
dstsz | - | 将写入的最大宽字节数( dst 数组的大小)
|
retval | - | 指向将存储结果的 size_t 对象的指针 |
返回值
2) 成功时为零(该情况下写入或本该写入到
dst
的不含终止零的宽字符存储于 *retval ),错误时为非零,在运行时制约违规的情况,存储 (size_t)-1 于 *retval (除非 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 The mbstowcs function (p: 359)
- K.3.6.5.1 The mbstowcs_s function (p: 611-612)
- C99 标准(ISO/IEC 9899:1999):
- 7.20.8.1 The mbstowcs function (p: 323)
- C89/C90 标准(ISO/IEC 9899:1990):
- 4.10.8.1 The mbstowcs function
参阅
(C95)(C11) |
给定状态,将窄多字节字符串转换成宽字符串 (函数) |
(C11) |
将宽字符串转换成窄多字节字符串 (函数) |