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 的虛保護成員函式）