`wcrtomb_s`

Статья
04/03/2023

Преобразует расширенный символ в соответствующее представление многобайтового символа. Версия wcrtomb с улучшениями безопасности, как описано в функциях безопасности в CRT.

Синтаксис

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

Параметры

pReturnValue
Возвращает записанное число символов или –1 в случае возникновения ошибки.

mbchar
Итоговый преобразованный многобайтовый символ.

sizeOfmbchar
Размер переменной mbchar в байтах.

wchar
Расширенный символ для преобразования.

mbstate
Указатель на объект mbstate_t.

Возвращаемое значение

Возвращает нуль в случае успешного выполнения или значение errno при возникновении ошибки.

Замечания

Функция wcrtomb_s преобразует строку расширенных символов, начиная с указанного состояния преобразования, содержащегося в mbstate, из значения, содержащегося в wchar, в адрес, представленный mbchar. Значением pReturnValue будет число преобразованных байтов, но не более MB_CUR_MAX байтов, или -1, если произошла ошибка.

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

Функция wcrtomb_s отличается от _wctomb_s_lwctomb_s ее перезапуска. Состояние преобразования хранится в переменной mbstate для последующих вызовов тех же или других перезапускаемых функций. При смешанном использовании перезапускаемых и неперезапускаемых функций результаты становятся неопределенными. Например, в приложении следует использовать функцию wcsrlen вместо функции wcslen, если в последующем вызове используется функция wcsrtombs_s, а не функция wcstombs_s.

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

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

Исключения

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

Пример

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

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

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

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

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to a the "Q" multibyte character.

Требования

Маршрут	Обязательный заголовок
`wcrtomb_s`	<wchar.h>

См. также

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

Поделиться через