std::ctype:...:do_toupper(3)

🌸 NAME 🌸

okay so bestie, this is the page for std::ctype::toupper,std::ctype::do_toupper — the header up top says std::ctype:...:do_toupper(3), and it's from the C++ Standard Libary manual (yep, that's the spelling on the page, no cap 💅). The NAME line is std::ctype::toupper,std::ctype::do_toupper — dash — std::ctype::toupper,std::ctype::do_toupper again, because the page said it twice and we're not erasing that. It's giving "let's uppercase some characters, but make it locale-aware" energy, and we're keeping every single deet. periodt.

✨ Synopsis ✨

Defined in header <locale>
public:
(1)
CharT toupper( CharT c ) const;
public:
(2)
const CharT* toupper( CharT* beg, const CharT* end ) const;
protected:
(3)
virtual CharT do_toupper( CharT c ) const;
protected:
(4)
virtual const CharT* do_toupper( CharT* beg, const CharT* end )
const;

the vibe check on the numbered ones:

• 1,2) — Public member function, calls the protected virtual member function do_toupper of the most derived class.
• 3) — Converts the character c to upper case if an upper case form is defined by this locale.
• 4) — For every character in the character array [beg, end), for which an upper case form exists, replaces the character with that upper case form.

🎀 Parameters 🎀

• c — character to convert.
• beg — pointer to the first character in an array of characters to convert.
• end — one past the end pointer for the array of characters to convert.

🦋 Return value 🦋

• 1,3) — upper case character or c if no upper case form is listed by this locale.
• 2,4) — end.

💅 Notes 💅

Only 1:1 character mapping can be performed by this function, e.g. the uppercase form of 'ß' is the two-character string "SS" (with some exceptions - see «Capital ẞ»), which cannot be obtained by do_toupper. highkey important if you were expecting magic multi-character glow-ups 😭.

🌈 Example 🌈

obsessed with this little demo, fr fr:

// Run this code

#include <iostream>
#include <locale>

void try_upper(const std::ctype<wchar_t>& f, wchar_t c)
{
    wchar_t up = f.toupper(c);
    if (up != c)
        std::wcout << "Upper case form of \'" << c << "' is " << up << '\n';
    else
        std::wcout << '\'' << c << "' has no upper case form\n";
}

int main()
{
    std::locale::global(std::locale("en_US.utf8"));
    std::wcout.imbue(std::locale());
    std::wcout << "In US English UTF-8 locale:\n";
    auto& f = std::use_facet<std::ctype<wchar_t>>(std::locale());
    try_upper(f, L's');
    try_upper(f, L'ſ');
    try_upper(f, L'δ');
    try_upper(f, L'ö');
    try_upper(f, L'ß');

    std::wstring str = L"Hello, World!";
    std::wcout << "Uppercase form of the string '" << str << "' is ";
    f.toupper(&str[0], &str[0] + str.size());
    std::wcout << '\'' << str << "'\n";
}

and the output is literally:

In US English UTF-8 locale:
Upper case form of 's' is S
Upper case form of 'ſ' is S
Upper case form of 'δ' is Δ
Upper case form of 'ö' is Ö
'ß' has no upper case form
Uppercase form of the string 'Hello, World!' is 'HELLO, WORLD!'

🔥 See also 🔥

• tolower — invokes do_tolower (public member function)
• toupper — converts a character to uppercase (function)
• towupper — converts a wide character to uppercase (function)

that's the whole page, bestie 🫶 — signing off from http://cppreference.com, date/version 2024.06.10, page std::ctype:...:do_toupper(3). mwah 💋