std::strstr...uf::overflow(3)

💖 NAME 💖

std::strstreambuf::overflow — std::strstreambuf::overflow (yes bestie, it's listed twice, and that's the whole NAME vibe 💅). This page is titled std::strstr...uf::overflow(3) and lives under the C++ Standard Libary manual — spelling stays exactly as the header gave it, no cap ✨.

✨ Synopsis ✨

protected:                                      (deprecated in C++98)
virtual int_type overflow( int_type c = EOF );  (removed in C++26)

Okay so this one appends the character c to the put area of the buffer, reallocating if possible 🫶. The way it goes down is:

1. If c == EOF, does nothing.
2. Otherwise, if the put area has a write position available (pptr() < epptr()), stores the character as if by *pptr()++ = c.
3. Otherwise, if the stream buffer mode is not dynamic or the stream buffer is currently frozen, the function fails and returns EOF.
4. Otherwise, the function reallocates (or initially allocates) a dynamic array large enough to hold the contents of the current dynamic array (if any) plus at least one additional write position. If a pointer to the allocating function palloc was used in the constructor, that function is called with (*palloc)(n) where n is the number of bytes to allocate, otherwise new char[n] is used. If a pointer to the deallocating function pfree was used in the constructor, that function is called with (*pfree)(p) to deallocate the previous array, if needed, otherwise delete[] p is used. If allocation fails, the function fails and returns EOF.

Heads up bestie: the synopsis literally tags this as deprecated in C++98 and removed in C++26. The timeline is timelining 😭⏳

🌸 Parameters 🌸

• c — the character to store in the put area.

🎀 Return value 🎀

If c == EOF, returns some value other than EOF. Otherwise, returns (unsigned char)(c) on success, EOF on failure 💖.

🦋 Example 🦋

// Run this code

#include <iostream>
#include <strstream>

struct mybuf : std::strstreambuf
{
    int_type overflow(int_type c)
    {
        std::cout << "Before overflow(): size of the put area is " << epptr()-pbase()
                  << " with " << epptr()-pptr() << " write positions available\n";
        int_type rc = std::strstreambuf::overflow(c);
        std::cout << "After overflow(): size of the put area is " << epptr()-pbase()
                  << " with " << epptr()-pptr() << " write positions available\n";
        return rc;
    }
};

int main()
{
    mybuf sbuf; // read-write dynamic strstreambuf
    std::iostream stream(&sbuf);

    stream << "Sufficiently long string to overflow the initial allocation, at least "
           << " on some systems.";
}

🍓 Possible output: 🍓

Before overflow(): size of the put area is 16 with 0 write positions available
After overflow(): size of the put area is 32 with 15 write positions available
Before overflow(): size of the put area is 32 with 0 write positions available
After overflow(): size of the put area is 64 with 31 write positions available
Before overflow(): size of the put area is 64 with 0 write positions available
After overflow(): size of the put area is 128 with 63 write positions available

👑 See also 👑

• overflow — writes characters to the associated output sequence from the put area [virtual] (virtual protected member function of std::basic_streambuf<CharT,Traits>)
• overflow — appends a character to the output sequence [virtual] (virtual protected member function of std::basic_stringbuf<CharT,Traits,Allocator>)
• overflow — writes characters to the associated file from the put area [virtual] (virtual protected member function of std::basic_filebuf<CharT,Traits>)
• sputc — writes one character to the put area and advances the next pointer (public member function of std::basic_streambuf<CharT,Traits>)
• put — inserts a character (public member function of std::basic_ostream<CharT,Traits>)

Source/version/date shoutout, because the footer said so: http://cppreference.com · 2024.06.10 · page std::strstr...uf::overflow(3) 🫶💖✨