Namespaces
Variants

    wcrtomb, wcrtomb_s

    С ru.cppreference.net
     
    C
     
    Библиотека строк
     
    Многобайтовые строки, завершающиеся нулём
     
    Определено в заголовке <wchar.h> 
    size_t wcrtomb( char* s, wchar_t wc, mbstate_t* ps);
    		(1) (начиная с C95)
    (до C99)    		 
    size_t wcrtomb( char* restrict s, wchar_t wc, mbstate_t* restrict ps);
    		(начиная с C99) 
    errno_t wcrtomb_s(size_t* restrict retval, char* restrict s, rsize_t ssz,
                  wchar_t wc, mbstate_t* restrict ps);
    		(2) (начиная с C11)

    Преобразует широкий символ в его узкое многобайтовое представление.

    1) Если s не является нулевым указателем, функция определяет количество байтов, необходимых для хранения многобайтового представления символа wc (включая любые последовательности сдвига и учитывая текущее состояние преобразования многобайтового символа *ps), и сохраняет многобайтовое представление символа в массив символов, на первый элемент которого указывает s, обновляя *ps по мере необходимости. С помощью этой функции можно записать не более MB_CUR_MAX байтов.
    Если s является нулевым указателем, вызов эквивалентен wcrtomb(buf, L'\0', ps) для некоторого внутреннего буфера buf.
    Если wc является нулевым широким символом L'\0', сохраняется нулевой байт, которому предшествует любая последовательность сдвига, необходимая для восстановления начального состояния сдвига, а параметр состояния преобразования *ps обновляется для представления начального состояния сдвига.
    Если макрос окружения __STDC_ISO_10646__ определён, значения типа wchar_t совпадают с короткими идентификаторами символов в обязательном наборе Unicode (обычно кодировка UTF-32); в противном случае это определяется реализацией. В любом случае, многобайтовая кодировка символов, используемая этой функцией, определяется текущей активной локалью C.
    2) То же, что и (1), за исключением того, что
    если s является нулевым указателем, вызов эквивалентен wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) с внутренними переменными retval и buf (размер которых больше, чем MB_CUR_MAX)
    результат возвращается в выходном параметре retval
    следующие ошибки обнаруживаются во время выполнения и вызывают установленную в данный момент функцию-обработчик ограничений функцию:
    • retval или ps является нулевым указателем.
    • ssz равен нулю или больше RSIZE_MAX (если только s не равен null)
    • ssz меньше количества байтов, которые будут записаны (если только s не равен null)
    • s является нулевым указателем, но ssz не равен нулю
    Как и все функции с проверкой границ, wcrtomb_s гарантированно доступна только если __STDC_LIB_EXT1__ определён реализацией и если пользователь определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 перед включением <wchar.h>.

    Параметры

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

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

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

    Пример

    Запустить этот код
    #include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu wchar_t units: [ ", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%#x ", (unsigned int)in[n]);
    puts("]");
 
    char out[MB_CUR_MAX * in_sz];
    char* p = out;
    for (size_t n = 0; n < in_sz; ++n)
    {
        int rc = wcrtomb(p, in[n], &state);
        if (rc == -1)
            break;
        p += rc;
    }
 
    size_t out_sz = p - out;
    printf("into %zu UTF-8 code units: [ ", out_sz);
    for (size_t x = 0; x < out_sz; ++x)
        printf("%#x ", +(unsigned char)out[x]);
    puts("]");
}

    Вывод: 

    Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

    Ссылки

    • Стандарт C23 (ISO/IEC 9899:2024):
    • 7.29.6.3.3 Функция wcrtomb (стр.: TBD)
    • K.3.9.3.1.1 Функция wcrtomb_s (стр.: TBD)
    • Стандарт C17 (ISO/IEC 9899:2018):
    • 7.29.6.3.3 Функция wcrtomb (стр.: TBD)
    • K.3.9.3.1.1 Функция wcrtomb_s (стр.: TBD)
    • Стандарт C11 (ISO/IEC 9899:2011):
    • 7.29.6.3.3 Функция wcrtomb (стр.: 444)
    • K.3.9.3.1.1 Функция wcrtomb_s (стр.: 647-648)
    • Стандарт C99 (ISO/IEC 9899:1999):
    • 7.24.6.3.3 Функция wcrtomb (стр.: 390)

    См. также

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