UCHAR(3)

📦 version 11.0, in nixpkgs unstable

✨ UCHAR ✨

okay bestie, so this one is uchar — literally the Unicode utilities page, and it's giving "short but mighty" 💅 the manual name is folded in right here so you don't have to hunt for it, and it lives in the Library Functions Manual section of your fave Debian box.

🌸 SYNOPSIS 🌸

#include <uchar.h>

that's it. that's the whole synopsis. one include. iconic behavior honestly 🎀

💖 DESCRIPTION 💖

so the <uchar.h> header file declares types and functions for manipulating Unicode code units. code units, bestie, not code points — there's a difference and this header is very serious about it 🫶

🦋 Types 🦋

  • char8_t — (C23) unsigned integer type for UTF-8 code units. highkey the baby of the group 🌱 Same type as unsigned char.
  • char16_t — unsigned integer type for UTF-16 code units. Same type as uint_least16_t from <stdint.h>. may represent both surrogate code points, i.e. code points in the interval [0xd800,0xdfff], and Unicode scalar values in the Basic Multilingual Plane, which are the 16-bit code points other than surrogate code points. so it's got range, we love that for it 💜
  • char32_t — unsigned integer type for UTF-32 code units. Same type as uint_least32_t from <stdint.h>. can represent all Unicode scalar values, not just those in the Basic Multilingual Plane. intended to represent only Unicode scalar values, not surrogate code points — read that again, it's a whole vibe check on surrogates and they do not pass 😭
  • mbstate_t — opaque multibyte conversion state. it's opaque, she's mysterious, she's not showing you her internals 🙈 Same type as in stddef.h and wchar.h.
  • size_t — unsigned integer type to represent array sizes. the classic, the legend, the one everybody already knows 👑 Same type as in stddef.h, stdint.h, and sys/types.h.

🧚 Functions 🧚

the <uchar.h> header file declares the functions mbrtoc8(3), c8rtomb(3), mbrtoc16(3), c16rtomb(3), mbrtoc32(3), and c32rtomb(3) for conversion between multibyte sequences and UTF-8/UTF-16/UTF-32 code units. so like, mbr-to-c goes one way and c-to-mbr goes the other, and yes the naming is a whole gymnastic routine but you'll get used to it fr fr ⭐

🔥 SEE ALSO 🔥

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.

P. Hoffman and F. Yergeau, UTF-16, an encoding of ISO 10646, Internet Engineering Task Force, RFC 2781, https://datatracker.ietf.org/doc/html/rfc2781, February 2000.

F. Yergeau, UTF-8, a transformation format of ISO 10646, Internet Engineering Task Force, RFC 3629, https://datatracker.ietf.org/doc/html/rfc3629, November 2003.

💀 STANDARDS 💀

The <uchar.h> header file conforms to ISO/IEC 9899:2011 ("ISO C11") and . — yeah, the original page literally trails off with "and ." right there, and no I'm not fixing it, not me editing the sacred text 🙈 keep it exactly as it is, bestie.

🌈 HISTORY 🌈

The <uchar.h> header file first appeared in NetBSD 11.0. she's new here and she's already main character energy ✨

🫶 reminder because it matters: those surrogate code points in char16_t are allowed there. don't go assuming every char16_t is a real scalar value, or the standard will side-eye you. and char32_t is intended for scalar values only — no surrogate shenanigans, periodt 💅

and that's the whole page, bestie!! source/version says Debian and the date on this beauty is August 15, 2024, filed under UCHAR(3) 🎀 catch you in the next man page, mwah 🍓

📦 where this page comes from