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__ определён, то 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, несмотря на то, что это было первоначальным намерением этой функции. Это было исправлено отчётом о дефекте после C11 DR488.

Пример

#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 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("%#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 = 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("%#x ", +(unsigned char)out[x]);
    puts("]");
}

Processing 6 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c 0 ]
into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

Ссылки

• Стандарт C23 (ISO/IEC 9899:2023):
• 7.28.1.2 Функция c16rtomb (с. TBD)
• Стандарт C17 (ISO/IEC 9899:2018):
• 7.28.1.2 Функция c16rtomb (с. TBD)
• Стандарт C11 (ISO/IEC 9899:2011):
• 7.28.1.2 Функция c16rtomb (с. 399-400)

См. также