std::ios_base::iword(3)

💖 NAME 💖

Manual: C++ Standard Libary (their spelling, not mine 😭). Page: std::ios_base::iword — literally std::ios_base::iword - std::ios_base::iword, bestie. We’re doing this.

---

🦋 Synopsis 🦋

long& iword( int index );

Okay so first, it allocates or resizes the private storage (dynamic array of long or another indexable data structure) sufficiently to make index a valid index, then returns a reference to the long element of the private storage with the index index.

The reference may be invalidated by any operation on this ios_base object, including another call to iword(), but the stored values are retained, so that reading from iword(index) with the same index later will produce the same value until the next call to std::basic_ios::copyfmt(). The value can be used for any purpose. The index of the element must be obtained by a previous call to xalloc(), otherwise the behavior is undefined. New elements are initialized to 0.

If the function fails (possibly caused by an allocation failure) and *this is a base class subobject of a basic_ios<> object or subobject, calls std::basic_ios<>::setstate(badbit) which may throw std::ios_base::failure.

undefined behavior warning, bestie: if you didn’t get that index from a previous xalloc() call, the behavior is literally undefined. No cap. 💀

---

✨ Notes ✨

Typical use of iword storage is to pass information (e.g. custom formatting flags) from user-defined I/O manipulators to user-defined operator<< and operator>> or to user-defined formatting facets imbued into standard streams.

---

🎀 Parameters 🎀

• index — index value of the element.

---

⭐ Return value ⭐

A reference to the element.

---

💅 Exceptions 💅

May throw std::ios_base::failure when setting the badbit.

---

🌈 Example 🌈

       // Run this code

        #include <iostream>
        #include <string>

        struct Foo
        {
            static int foo_xalloc;
            std::string data;

            Foo(const std::string& s) : data(s) {}
        };

        // Allocates the iword storage for use with Foo objects
        int Foo::foo_xalloc = std::ios_base::xalloc();

        // This user-defined operator<< prints the string in reverse if the
       iword holds 1
        std::ostream& operator<<(std::ostream& os, Foo& f)
        {
            if (os.iword(Foo::foo_xalloc) == 1)
                return os << std::string(f.data.rbegin(), f.data.rend());
            else
                return os << f.data;
        }

        // This I/O manipulator flips the number stored in iword between 0 and
       1
        std::ios_base& rev(std::ios_base& os)
        {
            os.iword(Foo::foo_xalloc) = !os.iword(Foo::foo_xalloc);
            return os;
        }

        int main()
        {
            Foo f("example");
            std::cout << f << '\n' << rev << f << '\n' << rev << f << '\n';
        }

🌸 Output 🌸

        example
        elpmaxe
        example

---

💀 Defect reports 💀

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

• DR LWG 36, applied to C++98 — behavior as published: “the stored value might not be retained if the reference is invalidated”; correct behavior: “the stored value is retained until the next call of copyfmt()”.
• DR LWG 41, applied to C++98 — behavior as published: “the function set badbit by itself on failure, but ios_base does not provide such interface”; correct behavior: “badbit is set by basic_ios (if *this is its base class subobject)”.

---

🫶 See also 🫶

• pword — resizes the private storage if necessary and access to the void* element at the given index (public member function).
• xalloc [static] — returns a program-wide unique integer that is safe to use as index to pword() and iword() (public static member function).

---

okay that’s the whole vibe, bestie 💅 source/version: http://cppreference.com; date: 2024.06.10 — and the footer’s manual tag is std::ios_base::iword(3), periodt 🫶