C 参考手册

位置:首页 > C 参考手册 >字符串库 >空终止多字节字符串 > mbstowcs, mbstowcs_s

定义于头文件 <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
srcdst 重叠,则行为未定义
2)(1) ,除了
* 转换如同以 mbrtowc ,而非 mbtowc
* 函数用输出参数 retval 返回结果
* 若在写入 len 个宽字符后未写入空字符到 dst ,则存储 L'\0'dst[len] ,这表示总计写入 len+1 个宽字符
* 若 dst 是空指针,则存储本会产生的宽字符数于 *retval
* 函数从空终止到 dstsz 为止破坏目标数组
* 若 srcdst 重叠,则行为未指定。
* 在运行时检测下列错误,并调用当前安装的制约处理函数:
  • retvalsrc 是空指针
  • dstszlen 大于 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_smbsrtowcs 是标准。

参数

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 standard (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 standard (ISO/IEC 9899:1999):
  • 7.20.8.1 The mbstowcs function (p: 323)
  • C89/C90 standard (ISO/IEC 9899:1990):
  • 4.10.8.1 The mbstowcs function

参阅

给定状态,将窄多字节字符串转换成宽字符串
(函数)
将宽字符串转换成窄多字节字符串
(函数)