Namespaces
Variants

wctomb, wctomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Определено в заголовочном файле <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 в многобайтовую кодировку и сохраняет его (включая любые сдвиговые последовательности) в массив символов, на первый элемент которого указывает s . Сохраняется не более MB_CUR_MAX символов. Преобразование зависит от категории LC_CTYPE текущей локали.
Если wc является нулевым символом, нулевой байт записывается в s , предваряемый любыми последовательностями сдвига, необходимыми для восстановления исходного состояния сдвига.
Если s является нулевым указателем, эта функция сбрасывает глобальное состояние преобразования и определяет, используются ли сдвиговые последовательности.
2) Аналогично (1) , за исключением того, что результат возвращается в выходном параметре status и следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную функцию обработки ограничений :
  • ssz меньше количества байтов, которые были бы записаны (если s не является нулевым указателем)
  • ssz больше RSIZE_MAX (если s не является нулевым указателем)
  • s является нулевым указателем, но 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

Смотрите также

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