MBRTOC32(3) | Library Functions Manual | MBRTOC32(3) |
mbrtoc32
—
#include <uchar.h>
size_t
mbrtoc32
(char32_t * restrict
pc32, const char * restrict s,
size_t n, mbstate_t * restrict
ps);
mbrtoc32
function decodes multibyte characters in
the current locale and converts them to Unicode scalar values (i.e., to
UTF-32), keeping state so it can restart after incremental progress.
Each call to mbrtoc32
:
*
pc32,Specifically:
mbrtoc32
returns
(size_t)-1
and sets
errno(2) to indicate the
error.mbrtoc32
saves its state
in ps after all the input so far and returns
(size_t)-2
.mbrtoc32
decodes the null multibyte character,
then it stores zero at *
pc32
and returns zero.mbrtoc32
decodes a single multibyte
character, stores its Unicode scalar value at
*
pc32, and returns the
number of bytes consumed to decode the first multibyte character.If pc32 is a null pointer, nothing is stored, but the effects on ps and the return value are unchanged.
If s is a null pointer, the
mbrtoc32
call is equivalent to:
mbrtoc32
(NULL
,
""
, 1
,
ps);This always returns zero, and has the effect of resetting ps to the initial conversion state, without writing to pc32, even if it is nonnull.
If ps is a null pointer,
mbrtoc32
uses an internal
mbstate_t object with static storage duration,
distinct from all other mbstate_t objects (including
those used by mbrtoc8(3),
mbrtoc16(3),
c8rtomb(3),
c16rtomb(3), and
c32rtomb(3)), which is
initialized at program startup to the initial conversion state.
mbrtoc32
function returns:
0
mbrtoc32
decoded a null multibyte
character.0
≤
i ≤ n, if
mbrtoc32
consumed i bytes of
input to decode the next multibyte character, yielding a Unicode scalar
value.(size_t)-2
mbrtoc32
found only an incomplete
multibyte sequence after all n bytes of input and
any previous input, and saved its state to restart in the next call with
ps.(size_t)-1
char *s = ...; size_t n = ...; mbstate_t mbs = {0}; /* initial conversion state */ while (n) { char32_t c32; size_t len; len = mbrtoc32(&c32, s, n, &mbs); switch (len) { case 0: /* NUL terminator */ assert(c32 == 0); goto out; default: /* scalar value */ printf("U+%04"PRIx32"\n", (uint32_t)c32); break; case (size_t)-2: /* incomplete */ printf("incomplete\n"); goto readmore; case (size_t)-1: /* error */ printf("error: %d\n", errno); goto out; } s += len; n -= len; }
The Unicode Standard, https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf, The Unicode Consortium, September 2022, Version 15.0 — Core Specification.
mbrtoc32
function conforms to
ISO/IEC 9899:2011 (“ISO C11”).
mbrtoc32
function first appeared in
NetBSD 11.0.
August 14, 2024 | NetBSD 10.1 |