wcstombs，_wcstombs_l

  • 项目

将宽字符序列转换为对应的多字节字符序列。 提供这些函数的更安全版本；请参阅 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 支持

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

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

wcstombs 会验证其参数。 如果 wcstr 为 NULL，或如果 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.

另请参阅

数据转换
区域设置
_mbclen、mblen、_mblen_l
mbstowcs、_mbstowcs_l
mbtowc、_mbtowc_l
wctomb、_wctomb_l
WideCharToMultiByte