mbstowcs_s, _mbstowcs_s_l

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

Синтаксис

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Параметры

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

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

sizeInWords
Размер буфера wcstr в словах.

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

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

locale
Используемый языковой стандарт.

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

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

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

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

Замечания

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

• Встретился многобайтовый символ null.

• Встретился недопустимый многобайтовый символ.

• Число расширенных символов, сохраненных в буфере wcstr, равно count.

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

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

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

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

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

Важно!

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

Функция mbstowcs_s использует текущий языковой стандарт для любых аспектов поведения, зависящих от языкового стандарта; функция _mbstowcs_s_l идентична за исключением того, что она использует переданный языковой стандарт. Дополнительные сведения см. в разделе Locale.

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

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

Требования

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

Дополнительные сведения о совместимости см. в разделе Совместимость.

См. также

Преобразование данных
Локаль
MultiByteToWideChar
Интерпретация последовательностей многобайтовых символов
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l