c16rtomb

size_t c16rtomb( char* restrict s, char16_t c16, mbstate_t* restrict ps );

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

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

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

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

Если c16 не является последней кодовой единицей в 16-битном представлении широкого символа, функция не записывает данные в массив, на который указывает s, а обновляет только *ps.

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

Параметры

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

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

В случае ошибки (если c16 не является допустимой 16-битной кодовой единицей) возвращает -1, сохраняет EILSEQ в errno и оставляет *ps в неопределённом состоянии.

Примечания

В опубликованной редакции C11, в отличие от mbrtoc16, преобразующей многобайтовую кодировку переменной ширины (например, UTF-8) в 16-битную кодировку переменной ширины (например, UTF-16), эта функция может преобразовывать только 16-битную кодировку с единицами фиксированной ширины. Это означает, что она не может преобразовать UTF-16 в UTF-8, несмотря на то, что именно это было изначальной целью создания функции. Ошибка была исправлена в отчёте об обнаруженной ошибке DR488, опубликованном после C11.

Пример

#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <uchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char16_t in[] = u"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    const size_t in_sz = sizeof in / sizeof *in;

    printf("Processing %zu UTF-16 code units: [", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%s%04X", 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 = c16rtomb(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 6 UTF-16 code units: [007A 00DF 6C34 D83C DF4C 0000]
into 13 UTF-8 code units: [7A C3 9F E6 B0 B4 ED A0 BC ED BD 8C 00]

Ссылки

• Стандарт C23 (ISO/IEC 9899:2024):
• 7.28.1.2 Функция c16rtomb (стр.: уточняется)
• Стандарт C17 (ISO/IEC 9899:2018):
• 7.28.1.2 Функция c16rtomb (стр.: уточняется)
• Стандарт C11 (ISO/IEC 9899:2011):
• 7.28.1.2 Функция c16rtomb (стр.: 399–400)

См. также