std::towlower(3)

💅 std::towlower — yes bestie, it's giving lowercase

okay so real quick, this whole page lives in the C++ Standard Libary manual (that's literally how it's spelled up top, i'm not fixing it, it's iconic 💀). the function we're stanning today is std::towlower, and it's exactly what it sounds like: wide char goes in, lowercase wide char comes out. slay.

---

✨ NAME ✨

std::towlower — literally std::towlower. that's the name. that's the whole name. short and sweet, main character energy 👑

---

🌸 Synopsis 🌸

so first things first, where does she live? she's defined in the header <cwctype>. periodt.

std::wint_t towlower( std::wint_t ch );

what she does: converts the given wide character to lowercase, if possible. (that "if possible" is doing a lot of work, keep reading 👀)

⚠️ okay so this is the important scary part, no cap: if the value of ch is neither representable as a wchar_t nor equal to the value of the macro WEOF, the behavior is undefined. like, undefined undefined. don't do it. 🚩

---

🎀 Parameters 🎀

• ch — the wide character to be converted. that's it, that's the whole list bestie, she's low maintenance 🫶

---

🦋 Return value 🦋

you get back the lowercase version of ch — or, if no lowercase version is listed in the current C locale, you just get ch back unmodified. no lowercase fit found? she returns home unchanged, we respect that 💜

---

💅 Notes 💅

okay so this is the tea: this function can only do 1:1 character mapping. only one-to-one. nothing fancy.

the example they give (and it's such a good example, obsessed): the Greek uppercase letter 'Σ' has two lowercase forms depending on where it sits in a word — 'σ' and 'ς'. so a call to std::towlower cannot be used to get the correct lowercase form in that case. it just can't. it's not built for that, don't come for her 😭

also, ISO 30112 specifies which pairs of Unicode characters are included in this mapping. iykyk ⭐

---

🌈 Example 🌈

// Run this code — go off, run it:

#include <clocale>
#include <cwctype>
#include <iostream>

int main()
{
    wchar_t c = L'\u0190'; // Latin capital open E ('Ɛ')

    std::cout << std::hex << std::showbase;
    std::cout << "in the default locale, towlower("
              << static_cast<std::wint_t>(c) << ") = "
              << std::towlower(c) << '\n';
    std::setlocale(LC_ALL, "en_US.utf8");
    std::cout << "in Unicode locale, towlower("
              << static_cast<std::wint_t>(c) << ") = "
              << std::towlower(c) << '\n';
}

note the cute little L'\u0190' — that's the Latin capital open E ('Ɛ') in case you were wondering 🍓

🧚 Output:

in the default locale, towlower(0x190) = 0x190
in Unicode locale, towlower(0x190) = 0x25b

see how in the default locale she just hands it right back? 0x190 → 0x190, no change, nothing to map to. but once you std::setlocale(LC_ALL, "en_US.utf8")? boom, 0x190 → 0x25b. the glow-up is real 🔥

---

👑 See also 👑

• towupper — converts a wide character to uppercase (function). the sister function, equally iconic.
• tolower(std::locale) — converts a character to lowercase using the ctype facet of a locale (function template). fancy locale-aware version, she's got range.
• tolower — converts a character to lowercase (function). the narrow-char cousin.
• C documentation for towlower — yes, C has one too, the family reunion is complete 🌸

---

okay that's the whole page, you're officially educated, go forth and lowercase responsibly 💖

signed off with love from http://cppreference.com, dated 2024.06.10, page std::towlower(3) — mwah, catch you in the next manpage bestie 🫶✨