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

 

C++

编译器支持

自由（freestanding）与宿主（hosted）

语言

标准库

标准库头文件

具名要求

特性测试宏 (C++20)

语言支持库

概念库 (C++20)

诊断库

内存管理库

元编程库 (C++11)

通用工具库

容器库

迭代器库

范围库 (C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库 (C++17)

并发支持库 (C++11)

执行控制库 (C++26)

技术规范

符号索引

外部库

 

输入/输出库

I/O 操纵器

打印函数 (C++23)

C 风格 I/O

缓冲区

basic_streambuf

basic_filebuf

basic_stringbuf

basic_spanbuf (C++23)

strstreambuf (C++98/26*)

basic_syncbuf (C++20)

流

抽象

ios_base

basic_ios

basic_istream

basic_ostream

basic_iostream

文件 I/O

basic_ifstream

basic_ofstream

basic_fstream

字符串 I/O

basic_istringstream

basic_ostringstream

basic_stringstream

数组 I/O

basic_ispanstream (C++23)

basic_ospanstream (C++23)

basic_spanstream (C++23)

istrstream (C++98/26*)

ostrstream (C++98/26*)

strstream (C++98/26*)

同步输出

basic_osyncstream (C++20)

类型

streamoff

streamsize

fpos

错误类别接口

iostream_category (C++11)

io_errc (C++11)

 

std::basic_streambuf

公开成员函数 basic_streambuf::~basic_streambuf      区域设置 basic_streambuf::pubimbue basic_streambuf::getloc 定位 basic_streambuf::pubsetbuf basic_streambuf::pubseekoff basic_streambuf::pubseekpos basic_streambuf::pubsync 获取区 basic_streambuf::in_avail basic_streambuf::snextc basic_streambuf::sbumpc basic_streambuf::sgetc basic_streambuf::sgetn 放置区 basic_streambuf::sputc basic_streambuf::sputn 回放 basic_streambuf::sputbackc basic_streambuf::sungetc

受保护的成员函数 basic_streambuf::basic_streambuf basic_streambuf::operator= (C++11) basic_streambuf::swap (C++11) 区域设置 basic_streambuf::imbue 定位 basic_streambuf::setbuf basic_streambuf::seekoff basic_streambuf::seekpos basic_streambuf::sync 获取区 basic_streambuf::showmanyc basic_streambuf::underflow basic_streambuf::uflow basic_streambuf::xsgetn basic_streambuf::ebackbasic_streambuf::gptrbasic_streambuf::egptr basic_streambuf::gbump basic_streambuf::setg 放置区 basic_streambuf::xsputn basic_streambuf::overflow basic_streambuf::pbasebasic_streambuf::pptrbasic_streambuf::epptr basic_streambuf::pbump basic_streambuf::setp 回放 basic_streambuf::pbackfail

 

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

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

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

参数

ch

-

- 要存储在放置区的字符

返回值

成功时返回不同于 Traits::eof() 的值。失败时返回 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>
 
// Buffer for std::ostream implemented by 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()
    {
        // put area pointers to work with '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{}; // value-initialize 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

参见

uflow [虚函数]	从关联输入序列中读取字符到获取区并推进下一个指针 （虚保护成员函数）
underflow [虚函数]	从关联输入序列中读取字符到获取区 （虚保护成员函数）
overflow [虚函数]	从放置区向关联文件写入字符 （std::basic_filebuf<CharT,Traits> 的虚保护成员函数）
overflow [虚函数]	将一个字符附加到输出序列 （std::basic_stringbuf<CharT,Traits,Allocator> 的虚保护成员函数）
overflow [虚函数]	向输出序列追加一个字符，如果缓冲区是动态且未冻结的，则可能重新分配或初始分配缓冲区 （std::strstreambuf 的虚保护成员函数）