wcsrtombs_s

Статья
02/20/2013

Преобразование строка символов юникода в строковое представление многобайтового символов.Версия 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 в многобайтовые символы, хранящегося в буфере указывать на by mbstrс помощью преобразований, содержащихся в состояние mbstate.Преобразование продолжится для каждого символа до тех пор, пока одно из этих условий не будет выполнено.

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

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

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

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

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

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

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

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

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

Исключения

wcsrtombs_s функция многопоточной safe, если ни одна функция в текущих вызовов потока 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" );
    }
}