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, если произошла ошибка.

Замечания

Функция wcrtomb преобразует строку расширенных символов, начиная с указанного состояния преобразования, содержащегося в mbstate, из значения, содержащегося в wchar, в адрес, представленный mbchar. Возвращаемое значение — число байтов, необходимых для представления в соответствующего многобайтового символа, но не более MB_CUR_MAX байт.

Если mbstate имеет значение null, то используется внутренний объект mbstate_t, содержащий состояние преобразования mbchar. Если в последовательности wchar символов нет соответствующего многобайтового представления, возвращается значение -1 и errno задано значение EILSEQ.

Функция wcrtomb отличается от _wctomb_lwctomb ее перезапуска. Состояние преобразования хранится в переменной mbstate для последующих вызовов тех же или других перезапускаемых функций. При смешанном использовании перезапускаемых и неперезапускаемых функций результаты становятся неопределенными. Например, в приложении следует использовать функцию wcsrlen вместо функции wcsnlen, если в последующем вызове используется функция wcsrtombs, а не функция wcstombs.

В C++ эта функция имеет перегрузку шаблона, которая вызывает более новые и безопасные аналоги этой функции. Дополнительные сведения см. в разделе "Безопасные перегрузки шаблонов".

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Исключения

Функция wcrtomb является потокобезопасной, если ни одна из функций в текущем потоке не вызывает setlocale, пока выполняется данная функция и пока mbstate имеет значение null.

Пример

// 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.

Требования

См. также

Преобразование данных
Локаль
Интерпретация последовательностей многобайтовых символов
mbsinit