.TH MPU_STR8ING 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
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
\- ordinary 8-bit C string operations
.SH SYNOPSIS
.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 DESCRIPTION
These functions operate on ordinary NUL-terminated 8-bit C strings.
Their basic contracts follow the corresponding libc string functions.
They do not interpret the byte sequence as UTF-8; character-oriented UTF-8
operations are provided by the
.B mpu_utf8*
family.
.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 ()
and
.BR mpu_str8nlen ()
follow the usual libc semantics.
.PP
.B mpu_str8chrnul()
returns the matching byte or, if no match exists, a pointer to the terminating
NUL byte.
.PP
.B mpu_str8pcpy()
copies the complete string and returns a pointer to the terminating NUL in
.IR dest .
.PP
.B mpu_str8pncpy()
is the pointer-returning bounded-copy variant used by LIBMPUIO.  It copies and
pads exactly as
.BR strncpy (3).
If the source string terminates before
.I n
bytes, the return value points to the first NUL written to
.IR dest .
If no NUL is encountered in the first
.I n
source bytes, the return value is
.IR dest+n .
.PP
.B mpu_str8rstr()
returns the last occurrence of
.I needle
in
.IR haystack .
For an empty
.I needle
it returns a pointer to the terminating NUL of
.IR haystack .
.PP
.B mpu_str8tok()
is the stateful tokenizer analogous to
.BR strtok (3).
The continuation pointer is stored in thread-local storage, so independent
threads do not share tokenizer state.  Calls within one thread still share one
continuation state and therefore are not reentrant.
.PP
.B mpu_str8tok_r()
is a reentrant tokenizer analogous to
.BR strtok_r (3).
The caller supplies storage for the continuation pointer through
.IR saveptr .
.PP
.BR mpu_str8dup ()
and
.B mpu_str8ndup()
allocate duplicates with
.BR malloc (3).
.B mpu_str8ndup()
copies at most
.I n
bytes and always appends a terminating NUL.  The caller releases either result with
.BR free (3).
Passing NULL sets
.B errno
to
.B EINVAL
and returns NULL.
.SH RETURN VALUE
The pointer-returning and comparison functions follow the corresponding libc
conventions described above.  Length and span functions return byte counts.
.BR mpu_str8dup ()
and
.B mpu_str8ndup()
return NULL on failure.
.SH NOTES
The destination object must be large enough for every copying or concatenation
operation, exactly as for the corresponding libc routine.
.PP
Use
.BR mpu_utf8ing (3)
when
.I n
must denote UTF-8 characters instead of bytes.
.SH SEE ALSO
.BR string (3),
.BR mpu_str16ing (3),
.BR mpu_utf8ing (3),
.BR mpu_string_conversion (3)