std::ios_base::xalloc(3)

✨ std::ios_base::xalloc ✨

okay so this is the std::ios_base::xalloc(3) page from the C++ Standard Libary manual — yes, that's the spelling, and no, we are not fixing it, it's iconic 💅. Buckle up bestie, we're doing private std::ios_base storage today 🎀.

---

🌸 NAME 🌸

std::ios_base::xalloc — std::ios_base::xalloc

---

✨ Synopsis ✨

static int xalloc();

So this one returns a unique (program-wide) index value that you can use to access one long and one void* elements in the private storage of std::ios_base by calling iword() and pword(). The call to xalloc does not allocate memory — nope, none, zero, zilch, no cap 💖.

This function is thread-safe: concurrent access by multiple threads (since C++11) does not result in a data race. Periodt 🫶.

Effectively increments the next available unique index. It's giving "handing out the next little ticket number" energy 🎟️.

---

💖 Return value 💖

A unique integer for use as a pword/iword index. That's it, that's the return value, slay 💅.

---

🎀 Example 🎀

This example uses base class pword storage for runtime type identification of derived stream objects. Obsessed with the little pointer lookup moment, honestly ✨.

// Run this code

#include <iostream>

template<class CharT, class Traits = std::char_traits<CharT>>
class mystream : public std::basic_ostream<CharT, Traits>
{
public:
    static const int xindex;

    mystream(std::basic_ostream<CharT, Traits>& ostr) :
        std::basic_ostream<CharT, Traits>(ostr.rdbuf())
    {
        this->pword(xindex) = this;
    }

    void myfn()
    {
        *this << "[special handling for mystream]";
    }
};

// Each specialization of mystream obtains a unique index from xalloc()
template<class CharT, class Traits>
const int mystream<CharT, Traits>::xindex = std::ios_base::xalloc();

// This I/O manipulator will be able to recognize ostreams that are mystreams
// by looking up the pointer stored in pword
template<class CharT, class Traits>
std::basic_ostream<CharT, Traits>& mymanip(std::basic_ostream<CharT, Traits>& os)
{
    if (os.pword(mystream<CharT, Traits>::xindex) == &os)
        static_cast<mystream<CharT, Traits>&>(os).myfn();
    return os;
}

int main()
{
    std::cout << "cout, narrow-character test " << mymanip << '\n';

    mystream<char> myout(std::cout);
    myout << "myout, narrow-character test " << mymanip << '\n';

    std::wcout << "wcout, wide-character test " << mymanip << '\n';

    mystream<wchar_t> mywout(std::wcout);
    mywout << "mywout, wide-character test " << mymanip << '\n';
}

---

🌈 Output 🌈

cout, narrow-character test
myout, narrow-character test [special handling for mystream]
wcout, wide-character test
mywout, wide-character test [special handling for mystream]

look at those lil' [special handling for mystream] moments showing up exactly where they should 😭💖

---

💅 Defect reports 💅

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. Retroactive glow-up, we love to see it ✨:

• LWG 2143 — applied to C++11; behavior as published: xalloc was not thread-safe; correct behavior: made thread-safe.

---

🦋 See also 🦋

• pword — public member function: resizes the private storage if necessary and access to the void* element at the given index.
• iword — public member function: resizes the private storage if necessary and access to the long element at the given index.

---

mwah 💋 — this came from http://cppreference.com, version/date 2024.06.10, and it's the std::ios_base::xalloc(3) page. Byeeee 🫶