.TH MPU_STR8ING 3 "Август 2026" "libmpuio" "Руководство программиста LIBMPUIO"
.SH ИМЯ
mpu_str8cat, mpu_str8chr, mpu_str8chrnul, mpu_str8cmp, mpu_str8cpy,
mpu_str8cspn, mpu_str8dup, mpu_str8ndup, mpu_str8len, mpu_str8ncat, mpu_str8ncmp,
mpu_str8ncpy, mpu_str8nlen, mpu_str8pbrk, mpu_str8rchr, mpu_str8spn,
mpu_str8pcpy, mpu_str8pncpy, mpu_str8str, mpu_str8rstr, mpu_str8tok, mpu_str8tok_r
\- операции с обычными 8-битными строками C
.SH ОБЗОР
.nf
#include <libmpuio.h>

__mpu_char8_t   *mpu_str8cat( __mpu_char8_t *dest, const __mpu_char8_t *src );
__mpu_char8_t   *mpu_str8chr( const __mpu_char8_t *s, int c );
__mpu_char8_t   *mpu_str8chrnul( const __mpu_char8_t *s, int c );
int              mpu_str8cmp( const __mpu_char8_t *s1, const __mpu_char8_t *s2 );
__mpu_char8_t   *mpu_str8cpy( __mpu_char8_t *dest, const __mpu_char8_t *src );
__mpu_size_t     mpu_str8cspn( const __mpu_char8_t *s, const __mpu_char8_t *reject );
__mpu_char8_t   *mpu_str8dup( const __mpu_char8_t *s );
__mpu_char8_t   *mpu_str8ndup( const __mpu_char8_t *s, __mpu_size_t n );
__mpu_size_t     mpu_str8len( const __mpu_char8_t *s );
__mpu_char8_t   *mpu_str8ncat( __mpu_char8_t *dest, const __mpu_char8_t *src, __mpu_size_t n );
int              mpu_str8ncmp( const __mpu_char8_t *s1, const __mpu_char8_t *s2, __mpu_size_t n );
__mpu_char8_t   *mpu_str8ncpy( __mpu_char8_t *dest, const __mpu_char8_t *src, __mpu_size_t n );
__mpu_size_t     mpu_str8nlen( const __mpu_char8_t *s, __mpu_size_t maxlen );
__mpu_char8_t   *mpu_str8pbrk( const __mpu_char8_t *s, const __mpu_char8_t *accept );
__mpu_char8_t   *mpu_str8rchr( const __mpu_char8_t *s, int c );
__mpu_size_t     mpu_str8spn( const __mpu_char8_t *s, const __mpu_char8_t *accept );
__mpu_char8_t   *mpu_str8pcpy( __mpu_char8_t *dest, const __mpu_char8_t *src );
__mpu_char8_t   *mpu_str8pncpy( __mpu_char8_t *dest, const __mpu_char8_t *src, __mpu_size_t n );
__mpu_char8_t   *mpu_str8str( const __mpu_char8_t *haystack, const __mpu_char8_t *needle );
__mpu_char8_t   *mpu_str8rstr( const __mpu_char8_t *haystack, const __mpu_char8_t *needle );
__mpu_char8_t   *mpu_str8tok( __mpu_char8_t *s, const __mpu_char8_t *delim );
__mpu_char8_t   *mpu_str8tok_r( __mpu_char8_t *s, const __mpu_char8_t *delim, __mpu_char8_t **saveptr );
.fi
.SH ОПИСАНИЕ
Эти функции работают с обычными NUL-терминированными 8-битными строками C.
Их основные контракты соответствуют аналогичным строковым функциям libc.
Они не интерпретируют последовательность байтов как UTF-8; операции UTF-8,
ориентированные на символы, предоставляет семейство
.BR mpu_utf8* .
.PP
.BR mpu_str8cat (),
.BR mpu_str8cpy (),
.BR mpu_str8ncat (),
.BR mpu_str8ncpy (),
.BR mpu_str8cmp (),
.BR mpu_str8ncmp (),
.BR mpu_str8chr (),
.BR mpu_str8rchr (),
.BR mpu_str8str (),
.BR mpu_str8pbrk (),
.BR mpu_str8spn (),
.BR mpu_str8cspn (),
.BR mpu_str8len ()
и
.BR mpu_str8nlen ()
следуют обычной семантике libc.
.PP
.B mpu_str8chrnul()
возвращает указатель на совпавший байт либо, если совпадения нет, указатель на
завершающий байт NUL.
.PP
.B mpu_str8pcpy()
копирует всю строку и возвращает указатель на завершающий NUL в
.IR dest .
.PP
.B mpu_str8pncpy()
\- ограниченный вариант копирования с возвратом указателя, используемый
LIBMPUIO.  Он копирует и дополняет буфер в точности как
.BR strncpy (3).
Если исходная строка заканчивается раньше
.I n
байтов, возвращаемое значение указывает на первый NUL, записанный в
.IR dest .
Если в первых
.I n
байтах источника NUL не встретился, возвращается
.IR dest+n .
.PP
.B mpu_str8rstr()
возвращает последнее вхождение
.I needle
в
.IR haystack .
Для пустой
.I needle
возвращается указатель на завершающий NUL
.IR haystack .
.PP
.B mpu_str8tok()
\- токенизатор с состоянием, аналогичный
.BR strtok (3).
Указатель продолжения хранится в thread-local storage, поэтому разные потоки
выполнения не разделяют состояние токенизатора.  Однако вызовы внутри одного
потока по-прежнему используют одно общее состояние продолжения и потому не
являются реентерабельными.
.PP
.B mpu_str8tok_r()
\- реентерабельный токенизатор, аналогичный
.BR strtok_r (3).
Вызывающая сторона предоставляет хранилище для указателя продолжения через
.IR saveptr .
.PP
.BR mpu_str8dup ()
и
.B mpu_str8ndup()
выделяют копии через
.BR malloc (3).
.B mpu_str8ndup()
копирует не более
.I n
байтов и всегда добавляет завершающий NUL.  Обе полученные строки вызывающая
сторона освобождает через
.BR free (3).
Передача NULL устанавливает
.B errno
в
.B EINVAL
и возвращает NULL.
.SH ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функции, возвращающие указатели, и функции сравнения следуют описанным выше
соглашениям соответствующих функций libc.  Функции длины и span возвращают
число байтов.
.BR mpu_str8dup ()
и
.B mpu_str8ndup()
при ошибке возвращают NULL.
.SH ПРИМЕЧАНИЯ
Объект назначения должен быть достаточно велик для каждой операции копирования
или конкатенации, ровно как и для соответствующей функции libc.
.PP
Используйте
.BR mpu_utf8ing (3),
если
.I n
должно обозначать число символов UTF-8, а не байтов.
.SH СМ. ТАКЖЕ
.BR string (3),
.BR mpu_str16ing (3),
.BR mpu_utf8ing (3),
.BR mpu_string_conversion (3)