c32rtomb

size_t c32rtomb( char* restrict s, char32_t c32, mbstate_t* restrict ps );

Преобразует одиночный код символа из его представления в виде 32-битного символа переменной длины (но обычно UTF-32) в его представление в виде узкого многобайтового символа.

Если s не является нулевым указателем, функция определяет количество байтов, необходимых для хранения многобайтового представления c32 (включая все последовательности сдвига и с учётом текущего состояния преобразования многобайтовой строки *ps), и сохраняет это многобайтовое представление в массиве символов, адрес первого элемента которого указан в s, обновляя *ps по необходимости. Данная функция может записать не более MB_CUR_MAX байтов.

Если s является нулевым указателем, вызов эквивалентен вызову c32rtomb(buf, U'\0', ps) для некоторого внутреннего буфера buf.

Если c32 является нулевым широким символом U'\0', сохраняется нулевой байт, перед которым могут быть расположены необходимые последовательности сдвига, для восстановления начального состояния сдвига, и параметр состояния преобразования *ps обновляется, чтобы отразить начальное состояние сдвига.

Если макрос __STDC_UTF_32__ определён, то 32-битовая кодировка, используемая этой функцией, является UTF-32; в противном случае она определяется реализацией. Макрос всегда определён, а кодировка всегда UTF-32.(с C23) В любом случае, многобайтовая кодировка символов, используемая этой функцией, определяется текущим активным языковым окружением C.

Параметры

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

При успешном выполнении возвращает количество байтов (включая последовательности сдвига) записанных в массив символов, адрес первого элемента которого указан в s. Это значение может быть ​0​, например, при обработке ведущих char32_t единиц в много-char32_t-единичной последовательности (не происходит в UTF-32).

При ошибке (если c32 не является допустимым 32-битным широким символом) возвращает -1, сохраняет EILSEQ в errno, и оставляет *ps в неопределённом состоянии.

Пример

#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <uchar.h>
 
mbstate_t state;
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char32_t in[] = U"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu UTF-32 code units: [ ", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%#x ", in[n]);
    puts("]");
 
    char out[MB_CUR_MAX * in_sz];
    char* p = out;
    for (size_t n = 0; n < in_sz; ++n)
    {
        size_t rc = c32rtomb(p, in[n], &state);
        if(rc == (size_t)-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 UTF-32 code 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:2023):
• 7.30.1.6 Функция c32rtomb (стр. 411)
• Стандарт C11 (ISO/IEC 9899:2011):
• 7.28.1.4 Функция c32rtomb (стр. 401)

См. также