`wcsrtombs`

Статья
10/12/2023

Преобразует строку расширенных символов в соответствующее представление многобайтовой строки. Доступна более безопасная версия этой функции; см. раздел 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 (если имеется); в противном случае — значение -1, если произошла ошибка.

Замечания

Функция wcsrtombs преобразует строку расширенных символов, начиная с указанного состояния преобразования, содержащегося в mbstate, из значений, косвенно указанных в wcstr, в адрес mbstr. Преобразование будет продолжаться для каждого символа до тех пор, пока не встретится расширенный завершающий символ null, или не обнаружится несоответствующий символ, или когда следующий символ может превысить ограничение, указанное в count. Если функция wcsrtombs встречает расширенный нуль-символ (L"\0") перед или после count символов, она преобразовывает его в 8-битный 0 и останавливается.

Таким образом, строка многобайтовых символов mbstr завершается символом NULL только в том случае, если функция wcsrtombs встречает расширенный нуль-символ во время преобразования. Если последовательности, на которые указывают параметры wcstr и mbstr, перекрываются, то поведение wcsrtombs не определено. На функцию wcsrtombs влияет категория LC_TYPE текущего языкового стандарта.

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

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

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

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

Исключения

Функция wcsrtombs является многопоточной безопасной, если функция в текущих вызовах setlocale потока не выполняется, и mbstate значение не равно NULL.

Пример

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

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