mbrtoc8

size_t mbrtoc8( char8_t* restrict pc8, const char* restrict s, size_t n,
                mbstate_t* restrict ps );

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

Если s не является нулевым указателем, функция проверяет не более n байтов строки многобайтовых символов, начиная с байта, на который указывает s, чтобы определить количество байтов, необходимое для завершения следующего многобайтового символа (включая любые последовательности переключения). Если функция определяет, что следующий многобайтовый символ в s является полным и допустимым, она преобразует его в UTF-8 и сохраняет первую кодовую единицу UTF-8 в *pc8 (если pc8 не является нулевым указателем).

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

Если s является нулевым указателем, значения n и pc8 игнорируются, а вызов эквивалентен mbrtoc8(nullptr, "", 1, ps).

Если полученная кодовая единица UTF-8 равна u8'\0', состояние преобразования *ps представляет исходное состояние переключения.

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

Параметры

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

Первое из следующих применимых значений:

• 0, если символ, преобразованный из s (и сохранённый в *pc8, если указатель не равен нулю), был нулевым символом.
• Количество байтов [1, n] многобайтового символа, успешно преобразованного из s.
• (size_t)-3, если следующая кодовая единица UTF-8 символа, кодировка которого состоит из нескольких кодовых единиц, была записана в *pc8. В этом случае входные байты не обрабатываются.
• (size_t)-2, если следующие n байтов образуют неполный, но пока допустимый многобайтовый символ. В *pc8 ничего не записывается.
• (size_t)-1, если произошла ошибка кодирования. В *pc8 ничего не записывается, значение EILSEQ сохраняется в errno, а значение *ps не определено.

Пример

Ссылки

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

См. также