wcsrtombs

将宽字符字符串转换为多字节字符串表示形式。 此函数有一个更安全的版本；请参阅 wcsrtombs_s。

语法

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

参数

mbstr
生成的已转换多字节字符字符串的地址位置。

wcstr
间接指向要转换的宽字符字符串的位置。

count
要转换的字符数。

mbstate
指向 mbstate_t 转换状态对象的指针。

返回值

返回已成功转换的字节数，不包括 null 终止 null 字节（如果有），发生错误时则为 -1。

注解

从 mbstate 中包含的指定转换状态开始，wcsrtombs 函数将 wcstr 中间接指向的宽字符字符串值转换为 mbstr 地址。 在遇到 null 终止宽字符或非相应字符或在下一个字符将超过 count 中的限制之前，每个字符的转换都将会一直进行。 如果 wcsrtombs 在 count 出现前或出现时遇到宽字符 null 字符 (L'\0')，则它将该字符转换为 8 位 0 并停止操作。

因此，只有当 wcsrtombs 在转换期间遇到宽字符 null 字符时，mbstr 处的多字节字符串才以 null 结尾。 如果 wcstr 和 mbstr 指向的序列重叠，则 wcsrtombs 的行为没有定义。 wcsrtombs 受到当前区域设置中 LC_TYPE 类别的影响。

wcsrtombs 函数的可重启性不同于 wcstombs、_wcstombs_l。 转换状态存储在 mbstate 中，以便后续调用相同的或其他可重启函数。 混合使用可重启函数和不可重启函数时，结果不确定。 例如，如果使用 wcsrlen（而非 wcsnlen）的后续调用，则应用程序应使用 wcsrtombs，而非 wcstombs。

如果 mbstr 参数为 NULL，则 wcsrtombs 会返回目标字符串所需的大小（以字节为单位）。 如果 mbstate 为 null，则使用内部 mbstate_t 转换状态。 如果字符序列 wchar 不具有相应的多字节字符表示形式，则返回 -1 且将 errno 设置为 EILSEQ。

在 C++ 中，此函数具有一个调用此函数的更新、更安全副本的模板重载。 有关详细信息，请参阅安全模板重载。

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

异常

只要当前线程中的函数都不调用 setlocale，此函数正在执行且 mbstate 是 null，wcsrtombs 函数就是多线程安全的。

示例

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfuly converted.\n" );
    }
}

The string was successfuly converted.

要求

例程	必需的标头
wcsrtombs	<wchar.h>

另请参阅

数据转换
区域设置
多字节字符序列的解释
wcrtomb
wcrtomb_s
wctomb、_wctomb_l
wcstombs、_wcstombs_l
mbsinit