string-upcase(3scm)

💖 string-upcase(3scm) — string case conversion, bestie edition

okay so this is string-upcase(3scm) from the Scheme Programmer's Manual, and it's literally the glow-up page for your strings ✨ four whole procedures that change the case of your text and honestly they ate.

✨ NAME ✨

string-upcase, string-downcase, string-titlecase, string-foldcase — string case conversion 💅

📚 LIBRARY 📚

import these depending on which report you're living in, no cap:

(import (rnrs))                     ;R6RS
(import (rnrs unicode))             ;R6RS
(import (scheme char))              ;R7RS

🦋 SYNOPSIS 🦋

(string-upcase string)
(string-downcase string)
(string-titlecase string)           ;R6RS
(string-foldcase string)

🌸 DESCRIPTION 🌸

Every one of these hands you back a case-converted version of string. That's the whole vibe. But the way they each do it is different, so let's get into it:

• string-upcase — converts a string to upper case. LOUD MODE, all caps, main character energy 🔥
• string-downcase — converts a string to lower case. soft launch, lowercase era 🎀
• string-foldcase — converts the string to its case-folded counterpart, using the full case-folding mapping, but without the special mappings for Turkic languages. iykyk 😌
• string-titlecase — converts the first cased character of each word to title case, and downcases all other cased characters. every word gets its moment 👑

Heads up bestie: these procedures are defined in terms of Unicode's locale-independent case mappings from Unicode scalar-value sequences to scalar-value sequences. Which means — and this is the part that gets people — the length of the result string can be different from the length of the input string. not a typo, fr fr 😭

And since these procedures are locale-independent, they may not be appropriate for some locales. lowkey a limitation but that's the deal 🫶

R7RS 🧚

The Unicode Standard prescribes special treatment of the Greek letter Σ, whose normal lower-case form is σ but which becomes ς at the end of a word. See Unicode Standard Annex #44 for details.

However — and this is the important part — implementations of string-downcase are not required to provide this behavior, and may choose to change Σ to σ in all cases. so don't come for an implementation that doesn't do the fancy thing 💀

🛠️ IMPLEMENTATION NOTES 🛠️

The case mappings you need to actually implement these procedures can be extracted from UnicodeData.txt, SpecialCasing.txt, WordBreakProperty.txt, and CaseFolding.txt from the Unicode Consortium. in case you were wondering where the data lives ✨

Word breaking, as needed for the correct casing of Σ and for string-titlecase, is specified in Unicode Standard Annex #29.

💖 RETURN VALUES 💖

These procedures return a single value; a string. one value, one string, slay.

When the specified result is equal in the sense of string=?(3scm) to the argument, these procedures may return the argument instead of a newly allocated string. so don't go assuming it's a fresh object, okay? 🙈

⭐ EXAMPLES ⭐

the receipts 🧾

(string-upcase "Hi")               =>  "HI"
(string-downcase "Hi")             =>  "hi"
(string-foldcase "Hi")             =>  "hi"
(string-upcase "Straße")           =>  "STRASSE"
(string-downcase "Straße")         =>  "straße"
(string-foldcase "Straße")         =>  "strasse"
(string-downcase "STRASSE")        =>  "strasse"
(string-downcase "Σ")              =>  "σ"

watch the length change on Straße → STRASSE, iconic 🔥

;; Chi Alpha Omicron Sigma.
;; See the note on R7RS in the description.
(string-upcase "XAOΣ")             =>  "XAOΣ"
(string-downcase "XAOΣ")           =>  "χαoς"
(string-downcase "XAOΣΣ")          =>  "χαoσς"
(string-downcase "XAOΣ Σ")         =>  "χαoς σ"
(string-foldcase "XAOΣΣ")          =>  "χαoσσ"
(string-upcase "χαoς")             =>  "XAOΣ"
(string-upcase "χαoσ")             =>  "XAOΣ"

that's the whole Σ situation in action, see the R7RS note above 👀

(string-titlecase "kNock KNoCK")   =>  "Knock Knock"
(string-titlecase "who's there?")  =>  "Who's There?"
(string-titlecase "r6rs")          =>  "R6rs"
(string-titlecase "R6RS")          =>  "R6rs"

title case is unbothered by your SHOUTING, it's giving serene 🕊️

🌈 COMPATIBILITY 🌈

In R6RS implementations, case conversion differs according to which Unicode version is supported. and important: R7RS does not have string-titlecase. so if it's missing, that's why 🫠

💀 ERRORS 💀

This procedure can raise exceptions with the following condition types:

• &assertion (R6RS) — the wrong number of arguments was passed or an argument was outside its domain. classic.
• R7RS — the assertions described above are errors. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically. yes, catastrophically. no cap 😭

👀 SEE ALSO 👀

• char-upper-case?(3scm)
• Unicode Standard Annex #44: Unicode Character Database.
• Unicode Standard Annex #29: Unicode Text Segmentation.

👑 STANDARDS 👑

R6RS, R7RS

🎀 HISTORY 🎀

The first Scheme report with these procedures is R6RS. They were later also added in R7RS, except for string-titlecase. she got left out, tragic ✨

🫶 AUTHORS 🫶

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

---

that's the whole page bestie, go forth and case-convert responsibly 💅

scheme-manpages, dated 2022-05-13, filed under string-upcase(3scm) — mwah, take care 🦋