%>

将宽字符序列转换为对应的多字节字符序列。 提供这些函数的更安全版本;请参阅 wcstombs_s_wcstombs_s_l

语法

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

参数

mbstr
多字节字符序列的地址。

wcstr
宽字符序列的地址。

count
多字节输出字符串可以存储的最大字节数。

locale
要使用的区域设置。

返回值

如果 wcstombs 成功转换多字节字符串,将返回多字节输出字符串中写入的字节数,不包括终止 NULL(如果有)。 如果 mbstr 参数为 NULL,则 wcstombs 会返回目标字符串所需的大小(以字节为单位)。 如果 wcstombs 遇到无法转换为多字节字符的宽字符,将会把 -1 强制转换为类型 size_t,并将 errno 设置为 EILSEQ

注解

wcstombs 函数将 wcstr 指向的宽字符字符串转换为相应的多字节字符,并将转换结果存储到 mbstr 数组中。 count 参数指明多字节输出字符串可以存储的最大字节数(也就是 mbstr 的大小)。 一般情况下,转换宽字符字符串时不会知道需要多少个字节。 某些宽字符只需要输出字符串中的单个字节;其他需要 2 个字节。 如果输入字符串每个宽字符的多字节输出字符串存在 2 个字节(包括宽字符 NULL),要确保结果可以将其容纳。

从 Windows 10 版本 1803 (10.0.17134.0) 开始,通用 C 运行时支持使用 UTF-8 代码页。 使用 wcstombs(NULL, wcstr, 0) 获取转换所需的正确大小,因为假设每个宽字符需要两个字节可能不够。 有关 UTF-8 支持的详细信息,请参阅 UTF-8 支持

如果 wcstombscount 出现前或出现时遇到宽字符 NULL 字符 (L'\0'),则它将该字符转换为 8 位 0 并停止操作。 因此,只有当 wcstombs 在转换期间遇到宽字符 NULL 字符时,mbstr 处的多字节字符串才以 null 结尾。 如果 wcstrmbstr 指向的序列重叠,则 wcstombs 的行为没有定义。

如果 mbstr 参数为 NULL,则 wcstombs 会返回目标字符串所需的大小(以字节为单位)。

wcstombs 会验证其参数。 如果 wcstrNULL,或如果 count 优于 INT_MAX,此函数将调用无效参数处理程序,如参数验证中所述。 如果允许继续执行,则该函数将 errno 设置为 EINVAL 并返回 -1。

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

在 C++ 中,这些函数具有模板重载,以调用这些函数的更新、更安全副本。 有关详细信息,请参阅安全模板重载

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

要求

例程 必需的标头
wcstombs <stdlib.h>
_wcstombs_l <stdlib.h>

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

示例

本程序演示 wcstombs 函数的行为。

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}
Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

另请参阅

数据转换
区域设置
.- .
%>
%>
%>
WideCharToMultiByte