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

protected:
virtual int_type overflow( int_type ch = Traits::eof() );

Назначение этой функции — передавать символы из области записи буфера потока в связанную последовательность символов.

Формально эта функция гарантирует, что в области записи есть место как минимум для одного символа. Версия базового класса всегда завершается неудачей, а реализация, которая может завершиться успешно, может быть предоставлена только в производных классах (см. требования к реализации). Стандартная библиотека предоставляет std::strstreambuf::overflow(), (до C++26)std::basic_stringbuf::overflow() и std::basic_filebuf::overflow().

Параметры

Возвращаемое значение

Traits::eof()

Требования к реализации

Каждое переопределение этой виртуальной функции должно удовлетворять следующим ограничениям; в противном случае поведение не определено:

• Функция потребляет некоторую начальную подпоследовательность символов ожидающей последовательности . Ожидающая последовательность определяется как конкатенация следующих последовательностей:
  • Область записи (формально — пустая последовательность, если pbase() равен null, в противном случае — pptr() - pbase() символов, начиная с pbase()).
  • Символ ch либо ничего, если ch равен EOF (формально, если Traits::eq_int_type(ch, Traits::eof()) возвращает true).
• После потребления указатели области записи обновляются так, чтобы указывать на оставшиеся символы, если таковые имеются. Формально, пусть r — количество непотреблённых символов ожидающей последовательности:
  • Если r не равен нулю, то pbase() и pptr() устанавливаются так, чтобы выполнялись все следующие условия:
    • pptr() - pbase() равен r.
    • r символов, начиная с pbase(), составляют связанный выходной поток.
  • Если r равен нулю (все символы ожидающей последовательности потреблены), то либо pbase() устанавливается в нулевое значение, либо pbase() и pptr() устанавливаются в одно и то же ненулевое значение.
• Функция может завершиться неудачей, если добавление какого-либо символа в связанный выходной поток завершается неудачей или если она не может установить pbase() и pptr() в соответствии с приведёнными выше правилами.
• Если функция завершается успешно, она возвращает значение, отличное от Traits::eof(). Обычно для обозначения успеха возвращается ch, за исключением случая, когда Traits::eq_int_type(ch, Traits::eof()) возвращает true; в этом случае возвращается Traits::not_eof(ch).
• Если функция завершается неудачей, она возвращает Traits::eof() или выбрасывает исключение.

Примечание

sputc() и sputn() вызывают эту функцию при переполнении (pptr() == nullptr или pptr() >= epptr()).

Пример

#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

См. также