std::basic_streambuf<CharT,Traits>::overflow

The intent of this function is to transmit characters from the put area of the stream buffer to the associated character sequence.

Formally, this function ensures that there is space at the put area for at least one character. The base class version always fails, and a possibly-succeeding implementation can only be provided in derived classes (see implementation requirements). The standard library provides std::strstreambuf::overflow(), (until C++26)std::basic_stringbuf::overflow() and std::basic_filebuf::overflow().

[edit] Parameters

[edit] Return value

Traits::eof()

[edit] Implementation requirements

Every overriding definition of this virtual function must obey the following constraints, otherwise the behavior is undefined:

• The effect of the function is to consume some initial subsequence of the characters of the pending sequence . The pending sequence is defined as the concatenation of the following sequences:
  • The put area (formally, empty sequence if pbase() is null, otherwise pptr() - pbase() characters beginning at pbase()).
  • The character ch or nothing if ch is EOF (formally, if Traits::eq_int_type(ch, Traits::eof()) returns true).
• After consumption, the put area pointers are updated to hold the remaining characters, if any. Formally, let r be the number of characters in the pending sequence not consumed:
  • If r is non-zero, then pbase() and pptr() are set so that all following conditions are satisfied:
    • pptr() - pbase() is r.
    • The r characters starting at pbase() are the associated output stream.
  • If r is zero (all characters of the pending sequence have been consumed), then either pbase() is set to a null value, or pbase() and pptr() are both set to the same non-null value.
• The function may fail if either appending some character to the associated output stream fails or if it is unable to establish pbase() and pptr() according to the above rules.
• If the function succeeds, returns some value other than Traits::eof(). Typically, ch is returned to indicate success, except when Traits::eq_int_type(ch, Traits::eof()) returns true, in which case Traits::not_eof(ch) is returned.
• If the function fails, returns Traits::eof() or throws an exception.

[edit] Note

The sputc() and sputn() call this function in case of an overflow (pptr() == nullptr or pptr() >= epptr()).

[edit] Example

#include <array>
#include <cstddef>
#include <iostream>
 
// Buffer for std::ostream implemented by std::array
template<std::size_t size, class CharT = char>
struct ArrayedStreamBuffer : std::basic_streambuf<CharT>
{
    using Base = std::basic_streambuf<CharT>;
    using char_type = typename Base::char_type;
    using int_type = typename Base::int_type;
 
    ArrayedStreamBuffer()
    {
        // put area pointers to work with 'buffer'
        Base::setp(buffer.data(), buffer.data() + size);
    }
 
    int_type overflow(int_type ch) 
    {
        std::cout << "overflow\n";
        return Base::overflow(ch);
    }
 
    void print_buffer()
    {
        for (char_type i : buffer)
        {
            if (i == 0)
                std::cout << "\\0";
            else
                std::cout << i;
            std::cout << ' ';
        }
        std::cout << '\n';
    }
 
private:
    std::array<char_type, size> buffer{}; // value-initialize buffer
};
 
int main()
{
    ArrayedStreamBuffer<10> streambuf;
    std::ostream stream(&streambuf);
 
    stream << "hello";
    streambuf.print_buffer();
    if (stream.good())
        std::cout << "stream is good\n";
 
    stream << "world";
    streambuf.print_buffer();
    if (stream.good())
        std::cout << "stream is good\n";
 
    stream << "!";
    streambuf.print_buffer();
    if (!stream.good())
        std::cout << "stream is not good\n";
}

h e l l o \0 \0 \0 \0 \0
stream is good
h e l l o w o r l d 
stream is good
overflow
h e l l o w o r l d 
stream is not good

[edit] See also