wcstombs, _wcstombs_l

Статья
06/09/2015

Преобразование последовательности расширенных символов в соответствующую последовательность многобайтовых символов. Существуют более безопасные версии этих функций; см. раздел 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 и задает errno значение EILSEQ.

Заметки

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

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

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

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

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

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

Требования

Подпрограмма	Обязательный заголовок
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);
}