std::basic_stringbuf<CharT,Traits,Allocator>::overflow

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

Добавляет символ c в выходную последовательность символов.

Если c является индикатором конца файла (traits::eq_int_type(c, traits::eof()) == true), добавлять нечего. Функция ничего не делает и возвращает неопределённое значение, отличное от traits::eof().

В противном случае, если в выходной последовательности доступна позиция записи или эта функция может успешно её освободить, функция вызывает sputc(c) и возвращает c.

Эта функция может освободить позицию записи, если std::stringbuf открыт для вывода ((mode & ios_base::out) != 0): в этом случае она перераспределяет (или изначально выделяет) буфер достаточного размера, чтобы вместить весь текущий буфер и как минимум ещё один символ. Если std::stringbuf также открыт для ввода ((mode & ios_base::in) != 0), то overflow также увеличивает размер области чтения, перемещая egptr() так, чтобы он указывал на позицию сразу после новой позиции записи.

Параметры

символ, который нужно сохранить в области записи

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

Traits::eof() для обозначения ошибки, c, если символ c был успешно добавлен, или любое значение, отличное от Traits::eof(), если функция вызвана с аргументом Traits::eof().

Примечания

Эта функция отличается от типичной overflow(), которая перемещает содержимое буфера в связанную последовательность символов, поскольку для std::basic_stringbuf буфер и связанная последовательность — одно и то же.

Пример

В реализации, использованной для выполнения этого примера (например, GCC-4.9), overflow() выделяет для области записи буфер большего размера — 512 байт: вызов str() вернул бы только четыре инициализированных байта, однако следующие 508 вызовов sputc() не потребовали бы новых вызовов overflow().

#include <sstream>
#include <iostream>

struct mybuf : std::stringbuf
{
    mybuf(const std::string& new_str,
          std::ios_base::openmode which = std::ios_base::in | std::ios_base::out)
        : std::stringbuf(new_str, which) {}
    
    int_type overflow(int_type c = EOF) override
    {
        std::cout << "stringbuf::overflow('" << char(c) << "') called\n"
                  << "Before: size of get area: " << egptr() - eback() << '\n'
                  << "        size of put area: " << epptr() - pbase() << '\n';
        
        int_type ret = std::stringbuf::overflow(c);
        
        std::cout << "After : size of get area: " << egptr() - eback() << '\n'
                  << "        size of put area: " << epptr() - pbase() << '\n';
        
        return ret;
    }
};

int main()
{
    std::cout << "read-write stream:\n";
    mybuf sbuf("   "); // read-write stream
    std::iostream stream(&sbuf);
    stream << 1234;
    std::cout << sbuf.str() << '\n';
    
    std::cout << "\nread-only stream:\n";
    mybuf ro_buf("   ", std::ios_base::in); // read-only stream
    std::iostream ro_stream(&ro_buf);
    ro_stream << 1234;
    
    std::cout << "\nwrite-only stream:\n";
    mybuf wr_buf("   ", std::ios_base::out); // write-only stream
    std::iostream wr_stream(&wr_buf);
    wr_stream << 1234;
}

Возможный вывод:

read-write stream:
stringbuf::overflow('4') called
Before: size of get area: 3
        size of put area: 3
After : size of get area: 4
        size of put area: 512
1234

read-only stream:
stringbuf::overflow('1') called
Before: size of get area: 3
        size of put area: 0
After : size of get area: 3
        size of put area: 0

write-only stream:
stringbuf::overflow('4') called
Before: size of get area: 0
        size of put area: 3
After : size of get area: 0
        size of put area: 512

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были ретроспективно применены к ранее опубликованным стандартам C++.

DR	Применён к	Опубликованное поведение	Исправленное поведение
LWG 169	C++98	перераспределённый (или выделенный заново) буфер мог вместить только один дополнительный символ	допускает больше дополнительных символов
LWG 432	C++98	`overflow` перемещал `epptr()` так, чтобы он указывал на позицию сразу после новой позиции записи, если `std::stringbuf` открыт для ввода	он не перемещается

См. также

overflow [виртуальная]	записывает символы из области записи в связанную выходную последовательность (виртуальная защищённая функция-член `std::basic_streambuf<CharT,Traits>`)
underflow [виртуальная]	возвращает следующий символ, доступный во входной последовательности (виртуальная защищённая функция-член)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/io/basic_stringbuf/overflow