wcrtomb

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

语法

size_t wcrtomb(
   char *mbchar,
   wchar_t wchar,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcrtomb(
   char (&mbchar)[size],
   wchar_t wchar,
   mbstate_t *mbstate
); // C++ only

参数

mbchar
生成的多字节转换字符。

wchar
要转换的宽字符。

mbstate
指向 mbstate_t 对象的指针。

返回值

返回表示已转换多字节字符所需的字节数,如果发生错误则为 -1。

备注

mbstate 中包含的指定转换状态开始,wcrtomb 函数将 wchar 的宽字符值转换为 mbchar 表示的地址。 返回值为表示相应多字节字符所需的字节数,但该返回值不会超过 MB_CUR_MAX 字节。

如果 mbstate 为 null,则会使用包含 mbchar 转换状态的内部 mbstate_t 对象。 如果字符序列 wchar 不具有相应的多字节字符表示形式,则返回 -1 且将 errno 设置为 EILSEQ

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

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

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

例外

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

示例

// crt_wcrtomb.c
// compile with: /W3
// This program converts a wide character
// to its corresponding multibyte character.

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    size_t      sizeOfCovertion = 0;
    mbstate_t   mbstate;
    char        mbStr = 0;
    wchar_t*    wcStr = L"Q";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    sizeOfCovertion = wcrtomb(&mbStr, *wcStr, &mbstate); // C4996
    // Note: wcrtomb is deprecated; consider using wcrtomb_s instead
    if (sizeOfCovertion > 0)
    {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wcStr);
        printf(" was converted to the \"%c\" ", mbStr);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}
The corresponding wide character "Q" was converted to the "Q" multibyte character.

要求

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

另请参阅

数据转换
区域设置
多字节字符序列的解释
mbsinit