wcsrtombs_s

Статья
06/09/2015

Преобразовать строку расширенных символов в строку многобайтовых символов. Это версия 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
Количество символов для преобразования.
[исходящий] mbstr
Адрес буфера для результирующей преобразованной строки многобайтовых символов.
[исходящий] sizeInBytes
Размер буфера mbstr (в байтах).
[входящий] wcstr
Указывает на преобразуемую строку расширенных символов.
[входящий] count
Максимальное количество байт, сохраняемых в буфере mbstr или _TRUNCATE.
[входящий] mbstate
Указатель на объект состояния преобразования mbstate_t.

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

Нуль, если успешно; код ошибки при неудаче.

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

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

Заметки

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

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

Строка назначения всегда содержит завершающий null (даже в случае ошибки).

Если count является специальным значением _TRUNCATE, то преобразование wcsrtombs_s будет выполняться до тех пор, пока буфер назначения не будет заполнен с учетом завершающего признака null.

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

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

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

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

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

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

Исключения

Функция 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

void 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" );
    }
}