Tcl_UtfToUpper(3)

💖 Tcl_UtfToUpper — bestie edition 💖

okay so this is the Tcl_UtfToUpper(3) page from the Tcl Library Procedures, and it's literally all about making letters go BIG, small, or that fancy in-between title-case situation. six routines, one vibe: case conversion for Unicode characters and UTF-8 strings. let's get into it 🦋

---

✨ NAME ✨

Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle — routines for manipulating the case of Unicode characters and UTF-8 strings 👑

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

int
Tcl_UniCharToUpper(ch)

int
Tcl_UniCharToLower(ch)

int
Tcl_UniCharToTitle(ch)

Tcl_Size
Tcl_UtfToUpper(str)

Tcl_Size
Tcl_UtfToLower(str)

Tcl_Size
Tcl_UtfToTitle(str)

---

🎀 ARGUMENTS 🎀

• int ch (in) — the Unicode character you wanna convert. one single character, that's the whole job 💅
• char *str (in/out) — pointer to a UTF-8 string that gets converted in place. yes bestie, in place, it edits the string right where it's sitting 🙈

---

🌈 DESCRIPTION 🌈

so the first three routines are the single-character girlies. they each convert the case of one individual Unicode character:

• if ch is giving lower-case energy, Tcl_UniCharToLower... wait no, Tcl_UniCharToUpper returns the matching upper-case character. and if there's no upper-case character defined for it? it just hands you back the character unchanged. no drama 💜
• if ch is giving upper-case energy, Tcl_UniCharToLower returns the matching lower-case character. if no lower-case character is defined, again, character comes back unchanged, no cap ✨
• if ch is lower-case, Tcl_UniCharToTitle returns the corresponding title-case character. if there's no title-case character defined, it returns the corresponding upper-case character instead. and if there's no upper-case character defined either? you guessed it — unchanged, character stays exactly as it was 🫶
  • title-case is only defined for a small number of characters that look different when they're sitting at the beginning of a capitalized word. it's giving special-occasion formatting, not an everyday thing 👑

then the next three routines handle whole UTF-8 strings, converting them in place in memory:

• Tcl_UtfToUpper changes every UTF-8 character in str to upper-case. heads up though: because changing the case of a character can change its size, the byte offset of each character in the resulting string may not match where it was originally. Tcl_UtfToUpper writes a null byte at the end of the converted string, and returns the new length of the string in bytes. that new length is guaranteed to be no longer than the original string length. iconic behavior fr fr 🔥
• Tcl_UtfToLower is the same as Tcl_UtfToUpper except it turns each character in the string into its lower-case equivalent 💖
• Tcl_UtfToTitle is the same as Tcl_UtfToUpper except it turns the first character in the string into its title-case equivalent, and all the following characters into their lower-case equivalents. main character gets the crown, everyone else dresses down 👑

---

⭐ KEYWORDS ⭐

utf, unicode, toupper, tolower, totitle, case

---

not me writing an entire manpage and then having the audacity to sign off cutely, but here we are 😭

okay that's the whole page bestie, you're officially fluent in Unicode case manipulation 💅✨ this was Tcl 8.1, and yeah, Tcl_UtfToUpper(3) — that's the one, that's the page 🎀🦋🌸

bye love u, go capitalize something 🫶