`mbsrtowcs_s`

Статья
10/12/2023

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

Синтаксис

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

Параметры

pReturnValue
Количество символов для преобразования.

wcstr
Адрес буфера для результирующей преобразованной строки расширенных символов.

sizeInWords
Размер wcstr в словах (расширенных символах).

mbstr
Косвенный указатель на расположение преобразуемой строки многобайтовых символов.

count
Максимальное количество расширенных символов для хранения в буфере wcstr , не включая завершающее значение NULL или _TRUNCATE.

mbstate
Указатель на объект состояния преобразования mbstate_t. Если это значение является пустым указателем, используется статичный внутренний объект состояния преобразования. Так как внутренний mbstate_t объект не является потокобезопасной, рекомендуется всегда передавать собственный mbstate параметр.

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

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

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

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

Замечания

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

Встретился многобайтовый символ null.
Встретился недопустимый многобайтовый символ.
Число расширенных символов, сохраненных в буфере wcstr, равно count.

Целевая строка wcstr всегда завершается значением NULL, wcstr даже если ошибка не имеет значения NULL.

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

Если mbsrtowcs_s исходная строка успешно преобразуется, она помещает размер в широкие символы преобразованной строки и конца *pReturnValuenull, если указан pReturnValue не пустой указатель. Размер вычисляется, даже если wcstr аргумент является пустым указателем, что позволяет определить требуемый размер буфера. Если wcstr указатель имеет значение NULL, count игнорируется.

Если wcstr указатель не является пустым, объект указателя, на который указывает mbstr указатель, назначается указателем NULL, если преобразование остановлено, так как достигнут завершающий символ NULL. В противном случае он назначает адрес только после последнего многобайтового символа, преобразованного, если таковой есть. Он позволяет последующему вызову функции перезапустить преобразование, в котором этот вызов остановлен.

Если значение mbstate является пустым указателем, используется статичный внутренний объект состояния преобразования mbstate_t. Так как этот внутренний статический объект не является потокобезопасной, рекомендуется передать собственное mbstate значение.

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

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

Важно!

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

Функция mbsrtowcs_s отличается от _mbstowcs_s_lmbstowcs_s ее перезапуска. Состояние преобразования хранится в переменной mbstate для последующих вызовов тех же или других перезапускаемых функций. При смешанном использовании перезапускаемых и неперезапускаемых функций результаты становятся неопределенными. Например, приложение должно использовать mbsrlen вместо mbslenнего, если последующий вызов mbsrtowcs_s используется вместо mbstowcs_s.

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

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

Исключения

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

Требования

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

См. также

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