C32RTOMB(3) | Library Functions Manual | C32RTOMB(3) |
c32rtomb
—
#include <uchar.h>
size_t
c32rtomb
(char * restrict s,
char32_t c32, mbstate_t * restrict
ps);
c32rtomb
function converts Unicode scalar values to
multibyte characters in the current locale, keeping state to remember
incremental progress if restarted.
Each call to c32rtomb
updates the
conversion state ps with a UTF-32 code unit
c32, writes up to MB_CUR_MAX
bytes to s, and returns either the number of bytes
written to s or (size_t)-1
to
denote error.
The input c32 is a UTF-32 code unit, representing a Unicode scalar value, i.e., a Unicode code point that is not a surrogate code point — in other words, c32 is an integer either in [0,0xd7ff] or in [0xe000,0x10ffff].
If s is a null pointer, no output is
produced and ps is reset to the initial conversion
state, as if the call had been
c8rtomb
(buf,
0
, ps); for some internal
buffer buf.
If c32 is zero,
c32rtomb
outputs a (possibly empty) shift sequence
to restore the initial state followed by a NUL byte and resets
ps to the initial conversion state.
If ps is a null pointer,
c32rtomb
uses an internal
mbstate_t object with static storage duration,
distinct from all other mbstate_t objects (including
those used by other functions such as
mbrtoc32(3)), which is
initialized at program startup to the initial conversion state.
c32rtomb
function returns the number of bytes
written to s on success, or sets
errno(2) and returns
(size_t)-1
on failure.
char32_t c32[] = { 0x1f4a9, 0x20ac, 0x21 }; char buf[(__arraycount(c32) + 1)*MB_LEN_MAX], *s = buf; size_t i; mbstate_t mbs = {0}; /* initial conversion state */ for (i = 0; i < __arraycount(c32); i++) { size_t len; len = c32rtomb(s, c32[i], &mbs); if (len == (size_t)-1) err(1, "c32rtomb"); assert(len < sizeof(buf) - (s - buf)); s += len; } len = c32rtomb(s, 0, &mbs); /* NUL-terminate */ if (len == (size_t)-1) err(1, "c32rtomb"); assert(len <= sizeof(buf) - (s - buf)); printf("%s\n", buf);
To avoid a variable-length array, this code uses
MB_LEN_MAX
, which is a constant upper bound on the
locale-dependent MB_CUR_MAX
.
EILSEQ
]EILSEQ
]EIO
]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.
c32rtomb
function conforms to
ISO/IEC 9899:2011 (“ISO C11”).
c32rtomb
function first appeared in
NetBSD 11.0.
August 14, 2024 | NetBSD 10.1 |