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.
#include <uchar.h> char32_t smile = U'\U0001F600'; char16_t text[] = u"cafรฉ";
Try it
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.
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
#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.
mbrtoc32converts from the locale's multibyte encoding. To read UTF-8, the locale must be a UTF-8 one (see locale.h);c32rtombwrites UTF-8 bytes under the same condition. The runner hasen_US.UTF-8andC.UTF-8. - Surrogate pairs. A code point above U+FFFF becomes two
char16_tunits in UTF-16. The first call tombrtoc16returns the number of input bytes together with the high surrogate. The next call (with the sameps) returns(size_t)-3and the low surrogate. Countingchar16_telements is not counting characters. - Literals are encoded by the compiler.
u"..."andU"..."do not depend on the locale or on the source file encoding, because escapes likeรฉand\U0001F600name 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_tunits still does not give "characters on screen"; that needs a library such as ICU. char8_tandu8literals. C23 declareschar8_tasunsigned charand givesu8"..."the typechar8_t[]. The runner's glibc 2.28<uchar.h>does not definechar8_tyet, so the examples use plaincharfor UTF-8 bytes. Treatchar8_tcode as read-only here.- Not for the platform API.
wchar_tis 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_tand the conversion functions (the macros__STDC_UTF_16__and__STDC_UTF_32__announce that they use UTF-16 and UTF-32);char8_tis new in C23.
Related
- wchar.h, locale.h, Multibyte conversion, char, Literals, stdint.h
- Lessons: Characters, Strings, Type limits