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

La intención de esta función es transmitir caracteres desde el área de puesta del búfer de flujo hacia la secuencia de caracteres asociada .

Formalmente, esta función garantiza que haya espacio en el área de escritura para al menos un carácter. La versión de la clase base siempre falla, y una implementación que pueda tener éxito solo puede proporcionarse en clases derivadas (ver requisitos de implementación ). La biblioteca estándar proporciona std::strstreambuf::overflow() , (until C++26) std::basic_stringbuf::overflow() y std::basic_filebuf::overflow() .

Parámetros

Valor de retorno

Traits :: eof ( )

Requisitos de implementación

Toda definición que sobrescriba esta función virtual debe cumplir con las siguientes restricciones, de lo contrario el comportamiento es indefinido:

• El efecto de la función es consumir alguna subsecuencia inicial de los caracteres de la secuencia pendiente  . La secuencia pendiente se define como la concatenación de las siguientes secuencias:
  • El área de escritura (formalmente, secuencia vacía si pbase() es nulo, de lo contrario pptr ( ) - pbase ( ) caracteres comenzando en pbase() ).
  • El carácter ch o nada si ch es EOF (formalmente, si Traits :: eq_int_type ( ch, Traits :: eof ( ) ) retorna true ).
• Después del consumo, los punteros del área de escritura se actualizan para contener los caracteres restantes, si los hay. Formalmente, sea r el número de caracteres en la secuencia pendiente no consumidos:
  • Si r es distinto de cero, entonces pbase() y pptr() se configuran para que se cumplan todas las siguientes condiciones:
    • pptr ( ) - pbase ( ) es r .
    • Los r caracteres comenzando en pbase() son el flujo de salida asociado.
  • Si r es cero (todos los caracteres de la secuencia pendiente han sido consumidos), entonces o bien pbase() se establece a un valor nulo, o pbase() y pptr() se establecen ambos al mismo valor no nulo.
• La función puede fallar si falla la adición de algún carácter al flujo de salida asociado o si no puede establecer pbase() y pptr() de acuerdo con las reglas anteriores.
• Si la función tiene éxito, retorna algún valor distinto de Traits :: eof ( ) . Típicamente, ch se retorna para indicar éxito, excepto cuando Traits :: eq_int_type ( ch, Traits :: eof ( ) ) retorna true , en cuyo caso se retorna Traits :: not_eof ( ch ) .
• Si la función falla, retorna Traits :: eof ( ) o lanza una excepción.

Nota

Las funciones sputc() y sputn() llaman a esta función en caso de un desbordamiento ( pptr ( ) == nullptr o pptr ( ) >= epptr ( ) ).

Ejemplo

#include <array>
#include <cstddef>
#include <iostream>
// Buffer para std::ostream implementado por 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()
    {
        // punteros del área de escritura para trabajar con '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{}; // inicializar buffer por valor
};
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

Véase también