std::ostrea...buf_iterator(3)

💅 std::ostreambuf_iterator::ostreambuf_iterator ✨

okay so bestie, we're in the C++ Standard Library today — this is the constructor page for std::ostreambuf_iterator::ostreambuf_iterator, and honestly it's giving "short and iconic." 🎀 Building one of these iterators is literally how you get your write-on-sight iterator vibe going. Let's go. 🦋

🌸 Synopsis 🌸

ostreambuf_iterator( streambuf_type* buffer )            (until C++11)
  throw();
ostreambuf_iterator( streambuf_type* buffer )            (since C++11)
  noexcept;                                        (1)
ostreambuf_iterator( ostream_type& stream )       (until C++11)
  throw();                                             (2)
ostreambuf_iterator( ostream_type& stream )       (since C++11)
  noexcept;

So there's two flavors, no cap:

1. Constructs the iterator with the private streambuf_type* member set to buffer and the failed() flag set to false. Heads up though — the behavior is undefined if buffer is a null pointer. 😭 Like fr fr, don't do that.
2. Same as ostreambuf_iterator(stream.rdbuf()). That's it, that's the whole thing. 💅

🫶 Parameters 🫶

• stream — the output stream whose rdbuf() will be accessed by this iterator.
• buffer — the output stream buffer to be accessed by this iterator.

🎀 Example 🎀

The page says // Run this code, so go off, queen 👑

#include <fstream>
#include <iostream>
#include <iterator>

int main()
{
    const char* file = "test.txt";
    {
        std::basic_filebuf<char> f;
        f.open(file, std::ios::out);
        std::ostreambuf_iterator<char> out1(&f);
        *out1 = 'a'; // writes to file via iterator
    }

    // read back from the file
    char a;
    std::cout << ((std::ifstream{file} >> a), a) << std::endl;

    std::ostreambuf_iterator<wchar_t> out2{std::wcout};
    *out2 = L'b';
}

⭐ Output ⭐

a
b

look at that, a then b, the assignment through the iterator literally just worked. observed. 👑

💀 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 112 — applied to C++98. As published: the requirement "the argument cannot be null" was applied to overload (2). Correct behavior: applies to overload (1) instead. 🙈 (classic mix-up, lowkey embarrassing but they fixed it)
• P2325R3 — applied to C++20. As published: default constructor was provided as iterators must be default_initializable. Correct behavior: C++20 removed the requirement. 🫠

ok that's the whole page!! every flag, every overload, every DR, all accounted for. no notes. 💖

✨ that's a wrap, bestie ✨ — this little gem comes from http://cppreference.com, dated 2024.06.10, filed under the manual page std::ostrea...buf_iterator(3). go forth and construct your iterators responsibly (and never with a null pointer, i'm begging 🫶💜).