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

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

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

Параметры

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

Traits :: eof ( )

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

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

• Эффект функции заключается в потреблении некоторой начальной подпоследовательности символов ожидающей последовательности  . Ожидающая последовательность определяется как конкатенация следующих последовательностей:
  • Область вывода (формально, пустая последовательность, если pbase() является нулевым указателем, иначе 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>
// Буфер для std::ostream, реализованный с помощью 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()
    {
        // указатели области вывода для работы с '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{}; // инициализация буфера значениями
};
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

Смотрите также