.TH MPU_STRING_CONVERSION 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_ucs2_to_utf8, mpu_utf8_to_ucs2
\- convert between LIBMPUIO strict UCS-2 strings and UTF-8
.SH SYNOPSIS
.nf
#include <libmpuio.h>

__mpu_size_t mpu_ucs2_to_utf8( __mpu_char8_t *dest, const __mpu_char16_t *src, __mpu_size_t nb );
__mpu_size_t mpu_utf8_to_ucs2( __mpu_char16_t *dest, const __mpu_char8_t *src, __mpu_size_t nb );
.fi
.SH DESCRIPTION
These functions convert between LIBMPUIO's internal strict UCS-2 text form and
its external UTF-8 representation.  They deliberately use ordinary caller
provided buffers; no pointer-to-pointer string object is required.
.PP
.B mpu_ucs2_to_utf8()
converts the NUL-terminated UCS-2 string
.I src
to UTF-8.  The
.I nb
argument is the available destination size in bytes.
.PP
.B mpu_utf8_to_ucs2()
converts the NUL-terminated UTF-8 string
.I src
to strict UCS-2.  The
.I nb
argument is the available destination size in
.B __mpu_char16_t
code units.
.PP
If
.I dest
is NULL, no output is written and
.I nb
is ignored.  The function validates the complete input and returns the exact
size required for the converted payload, excluding the terminating NUL.  This
provides the usual two-pass sizing pattern without requiring a double pointer.
.PP
If
.I dest
is non-NULL, as much complete output as fits is written.  A terminating NUL is
written only when room remains after the complete converted payload.  The
return value is the amount of converted payload actually written, excluding a
terminator.
.SH STRICT UCS-2
UCS-2 surrogate code units U+D800 through U+DFFF are invalid input to
.BR mpu_ucs2_to_utf8 ().
Likewise,
.B mpu_utf8_to_ucs2()
rejects valid UTF-8 characters above U+FFFF because they cannot be represented
by one strict UCS-2 code unit.  Surrogate scalar values and malformed UTF-8 are
also rejected.
.SH RETURN VALUE
On success,
.B mpu_ucs2_to_utf8()
returns a byte count and
.B mpu_utf8_to_ucs2()
returns a UCS-2 code-unit count.  The terminating NUL is not included.
.PP
On encoding error the functions return
.B (__mpu_size_t)-1
and set
.B errno
to
.BR EILSEQ .
.SH EXAMPLE
.nf
__mpu_char16_t  text[] = MPU_UCS2( "Hello" );
__mpu_size_t    bytes;
__mpu_char8_t  *utf8;

bytes = mpu_ucs2_to_utf8( NULL, text, 0 );
utf8 = malloc( bytes + 1 );
if( utf8 != NULL )
  mpu_ucs2_to_utf8( utf8, text, bytes + 1 );
.fi
.SH SEE ALSO
.BR mpu_str16ing (3),
.BR mpu_utf8ing (3),
.BR mpu_printf (3)