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

此函数的目的是将字符从流缓冲区的 放置区 传输到 关联字符序列 。

正式而言，此函数确保放置区域至少有一个字符的空间。基类版本始终失败，可能成功的实现仅能在派生类中提供（参见 实现要求 ）。标准库提供了 std::strstreambuf::overflow() , (until C++26) std::basic_stringbuf::overflow() 和 std::basic_filebuf::overflow() 。

参数

返回值

Traits :: eof ( )

实现要求

此虚函数的每个重写定义都必须遵循以下约束，否则行为未定义：

• 该函数的作用是消耗 待处理序列  字符的某个初始子序列。待处理序列定义为以下序列的串联：
  • 放置区（形式化定义：若 pbase() 为空则为空序列，否则为从 pbase() 开始的 pptr ( ) - pbase ( ) 个字符）。
  • 字符 ch 或空（形式化定义：若 Traits :: eq_int_type ( ch, Traits :: eof ( ) ) 返回 true ）。
• 消耗后，放置区指针将被更新以保存剩余字符（若有）。形式化定义：令 r 表示待处理序列中未被消耗的字符数：
  • 若 r 非零，则设置 pbase() 和 pptr() 以满足以下所有条件：
    • pptr ( ) - pbase ( ) 等于 r 。
    • 从 pbase() 开始的 r 个字符属于关联输出流。
  • 若 r 为零（待处理序列的所有字符已被消耗），则要么将 pbase() 设为空值，要么将 pbase() 和 pptr() 设为相同的非空值。
• 若向关联输出流追加字符失败，或无法根据上述规则设置 pbase() 和 pptr() ，则函数可能失败。
• 若函数成功，则返回除 Traits :: eof ( ) 外的某个值。通常返回 ch 表示成功，除非 Traits :: eq_int_type ( ch, Traits :: eof ( ) ) 返回 true ，此时返回 Traits :: not_eof ( ch ) 。
• 若函数失败，则返回 Traits :: eof ( ) 或抛出异常。

注释

当发生溢出时（ pptr ( ) == nullptr 或 pptr ( ) >= epptr ( ) ）， sputc() 和 sputn() 会调用此函数。

示例

#include <array>
#include <cstddef>
#include <iostream>
// 由 std::array 实现的 std::ostream 缓冲区
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

参见