c8rtomb

size_t c8rtomb( char* restrict s, char8_t c8, mbstate_t* restrict ps );

Преобразует одну кодовую точку из UTF-8 в представление узкого многобайтового символа.

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

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

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

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

Многобайтовая кодировка, используемая этой функцией, определяется текущей активной локалью C.

Параметры

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

Количество байтов, сохранённых в объекте массива (включая любые последовательности переключения). Это значение может быть равно нулю, если c8 не является последней кодовой единицей в представлении кодовой точки UTF-8.

Если c8 недопустимо (не входит в последовательность char8_t, соответствующую допустимому многобайтовому символу), значение макроса EILSEQ сохраняется в errno, возвращается (size_t)-1, а состояние преобразования становится неопределённым.

Примечания

Вызовы c8rtomb с нулевым указателем в качестве аргумента s могут привести к гонке данных с другими вызовами c8rtomb с нулевым указателем в качестве аргумента s.

Пример

Ссылки

• Стандарт C23 (ISO/IEC 9899:2024):
• 7.30.1.2 Функция c8rtomb

См. также