wctomb, wctomb_s

Определено в заголовке `<stdlib.h>`
int wctomb( char *s, wchar_t wc );	(1)
errno_t wctomb_s( int restrict status, char restrict s, rsize_t ssz, wchar_t wc );	(2)	(с C11)

1) Преобразует широкий символ wc в многобайтовую кодировку и сохраняет его (включая любые последовательности смены состояний) в массиве char, на который указывает s. Не более чем MB_CUR_MAX символов сохраняются. Преобразование зависит от категории LC_CTYPE текущего языка.

Если wc является нулевым символом, нулевой байт записывается в s, перед ним записываются необходимые последовательности смены состояний для восстановления начального состояния смены состояний.

Если s является указателем на NULL, эта функция сбрасывает глобальное состояние преобразования и определяет, используются ли последовательности смены состояний.

2) То же, что и (1), за исключением того, что результат возвращается в параметр status, а следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную функцию обработчика ограничений обработчика ограничений:

ssz меньше, чем количество байтов, которое должно быть записано (если s не равен NULL)
ssz больше, чем RSIZE_MAX (если s не равен NULL)
s является указателем на NULL, но ssz не равен нулю

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

Примечания

Каждый вызов wctomb обновляет внутреннее глобальное состояние преобразования (статический объект типа mbstate_t, известный только этой функции). Если многобайтовая кодировка использует состояния смены состояний, эта функция не является реентерабельной. В любом случае, несколько потоков не должны вызывать wctomb без синхронизации: wcrtomb или wctomb_s могут быть использованы вместо этого.

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

Параметры

s	-	указатель на символьный массив для вывода
wc	-	символ расширенной кодировки для преобразования
ssz	-	максимальное количество байтов для записи в `s` (размер массива `s`)
status	-	указатель на параметр вывода, где будет храниться результат (длина последовательности многобайтового символа или состояние последовательности смены кодовой страницы)

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

1) Если s не является нулевым указателем, возвращает количество байтов, содержащихся в многобайтовом представлении wc или -1, если wc не является допустимым символом.

Если s является нулевым указателем, сбрасывает внутреннее состояние преобразования в начальное состояние смены кодовой страницы и возвращает 0, если текущая многобайтовая кодировка не зависит от состояния (не использует последовательности смены кодовой страницы), или ненулевое значение, если текущая многобайтовая кодировка зависит от состояния (использует последовательности смены кодовой страницы).

2) ноль при успешном выполнении, в этом случае многобайтовое представление wc хранится в s, а его длина в *status, или, если s является нулевым указателем, состояние последовательности смены кодовой страницы хранится в status. Неноль в случае ошибки кодирования или нарушения ограничения во время выполнения, в этом случае (size_t)-1 хранится в *status. Значение, хранящееся в *status, никогда не превышает MB_CUR_MAX.

Пример

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
 
void demo(wchar_t wc)
{
    const char* dep = wctomb(NULL, wc) ? "Yes" : "No";
    printf("State-dependent encoding? %s.\n", dep);
 
    char mb[MB_CUR_MAX];
    int len = wctomb(mb, wc);
    printf("wide char '%lc' -> multibyte char [", wc);
    for (int idx = 0; idx < len; ++idx)
        printf("%s%#2x", idx ? " " : "", (unsigned char)mb[idx]);
    printf("]\n");
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX);
    demo(L'A');
    demo(L'\u00df');
    demo(L'\U0001d10b');
}

Возможный вывод:

MB_CUR_MAX = 6
State-dependent encoding? No.
wide char 'A' -> multibyte char [0x41]
State-dependent encoding? No.
wide char 'ß' -> multibyte char [0xc3 0x9f]
State-dependent encoding? No.
wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]

Ссылки

Стандарт C17 (ISO/IEC 9899:2018):

7.22.7.3 Функция wctomb (с. 261)
K.3.6.4.1 Функция wctomb_s (с. 443)

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

7.22.7.3 Функция wctomb (с. 358-359)
K.3.6.4.1 Функция wctomb_s (с. 610-611)

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

7.20.7.3 Функция wctomb (с. 322-323)

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

4.10.7.3 Функция wctomb

См. также

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

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