Tcl_UtfToUpper(3tcl)

✨ NAME ✨

okay bestie so this is Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_UtfToLower, and Tcl_UtfToTitle — literally the whole girl gang of routines for manipulating the case of Unicode characters and UTF-8 strings 💅 (it's 3tcl, the Tcl Library Procedures chapter, iykyk)

---

🌸 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 that's getting its case done 💖
• char *str (in/out) — pointer to the TUTF-8 byte sequence that gets converted in place, no copy, no extra drama

---

👑 DESCRIPTION 👑

N.B. go read the Tcl_UniChar documentation page first, bestie — that's where the TUTF-8 encoding and all the related terms referenced here get explained. It's giving prerequisite reading, fr fr.

---

💜 the first three — one character at a time

The first three routines convert the case of individual Unicode characters:

• If ch represents a lower-case character, Tcl_UniCharToUpper returns the corresponding upper-case character. If no upper-case character is defined, it returns the character unchanged — no cap, it just hands it back.
• If ch represents an upper-case character, Tcl_UniCharToLower returns the corresponding lower-case character. If no lower-case character is defined, it returns the character unchanged.
• If ch represents a lower-case character, Tcl_UniCharToTitle returns the corresponding title-case character. If no title-case character is defined, it returns the corresponding upper-case character. And if no upper-case character is defined, it returns the character unchanged.

Title-case is only defined for a small number of characters — the ones that literally look different when they're sitting at the beginning of a capitalized word. Rare queen behavior, honestly. 💅

---

🦋 the next three — whole strings, in place

The next three routines convert the case of null-terminated TUTF-8 byte sequences in place in memory:

• Tcl_UtfToUpper changes every TUTF-8 encoded character in str to upper-case. Because changing the case of a character may change its size, the byte offset of each character in the resulting string may differ from its original location — so don't come for the old byte offsets, they're not invited anymore 😭. Tcl_UtfToUpper writes a null byte at the end of the converted string. It returns the new length of the string in bytes, and this new length is guaranteed to be no longer than the original string length. Slay.
• Tcl_UtfToLower is the same as Tcl_UtfToUpper except it turns each character in the string into its lower-case equivalent. Same energy, lowercase fit. 🌈
• Tcl_UtfToTitle is the same as Tcl_UtfToUpper except it turns the first character in the string into its title-case equivalent and all following characters into their lower-case equivalents. Main character energy for exactly one character, everyone else falls in line. 👑

---

🔥 KEYWORDS 🔥

utf, unicode, toupper, tolower, totitle, case

---

✿ this has been Tcl library procedures realness, straight out of Tcl 8.1 ✿

kisses, take care of ur strings, and remember: in-place conversion means no takebacks 🫶💖