wcstombs, wcstombs_s

Определено в заголовке `<stdlib.h>`
	(1)
size_t wcstombs( char dst, const wchar_t src, size_t len );		(до C99)
size_t wcstombs( char restrict dst, const wchar_t restrict src, size_t len );		(с C99)
errno_t wcstombs_s( size_t restrict retval, char restrict dst, rsize_t dstsz, const wchar_t *restrict src, rsize_t len );	(2)	(с C11)

1) Преобразует последовательность широких символов из массива, на который указывает первый элемент, указанный по адресу src, в его узкое многобайтовое представление, начинающееся в начальном смещающем состоянии. Преобразованные символы сохраняются в последовательных элементах массива символов, на который указывает dst. В массив назначения не записывается более len байтов.

Каждый символ преобразуется так, как если бы был выполнен вызов wctomb, за исключением того, что состояние преобразования wctomb не изменяется. Преобразование останавливается, если:

* Символ-нуль L'\0' был преобразован и сохранён. Записанные байты в этом случае представляют собой последовательность сброса (при необходимости) и '\0',

* Встретился символ wchar_t, который не соответствует допустимому символу в текущей локали C.

* Следующий многобайтовый символ для записи превысил бы len.

Если src и dst перекрываются, поведение не определено.

2) Аналогично (1), за исключением того, что

* преобразование выполняется как при вызове wcrtomb, а не wctomb

* функция возвращает результат как параметр вывода retval

* если преобразование завершается без записи символа-нуля, функция запишет '\0' в следующий байт в dst, что может быть dst[len] или dst[dstsz], что наступит раньше (это означает, что может быть записано до len+1/dstsz+1 байтов в целом). В этом случае может не быть записанной последовательности сброса перед завершающим нулём.

* если dst является указателем на null, количество байтов, которое было бы произведено, сохраняется в *retval

* функция очищает массив назначения от завершающего нуля до dstsz

* Если src и dst перекрываются, поведение не определено.

* следующие ошибки обнаруживаются во время выполнения и вызывают установленную в данный момент функцию обработчика ограничений обработчика ограничений:

retval или src является указателем null
dstsz или len больше RSIZE_MAX (если dst не является null)
dstsz не равно нулю (если dst не является null)
len больше dstsz и преобразование не сталкивается с null или ошибкой кодирования в массиве src к моменту достижения dstsz (если dst не является null)

Как и во всех функциях с проверкой границ, wcstombs_s гарантированно доступен только если __STDC_LIB_EXT1__ определено реализацией и если пользователь определит __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 до включения <stdlib.h>.

Примечания

В большинстве реализаций wcstombs обновляет глобальный статический объект типа mbstate_t, по мере обработки строки, и не может быть вызван одновременно двумя потоками, wcsrtombs или wcstombs_s следует использовать в таких случаях.

POSIX определяет общее расширение: если dst является указателем на null, эта функция возвращает количество байтов, которое было бы записано в dst, если бы преобразование выполнилось. Аналогичное поведение стандартно для wcsrtombs и wcstombs_s.

Параметры

dst	-	указатель на массив узких символов, где будет храниться многобайтовый символ
src	-	указатель на первый элемент нуль-терминированной широкой строки для преобразования
len	-	количество байтов, доступных в массиве, на который указывает dst
dstsz	-	максимальное количество байтов, которое будет записано (размер массива `dst`)
retval	-	указатель на объект size_t, где будет сохранён результат

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

1) При успехе возвращает количество байтов (включая все последовательности сдвига, но не считая завершающий '\0') записанные в массив символов, на который указывает первый элемент, указанный по адресу dst. При ошибке преобразования (если был встречен недопустимый широкий символ) возвращает (size_t)-1.

2) Возвращает ноль при успехе (в этом случае количество байтов, не считая завершающего нуля, которые были или будут записаны в dst, хранится в *retval), ненулевое значение при ошибке. В случае нарушения ограничения во время выполнения, сохраняет (size_t)-1 в *retval (если retval не является null) и устанавливает dst[0] в '\0' (если dst не является null или dstmax равно нулю или больше RSIZE_MAX).

Пример

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
 
int main(void)
{
    // 4 wide characters
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // they occupy 10 bytes in UTF-8
    char dst[11];
 
    setlocale(LC_ALL, "en_US.utf8");
    printf("wide-character string: '%ls'\n",src);
    for (size_t ndx=0; ndx < sizeof src/sizeof src[0]; ++ndx)
        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
 
    int rtn_val = wcstombs(dst, src, sizeof dst);
    printf("rtn_val = %d\n", rtn_val);
    if (rtn_val > 0)
        printf("multibyte string:  '%s'\n",dst);
    for (size_t ndx=0; ndx<sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

Вывод:

wide-character string: 'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
multibyte string:  'zß水🍌'
   dst[ 0] = 0x7a
   dst[ 1] = 0xc3
   dst[ 2] = 0x9f
   dst[ 3] = 0xe6
   dst[ 4] = 0xb0
   dst[ 5] = 0xb4
   dst[ 6] = 0xf0
   dst[ 7] = 0x9f
   dst[ 8] = 0x8d
   dst[ 9] = 0x8c
   dst[10] =  0

Ссылки

Стандарт C11 (ISO/IEC 9899:2011):

7.22.8.2 Функция wcstombs (стр. 360)
K.3.6.5.2 Функция wcstombs_s (стр. 612-614)

Стандарт C99 (ISO/IEC 9899:1999):

7.20.8.2 Функция wcstombs (стр. 324)

Стандарт C89/C90 (ISO/IEC 9899:1990):

4.10.8.2 Функция wcstombs

См. также

wcsrtombswcsrtombs_s (C95)(C11)	преобразует широкую строку в узкую многобайтовую строку, учитывая состояние (функция)
mbstowcsmbstowcs_s (C11)	преобразует узкую многобайтовую строку в широкую строку (функция)
Документация C++ для `wcstombs`

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/c/string/multibyte/wcstombs