wcstombs, _wcstombs_l

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

Синтаксис

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

Параметры

mbstr
Адрес последовательности многобайтовых символов.

wcstr
Адрес последовательности расширенных символов.

count
Максимальное количество байтов, которые могут храниться в выходной строке многобайтовых символов.

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

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

Если функция wcstombs успешно преобразовывает строку многобайтовых символов, она возвращает число байтов, записанных в выходную строку многобайтовых символов, исключая конечный символ NULL (при его наличии). Если аргумент mbstr равен NULL, функция wcstombs возвращает необходимый размер строки назначения в байтах. Если wcstombs встречается широкий символ, он не может преобразоваться в многобайтовый символ, он возвращает -1 приведение к типу size_t и наборам errnoEILSEQ.

Замечания

Функция wcstombs преобразовывает строку расширенных символов, на которую указывает параметр wcstr, в соответствующие многобайтовые символы и сохраняет результаты в массиве mbstr. Параметр count указывает максимальное число байтов, которые могут храниться в выходной строке многобайтовых символов (т. е., размер mbstr). Как правило, не известно, сколько байтов потребуется при преобразовании строки широкого символа. Для некоторых расширенных символов требуется только один байт в выходной строке; другие требуют 2 байта. Если в многобайтовой выходной строке имеется 2 байта для каждого широкого символа входной строки (включая широкий символ NULL), результат гарантированно будет соответствовать.

Начиная с Windows 10 версии 1803 (10.0.17134.0), универсальная среда выполнения C поддерживает использование кодовой страницы UTF-8. Используйте wcstombs(NULL, wcstr, 0) для получения правильного размера, который потребуется для преобразования, так как предполагается, что вам потребуется два байта для каждого широкого символа может быть недостаточно. Дополнительные сведения о поддержке UTF-8 см. в разделе "Поддержка UTF-8"

При wcstombs обнаружении широкозначного символа NULL (L'\0) либо до или при count возникновении, он преобразует его в 8-разрядную 0 и останавливается. Таким образом, строка mbstr многобайтового символа по значению null завершается только в том случае, если wcstombs во время преобразования встречается символ с широким символом NULL . Если последовательности, на которые указывают параметры wcstr и mbstr, перекрываются, то поведение wcstombs не определено.

Если аргумент mbstr равен NULL, функция wcstombs возвращает необходимый размер строки назначения в байтах.

Кроме того, функция wcstombs проверяет свои параметры. Если wcstr значение NULLбольше или count больше INT_MAX, эта функция вызывает обработчик недопустимых параметров, как описано в разделе проверки параметров. Если выполнение может быть продолжено, функция устанавливает параметр errno в значение EINVAL и возвращает –1.

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

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

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

Требования

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

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

Пример

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

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

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

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

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}

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

См. также

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