wcstombs_s, _wcstombs_s_l

  • Статья

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

Синтаксис

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count
);

errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);

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

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

Параметры

pReturnValue
Размер преобразованной строки в байтах, включая терминатор NULL.

mbstr
Адрес буфера для итоговой преобразованной строки многобайтовых символов.

sizeInBytes
Размер (в байтах) буфера mbstr.

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

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

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

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

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

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

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

Замечания

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

  • Встретился расширенный нуль-символ.

  • Обнаружен широкий символ, который не может быть преобразован

  • Число байтов, сохраненных в буфере mbstr, равно count.

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

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

При wcstombs_s успешном преобразовании исходной строки он помещает размер в байты преобразованной строки, включая терминатор NULL, *pReturnValue в (указан pReturnValue не NULL). Размер вычисляется даже в том случае, если mbstr аргумент имеет NULLзначение; он предоставляет способ определения требуемого размера буфера. Если mbstr это NULLтак, count игнорируется.

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

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

Важно!

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

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

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

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

Требования

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

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

Пример

Эта программа иллюстрирует поведение функции wcstombs_s.

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t i;
    char *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    const wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,
               pWCBuffer, (size_t)BUFFER_SIZE - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n", pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
        free(pMBBuffer);
    }
    
    return 0;
}

Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

См. также

Преобразование данных
Локаль
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte