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__ определён, функция использует кодировку UTF-32 для 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>

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("%s%08X", n ? " " : "", in[n]);
    puts("]");

    char* out = malloc(MB_CUR_MAX * in_sz);
    char* p = out;
    mbstate_t state = {0};

    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("%s%02X", x ? " " : "", +(unsigned char)out[x]);
    puts("]");

    free(out);
}

Processing 5 UTF-32 code units: [0000007A 000000DF 00006C34 0001F34C 00000000]
into 11 UTF-8 code units: [7A C3 9F E6 B0 B4 F0 9F 8D 8C 00]

Ссылки

• Стандарт C23 (ISO/IEC 9899:2024):
• 7.30.1.6 Функция c32rtomb (стр. 411)
• Стандарт C11 (ISO/IEC 9899:2011):
• 7.28.1.4 Функция c32rtomb (стр. 401)

См. также