std::basic_streambuf<CharT,Traits>::overflow - cppreference.com

来自cppreference.com

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() 为空时是空序列，否则是从 pbase() 开始的 pptr() - pbase() 个字符）。
- 字符 ch，或当 ch 为 EOF（正式而言，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() 或抛出异常。

注解

sputc() 和 sputn() 在可能上溢的情况（pptr() == nullptr 或 pptr() >= epptr()）下调用此函数。

示例

#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()
    {
        // 设置 std::basic_streambuf 放置区指针以 '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{}; // 值初始化 buffer
};

int main()
{
    ArrayedStreamBuffer<10> streambuf;
    std::ostream stream(&streambuf);
    
    stream << "hello";
    streambuf.print_buffer();
    if (stream.good())
        std::cout << "流正常\n";
    
    stream << "world";
    streambuf.print_buffer();
    if (stream.good())
        std::cout << "流正常\n";
    
    stream << "!";
    streambuf.print_buffer();
    if (!stream.good())
        std::cout << "流异常\n";
}

输出：

h e l l o \0 \0 \0 \0 \0
流正常
h e l l o w o r l d 
流正常
overflow
h e l l o w o r l d 
流异常

参阅

	从输入序列读取字符到获取区，并推进下一位置指针 (虚受保护成员函数) [编辑]
	从关联输入序列读取字符到获取区 (虚受保护成员函数) [编辑]
	从放置区写字符到关联的文件 (`std::basic_filebuf<CharT,Traits>` 的虚受保护成员函数) [编辑]
	后附字符到输出序列 (`std::basic_stringbuf<CharT,Traits,Allocator>` 的虚受保护成员函数) [编辑]
	后附字符到输出序列，可能重分配或初始地分配缓冲区，若它为动态且未被冻结 (`std::strstreambuf` 的虚受保护成员函数) [编辑]