.TH MPU_STR16ING 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_str16cat, mpu_str16chr, mpu_str16chrnul, mpu_str16cmp, mpu_str16cpy,
mpu_str16cspn, mpu_str16dup, mpu_str16ndup, mpu_str16len, mpu_str16ncat, mpu_str16ncmp,
mpu_str16ncpy, mpu_str16nlen, mpu_str16pbrk, mpu_str16rchr, mpu_str16spn,
mpu_str16pcpy, mpu_str16pncpy, mpu_str16str, mpu_str16rstr,
mpu_str16tok, mpu_str16tok_r
\- strict UCS-2 string operations
.SH SYNOPSIS
.nf
#include <libmpuio.h>

__mpu_char16_t *mpu_str16cat( __mpu_char16_t *dest, const __mpu_char16_t *src );
__mpu_char16_t *mpu_str16chr( const __mpu_char16_t *s, __mpu_char16_t c );
__mpu_char16_t *mpu_str16chrnul( const __mpu_char16_t *s, __mpu_char16_t c );
int             mpu_str16cmp( const __mpu_char16_t *s1, const __mpu_char16_t *s2 );
__mpu_char16_t *mpu_str16cpy( __mpu_char16_t *dest, const __mpu_char16_t *src );
__mpu_size_t    mpu_str16cspn( const __mpu_char16_t *s, const __mpu_char16_t *reject );
__mpu_char16_t *mpu_str16dup( const __mpu_char16_t *s );
__mpu_char16_t *mpu_str16ndup( const __mpu_char16_t *s, __mpu_size_t n );
__mpu_size_t    mpu_str16len( const __mpu_char16_t *s );
__mpu_char16_t *mpu_str16ncat( __mpu_char16_t *dest, const __mpu_char16_t *src, __mpu_size_t n );
int             mpu_str16ncmp( const __mpu_char16_t *s1, const __mpu_char16_t *s2, __mpu_size_t n );
__mpu_char16_t *mpu_str16ncpy( __mpu_char16_t *dest, const __mpu_char16_t *src, __mpu_size_t n );
__mpu_size_t    mpu_str16nlen( const __mpu_char16_t *s, __mpu_size_t maxlen );
__mpu_char16_t *mpu_str16pbrk( const __mpu_char16_t *s, const __mpu_char16_t *accept );
__mpu_char16_t *mpu_str16rchr( const __mpu_char16_t *s, __mpu_char16_t c );
__mpu_size_t    mpu_str16spn( const __mpu_char16_t *s, const __mpu_char16_t *accept );
__mpu_char16_t *mpu_str16pcpy( __mpu_char16_t *dest, const __mpu_char16_t *src );
__mpu_char16_t *mpu_str16pncpy( __mpu_char16_t *dest, const __mpu_char16_t *src, __mpu_size_t n );
__mpu_char16_t *mpu_str16str( const __mpu_char16_t *haystack, const __mpu_char16_t *needle );
__mpu_char16_t *mpu_str16rstr( const __mpu_char16_t *haystack, const __mpu_char16_t *needle );
__mpu_char16_t *mpu_str16tok( __mpu_char16_t *s, const __mpu_char16_t *delim );
__mpu_char16_t *mpu_str16tok_r( __mpu_char16_t *s, const __mpu_char16_t *delim,
                                __mpu_char16_t **saveptr );
.fi
.SH DESCRIPTION
These routines are the UCS-2 counterparts of the LIBMPUIO 8-bit string
functions.  Strings are arrays of
.B __mpu_char16_t
terminated by a zero code unit.  The count argument
.I n
is measured in 16-bit code units.
.PP
The copy, concatenate, compare, search, span and length operations mirror the
corresponding libc string contracts, but operate on
.B __mpu_char16_t
objects.
.PP
.B mpu_str16ncpy()
copies at most
.I n
code units and pads the remainder with zero code units when the source is
shorter.  As with
.BR strncpy (3),
truncation does not append an extra terminator.
.PP
.B mpu_str16pcpy()
returns the address of the terminating zero written to
.IR dest .
.PP
.B mpu_str16pncpy()
copies and pads like
.B mpu_str16ncpy().
For a short source it returns the address of the first zero written to
.IR dest ;
for a source of at least
.I n
code units it returns
.IR dest+n .
.PP
.B mpu_str16rstr()
finds the last occurrence of
.IR needle .
An empty needle matches the terminating zero of the haystack.
.PP
.B mpu_str16tok()
provides strtok-style stateful tokenization for UCS-2 strings.  Its
continuation pointer is thread-local: different threads have independent
state, while nested tokenization within one thread still interferes in the
same way as ordinary strtok(3).
.PP
.B mpu_str16tok_r()
provides reentrant tokenization and modifies its input buffer by replacing
separators with zero code units.
.PP
.BR mpu_str16dup ()
and
.B mpu_str16ndup()
return malloc-allocated duplicates.  The bounded form copies at most
.I n
UCS-2 code units and appends a terminating zero.  Passing NULL returns NULL and sets
.B errno
to
.BR EINVAL .
.SH UCS-2 RULES
This API is intended for LIBMPUIO's strict UCS-2 internal representation.
The elementary string operations compare and copy code units; they do not
perform Unicode normalization or case folding.
.SH RETURN VALUE
Length and span functions return counts in 16-bit code units.  Pointer and
comparison functions follow the contracts described above.
.SH SEE ALSO
.BR mpu_str8ing (3),
.BR mpu_utf8ing (3),
.BR mpu_string_conversion (3)