%>

将多字节字符序列转换为对应的宽字符序列。 mbstowcs_mbstowcs_l 版本,具有安全性增强功能,如 CRT 中的安全功能中所述。

语法

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

参数

pReturnValue
要转换的字符数。

wcstr
用于转换所生成的宽字符串的缓冲区地址。

sizeInWords
wcstr 缓冲区大小(以字数为单位)。

mbstr
Null 终止的多字节字符序列的地址。

count
要存储在 wcstr 缓冲区中的宽字符的最大数量,不包括终止 null 或 _TRUNCATE

locale
要使用的区域设置。

返回值

如果成功,返回零;如果失败,则返回错误代码。

添加状态 返回值和 errno
wcstrNULLsizeInWords > 0 EINVAL
mbstrNULL EINVAL
目标缓冲区过小,无法包含转换的字符串(除非 count_TRUNCATE;请参阅下面的备注) ERANGE
wcstr 不是 NULLsizeInWords == 0 EINVAL

如果发生这些情况中的任何一个,都会调用无效参数异常,如参数验证中所述。 如果允许执行继续,函数将返回错误代码并按表中所示设置 errno

备注

mbstowcs_s 函数将 mbstr 指向的多字节字符串转换为存储在 wcstr 指向的缓冲区中的宽字符。 在满足以下条件之一前,该转换将一直对每个字符执行:

  • 遇到一个多字节空字符

  • 遇到一个无效的多字节字符

  • 存储在 wcstr 缓冲区中的宽字符数等于 count

目标字符串始终以 null 结尾(即使有错误)。

如果 count 是特殊值 _TRUNCATE,则 mbstowcs_s 会根据目标缓冲区的容量尽量多地转换字符串,同时为 null 终止符留下空间。

如果 mbstowcs_s 成功转换了源字符串,它会将转换的字符串(包括 null 终止符)的大小(以宽字符为单位)放入 *pReturnValue(假定 pReturnValue 不是 NULL)。 即使 wcstr 自变量是 NULL,也会计算大小,并提供一种方法来确定所需的缓冲区大小。 如果 wcstrNULL,则忽略 count,并且 sizeInWords 必须为 0。

如果 mbstowcs_s 遇到无效的多字节字符,它将执行以下操作:将 0 放入 *pReturnValue,将目标缓冲区设置为空字符串,将 errno 设置为 EILSEQ,并返回 EILSEQ

如果 mbstrwcstr 指向的序列重叠,则 mbstowcs_s 的行为没有定义。

重要

确保 wcstrmbstr 未重叠,并且 count 正确反映了要转换的多字节字符的数量。

mbstowcs_s 将当前区域设置用于任何与区域设置相关的行为;_mbstowcs_s_l 与此相同,只不过它使用传入的区域设置。 有关详细信息,请参阅 Locale

在 C++ 中,使用这些函数由模板重载简化;重载可以自动推导出缓冲区长度 (不再需要指定大小自变量),并且它们可以自动用以更新、更安全的对应物替换旧的、不安全的函数。 有关详细信息,请参阅安全模板重载

默认情况下,此函数的全局状态范围限定为应用程序。 若要更改此行为,请参阅 CRT 中的全局状态

要求

例程 必需的标头
mbstowcs_s <stdlib.h>
_mbstowcs_s_l <stdlib.h>

有关兼容性的详细信息,请参阅 兼容性

另请参阅

数据转换
区域设置
MultiByteToWideChar
多字节字符序列的解释
.- .
%>
%>
%>