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

来自cppreference.com
 
C++
 
输入/输出库
 
std::basic_streambuf
公开成员函数
本地环境
寻位
获取区
放置区
回放
受保护成员函数
(C++11)
(C++11)
本地环境
寻位
获取区
放置区
回放
 
<tbody> </tbody>
protected: virtual int_type overflow( int_type ch = Traits::eof() );
See More

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

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

参数

ch - 要在放置区存储的字符

返回值

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 的虚受保护成员函数) [编辑]