`mbsrtowcs`

Статья
04/03/2023

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

Синтаксис

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

Параметры

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

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

count
Максимальное число символов (не байтов) для преобразования и сохранения в wcstr.

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

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

Возвращает число успешно преобразованных символов без учета завершающего нуль-символа, если он есть. Возвращает (size_t)(-1), если произошла ошибка, и задает значение errnoEILSEQ.

Замечания

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

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

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

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

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

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

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

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

Исключения

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

Требования

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

См. также

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

Share via