Skip to content

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.