`wcsrtombs_s`

Статья
08/03/2024

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

Синтаксис

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

Параметры

pReturnValue
Размер преобразованной строки в байтах, включая терминатор NULL.

mbstr
Адрес буфера для итоговой преобразованной строки многобайтовых символов.

sizeInBytes
Размер (в байтах) буфера mbstr.

wcstr
Указывает на строку расширенных символов, которую необходимо преобразовать.

count
Максимальное количество байтов, хранящихся в буфере mbstr или _TRUNCATE.

mbstate
Указатель на объект состояния преобразования mbstate_t.

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

Возвращает нуль в случае успеха или код ошибки в случае неудачи.

Условие ошибки	Возвращаемое значение и `errno`
`mbstr` is `NULL` и `sizeInBytes`> 0	`EINVAL`
`wcstr` имеет значение `NULL`.	`EINVAL`
Буфер назначения слишком мал, чтобы вместить преобразованную строку (если параметр `count` не имеет значение `_TRUNCATE`; см. примечания ниже).	`ERANGE`

При возникновении любого из этих условий вызывается недопустимое исключение параметров, как описано в разделе проверки параметров. Если выполнение может быть продолжено, то функция возвращает код ошибки и устанавливает errno, как показано в таблице.

Замечания

Функция wcsrtombs_s преобразует строку расширенных символов, на которую указывает wcstr, в многобайтовые символы, сохраненные в буфере, на который указывает mbstr. При этом используется состояние преобразования, содержащееся в mbstate. Преобразование будет продолжаться для каждого символа до тех пор, пока не будет выполнено одно из указанных ниже условий.

Встретился расширенный нуль-символ.
Обнаружен широкий символ, который не может быть преобразован
Число байтов, сохраненных в буфере mbstr, равно count.

Строка назначения всегда завершается значением NULL (даже если возникает ошибка).

Если count это специальное значение _TRUNCATE, то wcsrtombs_s преобразуется столько строки, сколько вместится в целевой буфер, при этом остается место для конца null.

При wcsrtombs_s успешном преобразовании исходной строки он помещает размер в байты преобразованной строки, включая терминатор NULL, *pReturnValue в (указан pReturnValue не NULL). Размер вычисляется даже в том случае, если mbstr аргумент имеет NULLзначение; он предоставляет способ определения требуемого размера буфера. Если mbstr это NULLтак, count игнорируется.

Если wcsrtombs_s имеется широкий символ, он не может преобразоваться в многобайтовый символ, он помещает -1 в*pReturnValue, задает целевой буфер пустой строке, задает errno значение EILSEQи возвращает.EILSEQ

Если последовательности, на которые указывают параметры wcstr и mbstr, перекрываются, то поведение wcsrtombs_s не определено. На функцию wcsrtombs_s влияет категория LC_TYPE текущего языкового стандарта.

Внимание

Убедитесь, что строки wcstr и mbstr не перекрываются и что параметр count правильно отражает количество преобразуемых расширенных символов.

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

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

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

Исключения

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

Пример

// crt_wcsrtombs_s.cpp
//
// 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;
    errno_t         err;
    mbstate_t       mbstate;

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

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Требования

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

См. также

Преобразование данных
Локаль
Интерпретация последовательностей многобайтовых символов
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

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