Skip to content
Tutorials Center
My learning

Topics

C Reference ยท ctype.h, math.h and others

C uchar.h: char16_t, char32_t and Unicode

Reference for uchar.h: the Unicode character types char16_t and char32_t, u and U string literals, converting UTF-8 with mbrtoc32 and c32rtomb, and surrogate pairs.

<uchar.h> gives C types with a fixed meaning for Unicode text. char32_t is an unsigned 32-bit type that holds exactly one Unicode code point (UTF-32). char16_t is an unsigned 16-bit type for UTF-16 code units, where code points above U+FFFF take two units called a surrogate pair. C23 adds char8_t, an unsigned type for UTF-8 code units, and makes u8 literals use it.

Unlike wchar_t, whose width and encoding vary by platform, these types are the same everywhere. The header also provides conversion functions between the locale's multibyte encoding (usually UTF-8) and the two Unicode encodings. Literals have matching prefixes: u'x' and u"text" are UTF-16, U'x' and U"text" are UTF-32, and u8"text" is UTF-8.

C
#include <uchar.h>

char32_t smile = U'\U0001F600';
char16_t text[] = u"cafรฉ";

Try it

C Decoding UTF-8 into code points

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

C UTF-16, UTF-32 and surrogate pairs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Syntax

C
#include <uchar.h>

typedef /* uint_least16_t */ char16_t;
typedef /* uint_least32_t */ char32_t;
typedef unsigned char        char8_t;     /* C23 */

size_t mbrtoc16(char16_t *restrict pc16, const char *restrict s, size_t n, mbstate_t *restrict ps);
size_t c16rtomb(char *restrict s, char16_t c16, mbstate_t *restrict ps);
size_t mbrtoc32(char32_t *restrict pc32, const char *restrict s, size_t n, mbstate_t *restrict ps);
size_t c32rtomb(char *restrict s, char32_t c32, mbstate_t *restrict ps);
Name Description
pc16, pc32 Where to store the converted character, or NULL to just measure.
s, n The multibyte input and the most bytes to examine.
ps Conversion state (mbstate_t), zero-initialized before the first call. Needed because UTF-16 characters can come in two steps.
c16, c32 The Unicode unit to encode. The output buffer s must hold at least MB_CUR_MAX bytes.

Returns: the mbrtoc* functions return the number of bytes consumed, 0 if the character was a null, (size_t)-1 for an encoding error (with errno set to EILSEQ), (size_t)-2 for an incomplete sequence, and, for mbrtoc16 only, (size_t)-3 when the next unit of a surrogate pair is delivered without consuming input. The c*rtomb functions return the number of bytes written or (size_t)-1 on error.

Errors / undefined behavior: passing an uninitialized mbstate_t, or a destination buffer that is too small, is undefined. The conversions depend on the current LC_CTYPE locale: in the default "C" locale only ASCII works.

Usage notes

  • Pick the locale first. mbrtoc32 converts from the locale's multibyte encoding. To read UTF-8, the locale must be a UTF-8 one (see locale.h); c32rtomb writes UTF-8 bytes under the same condition. The runner has en_US.UTF-8 and C.UTF-8.
  • Surrogate pairs. A code point above U+FFFF becomes two char16_t units in UTF-16. The first call to mbrtoc16 returns the number of input bytes together with the high surrogate. The next call (with the same ps) returns (size_t)-3 and the low surrogate. Counting char16_t elements is not counting characters.
  • Literals are encoded by the compiler. u"..." and U"..." do not depend on the locale or on the source file encoding, because escapes like รฉ and \U0001F600 name Unicode code points directly.
  • A code point is not a user-perceived character. Accents may be separate code points (combining marks), and emoji sequences contain several. Counting char32_t units still does not give "characters on screen"; that needs a library such as ICU.
  • char8_t and u8 literals. C23 declares char8_t as unsigned char and gives u8"..." the type char8_t[]. The runner's glibc 2.28 <uchar.h> does not define char8_t yet, so the examples use plain char for UTF-8 bytes. Treat char8_t code as read-only here.
  • Not for the platform API. wchar_t is still what Windows APIs and many libraries expect; convert at the boundary.
  • Cost. Each conversion call decodes one character in O(1). UTF-32 uses 4 bytes per code point, UTF-8 between 1 and 4.
  • Standard version: C11 for char16_t, char32_t and the conversion functions (the macros __STDC_UTF_16__ and __STDC_UTF_32__ announce that they use UTF-16 and UTF-32); char8_t is new in C23.