通过

%>

  • 项目

将多字节字符序列转换为对应的宽字符序列。 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
wcstr 为 NULL 且 sizeInWords > 0 EINVAL
mbstr 是 NULL EINVAL
目标缓冲区过小，无法包含转换的字符串（除非 count 是 _TRUNCATE；请参阅下面的备注） ERANGE
wcstr 不是 NULL 且 sizeInWords == 0 EINVAL

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

备注

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

  • 遇到一个多字节空字符

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

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

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

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

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

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

如果 mbstr 和 wcstr 指向的序列重叠，则 mbstowcs_s 的行为没有定义。

重要

确保 wcstr 和 mbstr 未重叠，并且 count 正确反映了要转换的多字节字符的数量。

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

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

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

要求

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

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

另请参阅

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