.TH MPU_UTF8ING 3 "Август 2026" "libmpuio" "Руководство программиста LIBMPUIO"
.SH ИМЯ
mpu_utf8next, mpu_utf8prev, mpu_utf8last, mpu_utf8get, mpu_utf8len,
mpu_utf8nlen, mpu_utf8bytes, mpu_utf8nbytes, mpu_utf8valid, mpu_utf8_offset2index, mpu_utf8_index2offset, mpu_utf8cmp,
mpu_utf8ncmp, mpu_utf8cpy, mpu_utf8cat, mpu_utf8ncpy, mpu_utf8ncat,
mpu_utf8pcpy, mpu_utf8pncpy, mpu_utf8chr, mpu_utf8chrnul, mpu_utf8rchr,
mpu_utf8spn, mpu_utf8cspn, mpu_utf8pbrk, mpu_utf8str, mpu_utf8rstr,
mpu_utf8tok, mpu_utf8tok_r, mpu_utf8dup, mpu_utf8ndup
\- операции со строками и символами UTF-8
.SH ОБЗОР
.nf
#include <libmpuio.h>

const __mpu_char8_t *mpu_utf8next( const __mpu_char8_t *p );
const __mpu_char8_t *mpu_utf8prev( const __mpu_char8_t *start, const __mpu_char8_t *p );
const __mpu_char8_t *mpu_utf8last( const __mpu_char8_t *s );
const __mpu_char8_t *mpu_utf8get( const __mpu_char8_t *p, __mpu_char32_t *value );
__mpu_size_t         mpu_utf8len( const __mpu_char8_t *s );
__mpu_size_t         mpu_utf8nlen( const __mpu_char8_t *s, __mpu_size_t maxlen );
__mpu_size_t         mpu_utf8bytes( const __mpu_char8_t *s );
__mpu_size_t         mpu_utf8nbytes( const __mpu_char8_t *s, __mpu_size_t n );
int                  mpu_utf8valid( const __mpu_char8_t *s );
__mpu_size_t         mpu_utf8_offset2index( const __mpu_char8_t *s, __mpu_size_t offset );
__mpu_size_t         mpu_utf8_index2offset( const __mpu_char8_t *s, __mpu_size_t index );
int                  mpu_utf8cmp( const __mpu_char8_t *s1, const __mpu_char8_t *s2 );
int                  mpu_utf8ncmp( const __mpu_char8_t *s1, const __mpu_char8_t *s2, __mpu_size_t n );
__mpu_char8_t       *mpu_utf8cpy( __mpu_char8_t *dest, const __mpu_char8_t *src );
__mpu_char8_t       *mpu_utf8cat( __mpu_char8_t *dest, const __mpu_char8_t *src );
__mpu_char8_t       *mpu_utf8ncpy( __mpu_char8_t *dest, const __mpu_char8_t *src, __mpu_size_t n );
__mpu_char8_t       *mpu_utf8ncat( __mpu_char8_t *dest, const __mpu_char8_t *src, __mpu_size_t n );
__mpu_char8_t       *mpu_utf8pcpy( __mpu_char8_t *dest, const __mpu_char8_t *src );
__mpu_char8_t       *mpu_utf8pncpy( __mpu_char8_t *dest, const __mpu_char8_t *src, __mpu_size_t n );
__mpu_char8_t       *mpu_utf8chr( const __mpu_char8_t *s, __mpu_char32_t c );
__mpu_char8_t       *mpu_utf8chrnul( const __mpu_char8_t *s, __mpu_char32_t c );
__mpu_char8_t       *mpu_utf8rchr( const __mpu_char8_t *s, __mpu_char32_t c );
__mpu_size_t         mpu_utf8spn( const __mpu_char8_t *s, const __mpu_char8_t *accept );
__mpu_size_t         mpu_utf8cspn( const __mpu_char8_t *s, const __mpu_char8_t *reject );
__mpu_char8_t       *mpu_utf8pbrk( const __mpu_char8_t *s, const __mpu_char8_t *accept );
__mpu_char8_t       *mpu_utf8str( const __mpu_char8_t *haystack, const __mpu_char8_t *needle );
__mpu_char8_t       *mpu_utf8rstr( const __mpu_char8_t *haystack, const __mpu_char8_t *needle );
__mpu_char8_t       *mpu_utf8tok( __mpu_char8_t *s, const __mpu_char8_t *delim );
__mpu_char8_t       *mpu_utf8tok_r( __mpu_char8_t *s, const __mpu_char8_t *delim, __mpu_char8_t **saveptr );
__mpu_char8_t       *mpu_utf8dup( const __mpu_char8_t *s );
__mpu_char8_t       *mpu_utf8ndup( const __mpu_char8_t *s, __mpu_size_t n );
.fi
.SH ОПИСАНИЕ
Семейство
.B mpu_utf8*
работает с NUL-терминированными байтовыми строками UTF-8.  Декодирование UTF-8
строгое: принимаются только современные последовательности длиной от одного до
четырёх байтов, представляющие скалярные значения Unicode до U+10FFFF.
Избыточные кодировки, суррогатные кодовые точки, некорректные байты продолжения
и исторические пяти- и шестибайтовые формы отвергаются.
.PP
.BR mpu_utf8next (),
.BR mpu_utf8prev ()
и
.BR mpu_utf8last ()
возвращают границы символов.
.B mpu_utf8get()
декодирует один символ в
.I *value
и возвращает границу следующего символа.  На завершающем NUL функция сохраняет
ноль и возвращает тот же указатель.
.PP
.B mpu_utf8len()
возвращает число символов Unicode, а не байтов.
.B mpu_utf8nlen()
возвращает не более
.I maxlen
символов.
.B mpu_utf8bytes()
проверяет всю строку и возвращает её длину в байтах без завершающего NUL.
.B mpu_utf8nbytes()
возвращает число байтов, занимаемое не более чем первыми
.I n
символами UTF-8.  Функция никогда не останавливается внутри многобайтовой
последовательности.
.B mpu_utf8valid()
возвращает ненулевое значение только если вся строка является корректным UTF-8.
.PP
.B mpu_utf8_offset2index()
преобразует отсчитываемое от нуля смещение в символах в байтовый индекс.
.B mpu_utf8_index2offset()
преобразует байтовый индекс в смещение в символах.  Если
.I index
указывает внутрь многобайтового символа, возвращаемое смещение обозначает
символ, следующий за этой байтовой позицией, в соответствии с историческим
соглашением строк LIBMPUIO.
.PP
.BR mpu_utf8cmp ()
и
.BR mpu_utf8ncmp ()
сравнивают декодированные скалярные значения Unicode.  Аргумент
.I n
функции
.B mpu_utf8ncmp()
задаёт число символов.
.PP
.BR mpu_utf8cpy ()
и
.BR mpu_utf8cat ()
копируют полные корректные байтовые строки в той же форме хранения, что и
обычные строки C.  Ограниченные функции
.B mpu_utf8ncpy()
и
.B mpu_utf8ncat()
интерпретируют
.I n
как число символов UTF-8 и никогда не разрывают многобайтовый символ.
Результат завершается NUL.
.BR mpu_utf8pcpy ()
копирует полную строку UTF-8 и возвращает указатель на завершающий NUL.
.BR mpu_utf8pncpy ()
копирует не более
.I n
символов UTF-8, никогда не разрывает многобайтовую последовательность, всегда
записывает завершающий NUL и возвращает указатель на этот NUL.
.PP
.BR mpu_utf8chr ()
и
.BR mpu_utf8rchr ()
ищут скалярное значение Unicode.
.B mpu_utf8chrnul()
возвращает найденный символ либо завершающий NUL, если совпадения нет.
.PP
.BR mpu_utf8spn ()
и
.BR mpu_utf8cspn ()
возвращают число символов, а не байтов.
.B mpu_utf8pbrk()
возвращает первый символ в
.IR s ,
который присутствует в наборе символов UTF-8
.IR accept .
.BR mpu_utf8str ()
и
.BR mpu_utf8rstr ()
ищут подстроки UTF-8.
.B mpu_utf8tok()
\- токенизатор с состоянием, аналогичный strtok(3), но наборы разделителей
интерпретируются как символы UTF-8.  Его указатель продолжения является
thread-local, поэтому разные потоки выполнения имеют независимое состояние
токенизатора; вложенное использование в одном потоке не является
реентерабельным.
.PP
.B mpu_utf8tok_r()
\- реентерабельный токенизатор, аналогичный strtok_r(3), за исключением того,
что наборы разделителей интерпретируются как символы UTF-8.  Следовательно,
разделители могут быть многобайтовыми.
.BR mpu_utf8dup ()
и
.B mpu_utf8ndup()
возвращают строки UTF-8, выделенные через malloc.  Ограниченная форма копирует
не более
.I n
символов и никогда не разрывает многобайтовую последовательность.
.SH ОШИБКИ
При некорректном UTF-8 функции декодирования символов устанавливают
.B errno
в
.B EILSEQ
и возвращают NULL либо
.BR (__mpu_size_t)-1 ,
в зависимости от интерфейса.
.SH ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Если не указано иное, функции, возвращающие указатели, возвращают NULL при
ошибке.  Функции подсчёта символов, байтов и преобразования индексов возвращают
.B (__mpu_size_t)-1
для некорректного UTF-8.
.B mpu_utf8valid()
возвращает ноль для некорректного UTF-8 и оставляет
.B errno
равным
.BR EILSEQ .
.SH ПРИМЕЧАНИЯ
Эти функции не выполняют нормализацию Unicode, collation или преобразование
регистра.  Поиск подстроки работает по байтовому представлению UTF-8;
корректность UTF-8 гарантирует, что корректно закодированный символ не может
начинаться с байта продолжения.
.SH СМ. ТАКЖЕ
.BR mpu_str8ing (3),
.BR mpu_str16ing (3),
.BR mpu_string_conversion (3)