mbstowcs, mbstowcs_s

 

C

编译器支持

语言

头文件

类型支持

程序工具

变参数函数支持

错误处理

动态内存管理

字符串库

算法

数值

日期和时间工具

输入/输出支持

本地化支持

并发支持 (C11)

技术规范

符号索引

 

字符串库

字节字符串

多字节字符串

宽字符串

 

空终止多字节字符串

宽/多字节转换
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)     mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
类型
mbstate_t (C95)

 

在标头 <stdlib.h> 定义
	(1)
size_t mbstowcs( wchar_t          *dst, const char          *src, size_t len)			(C99 前)
size_t mbstowcs( wchar_t *restrict dst, const char *restrict src, size_t len)			(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)，但

* 如同以 mbrtowc，而非 mbtowc 进行转换

* 函数用输出参数 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 对象的指针，将存储结果

返回值

1) 成功时，返回目标数组的宽字符数，不含终止符 L'\0'。转换错误时（若遇到非法多字节字符），返回 (size_t)-1。

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 （第 359 页）

• K.3.6.5.1 The mbstowcs_s function （第 611-612 页）

• C99 标准（ISO/IEC 9899:1999）：

• 7.20.8.1 The mbstowcs function （第 323 页）

• C89/C90 标准（ISO/IEC 9899:1990）：

• 4.10.8.1 The mbstowcs function

参阅

mbsrtowcsmbsrtowcs_s (C95)(C11)	给定状态，将窄多字节字符串转换成宽字符串 (函数)
wcstombswcstombs_s (C11)	将宽字符串转换成窄多字节字符串 (函数)