std::ctype:...w,do_narrow(3)

🎀 NAME 🎀

std::ctype::narrow,do_narrow — std::ctype::narrow,do_narrow. yes bestie, the original NAME line said it twice, so we're saying it twice 💅 this is the std::ctype:...w,do_narrow(3) page from the C++ Standard Libary manual, and it's all about narrowing characters and the protected virtual functions that make it happen.

---

✨ Synopsis ✨

okay so here's the synopsis, and the formatting is exactly as chaotic as the original — we do not edit the sacred code block 💖

Defined in header <locale>
public:
(1)
char narrow( CharT c, char dflt ) const;
public:

const CharT* narrow( const CharT* beg, const CharT* end,
(2)

                     char dflt, char* dst ) const;
protected:
(3)
virtual char do_narrow( CharT c, char dflt ) const;
protected:

virtual const CharT* do_narrow( const CharT* beg, const CharT* end,
(4)

                                    char dflt, char* dst ) const;

now the overload lore 👑

• (1), (2) — Public member functions. They call the corresponding protected virtual member function do_narrow overload of the most derived class. Overload (1) calls do_narrow(c, dflt), overload (2) calls do_narrow(beg, end, dflt, dst).
• (3) — Converts the (possibly wide) character c to multibyte representation if the character can be represented with a single byte (for example, ASCII characters in UTF-8 encoding are single bytes). Returns dflt if such conversion does not exist.
• (4) — For every character in the character array [beg, end), writes narrowed characters (or dflt whenever narrowing fails) to the successive locations in the character array pointed to by dst.

Narrowing is always successful and always reversible (by calling widen()) for all characters from the basic source character set (until C++23) / basic character set (since C++23).

• i.e. do_widen(do_narrow(c, 0)) == c always holds for any character c in the basic source character set (until C++23) / basic character set (since C++23).

Narrowing, if successful, preserves all character classification categories known to is().

• i.e. is(m, c) || !ctc.is(m, do_narrow(c, dflt)) is always true for any named ctype category with a ctype<char> facet ctc and ctype_base::mask value m (unless do_narrow returns dflt).

Narrowing of any digit character guarantees that if the result is subtracted from the character literal '0', the difference equals the digit value of the original character.

• i.e. for any digit character c, the expression (do_narrow(c, dflt) - '0') evaluates to the digit value of the character.

bestie, the until C++23 / since C++23 split is doing the most, but it's real and it's here 🫶

---

🌸 Parameters 🌸

• c — character to convert.
• dflt — default value to produce if the conversion fails.
• 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.
• dst — pointer to the first element of the array of characters to fill.

---

💖 Return value 💖

• (1), (3) — Narrowed character or dflt if narrowing fails.
• (2), (4) — end.

---

🧚 Example 🧚

// Run this code

#include <iostream>
#include <locale>

void try_narrow(const std::ctype<wchar_t>& f, wchar_t c)
{
    char n = f.narrow(c, 0);
    if (n)
        std::wcout << '\'' << c << "' narrowed to " << +(unsigned char)n << '\n';
    else
        std::wcout << '\'' << c << "' could not be narrowed\n";
}

int main()
{
    std::locale::global(std::locale("en_US.utf8"));
    std::wcout.imbue(std::locale());
    std::wcout << std::hex << std::showbase << "In US English UTF-8 locale:\n";
    auto& f = std::use_facet<std::ctype<wchar_t>>(std::locale());
    try_narrow(f, L'A');
    try_narrow(f, L'Ａ');
    try_narrow(f, L'ě');

    std::locale::global(std::locale("cs_CZ.iso88592"));
    auto& f2 = std::use_facet<std::ctype<wchar_t>>(std::locale());
    std::wcout << "In Czech ISO-8859-2 locale:\n";
    try_narrow(f2, L'A');
    try_narrow(f2, L'Ａ');
    try_narrow(f2, L'ě');
}

💫 Possible output 💫

In US English UTF-8 locale:
'A' narrowed to 0x41
'Ａ' could not be narrowed
'ě' could not be narrowed
In Czech ISO-8859-2 locale:
'A' narrowed to 0x41
'Ａ' could not be narrowed
'ě' narrowed to 0xec

---

🔥 Defect reports 🔥

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 126 — applied to C++98. Behavior as published: 1. the code representing reversibility was do_widen(do_narrow(c), 0) == c; 2. the code representing category preservation was is(m, c) || !ctc.is(m, do_narrow(c), dflt). Correct behavior: corrected both.
• LWG 153 — applied to C++98. Behavior as published: narrow always called overload (4). Correct behavior: calls the corresponding overload.

---

🌈 See also 🌈

• widen — invokes do_widen (public member function).
• narrow — narrows characters (public member function of std::basic_ios<CharT,Traits>).
• wctob — narrows a wide character to a single-byte narrow character, if possible (function).

---

bestie, that's the whole page 💖 source/version: http://cppreference.com; date: 2024.06.10. now go out there and narrow something iconic, and if it fails, just return dflt and slay anyway 🫶✨