std::basic_streambuf

 

C++

編譯器支援

獨立式與託管式

語言

標準函式庫

標準函式庫標頭檔

具名要求

特性測試巨集 (C++20)

語言支援函式庫

概念函式庫 (C++20)

診斷函式庫

記憶體管理函式庫

元編程函式庫 (C++11)

通用公用程式函式庫

容器函式庫

疊代器函式庫

Ranges 函式庫 (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      在地化 (Locales) basic_streambuf::pubimbue basic_streambuf::getloc 定位 basic_streambuf::pubsetbuf basic_streambuf::pubseekoff basic_streambuf::pubseekpos basic_streambuf::pubsync 讀取區 (Get area) basic_streambuf::in_avail basic_streambuf::snextc basic_streambuf::sbumpc basic_streambuf::sgetc basic_streambuf::sgetn 寫入區 (Put area) basic_streambuf::sputc basic_streambuf::sputn 回寫 (Putback) basic_streambuf::sputbackc basic_streambuf::sungetc

受保護的成員函式 basic_streambuf::basic_streambuf basic_streambuf::operator= (C++11) basic_streambuf::swap (C++11) 在地化 (Locales) basic_streambuf::imbue 定位 basic_streambuf::setbuf basic_streambuf::seekoff basic_streambuf::seekpos basic_streambuf::sync 讀取區 (Get area) 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 寫入區 (Put area) basic_streambuf::xsputn basic_streambuf::overflow basic_streambuf::pbasebasic_streambuf::pptrbasic_streambuf::epptr basic_streambuf::pbump basic_streambuf::setp 回寫 (Putback) basic_streambuf::pbackfail

 

定義於標頭檔 <streambuf>
template<     class CharT,     class Traits = std::char_traits<CharT> > class basic_streambuf;

basic_streambuf 類別控制字元序列的輸入與輸出。它包含並提供了對下列項目的存取：

1. 「受控字元序列」（Controlled character sequence），也稱為「緩衝區」（buffer），其可能包含用於緩衝輸入操作的「輸入序列」（也稱為「取得區域」，get area）和/或用於緩衝輸出操作的「輸出序列」（也稱為「放置區域」，put area）。
2. 「關聯字元序列」（Associated character sequence），也稱為「來源」（用於輸入）或「接收器」（用於輸出）。這可能是一個透過作業系統 API 存取的實體（檔案、TCP socket、序列埠、其他字元裝置），或者可能是一個可以被解釋為字元來源或接收器的物件（std::vector、陣列、字串實字）。

I/O 資料流物件 std::basic_istream 和 std::basic_ostream，以及所有衍生自它們的物件（std::ofstream、std::stringstream 等），其實現完全基於 std::basic_streambuf。

受控字元序列是一個 CharT 陣列，它始終代表關聯字元序列的一個子序列或「視窗」。其狀態由三個指標描述：

1. 「起始指標」（beginning pointer），始終指向緩衝區的最底層元素。
2. 「下一個指標」（next pointer），指向作為下一個讀取或寫入候選者的元素。
3. 「結尾指標」（end pointer），指向緩衝區末端之後的一個位置。

basic_streambuf 物件可以同時支援輸入（此時由起始、下一個和結尾指標所描述的緩衝區稱為「取得區域」）、輸出（「放置區域」），或者同時支援輸入與輸出。在後者的情況下，會追蹤六個指標，這些指標可能全部指向同一個字元陣列中的元素，或是指向兩個不同的陣列。

如果放置區域中的下一個指標小於結尾指標，則表示有「寫入位置」可用。該下一個指標可以被取值（dereferenced）並被賦值。

如果取得區域中的下一個指標小於結尾指標，則表示有「讀取位置」可用。該下一個指標可以被取值並被讀取。

如果取得區域中的下一個指標大於起始指標，則表示有「放回位置」（putback position）可用，並且可以將下一個指標遞減、取值並賦值，以便將一個字元放回取得區域中。

受控序列中的字元表示與編碼可能與關聯序列中的字元表示不同，在此情況下通常會使用 std::codecvt 地區設定元（locale facet）來執行轉換。常見的例子是透過 std::wfstream 物件存取的 UTF-8（或其他多位元組）檔案：受控序列由 wchar_t 字元組成，但關聯序列由位元組組成。

std::basic_streambuf 基底類別的典型實作僅保留六個 CharT* 指標以及一個 std::locale 的副本作為資料成員。此外，實作可能會保留地區設定元的快取副本，這些副本在每次呼叫 imbue() 時都會失效。具體的緩衝區（如 std::basic_filebuf 或 std::basic_stringbuf）皆繼承自 std::basic_streambuf。

為常見的字元型別提供了數個 typedef：

定義於標頭檔 <streambuf>
類型	定義
std::streambuf	std::basic_streambuf<char>
std::wstreambuf	std::basic_streambuf<wchar_t>

成員型別

成員型別	定義
char_type	CharT
traits_type	Traits；若 Traits::char_type 不為 CharT，則程式形式不良 (ill-formed)。
int_type	Traits::int_type
pos_type	Traits::pos_type
off_type	Traits::off_type

成員函數

(解構函式) [虛擬]	解構 basic_streambuf 物件 (虛擬公開成員函數)
在地化 (Locales)
pubimbue	變更關聯的地區設定並呼叫 imbue() (公開成員函數)
getloc	取得關聯地區設定的複本 (公開成員函數)
定位
pubsetbuf	呼叫 setbuf() (公開成員函數)
pubseekoff	呼叫 seekoff() (公開成員函數)
pubseekpos	呼叫 seekpos() (公開成員函數)
pubsync	呼叫 sync() (公開成員函數)
讀取區 (Get area)
in_avail	取得讀取區中立即可用的字元數 (公開成員函數)
snextc	推進輸入序列，然後讀取一個字元而不再次推進 (公開成員函數)
sbumpcstossc (C++17 移除)	從輸入序列讀取一個字元並推進序列 (公開成員函數)
sgetc	從輸入序列讀取一個字元而不推進序列 (公開成員函數)
sgetn	呼叫 xsgetn() (公開成員函數)
寫入區 (Put area)
sputc	將一個字元寫入寫入區並推進下一個指標 (公開成員函數)
sputn	呼叫 xsputn() (公開成員函數)
回寫 (Putback)
sputbackc	將一個字元放回輸入序列 (公開成員函數)
sungetc	將輸入序列中的下一個指標向後移動一個位置 (公開成員函數)
受保護的成員函式
(建構子)	建構一個 basic_streambuf 物件 (受保護成員函式)
operator= (C++11)	替換一個 basic_streambuf 物件 (受保護成員函式)
swap (C++11)	交換兩個 basic_streambuf 物件 (受保護成員函式)
在地化 (Locales)
imbue [虛擬]	對相關地區設定的變更做出反應 (虛擬受保護成員函數)
定位
setbuf [虛擬]	在許可的情況下，以使用者定義的陣列替換緩衝區 (虛擬受保護成員函數)
seekoff [虛擬]	使用相對定址，重新定位輸入序列、輸出序列或兩者的下一個指標 (虛擬受保護成員函數)
seekpos [虛擬]	使用絕對定址，重新定位輸入序列、輸出序列或兩者的下一個指標 (虛擬受保護成員函數)
sync [虛擬]	將緩衝區與關聯的字元序列同步 (虛擬受保護成員函數)
讀取區 (Get area)
showmanyc [虛擬]	取得關聯輸入序列中可供輸入的字元數（若已知） (虛擬受保護成員函數)
underflow [虛擬]	從關聯的輸入序列讀取字元至讀取區 (虛擬受保護成員函數)
uflow [虛擬]	從關聯的輸入序列讀取字元至讀取區並推進下一個指標 (虛擬受保護成員函數)
xsgetn [虛擬]	從輸入序列讀取多個字元 (虛擬受保護成員函數)
ebackgptregptr	回傳指向讀取區開頭、當前字元及結尾的指標 (受保護成員函式)
gbump	推進輸入序列中的下一個指標 (受保護成員函式)
setg	重新定位輸入序列的開頭、下一個及結尾指標 (受保護成員函式)
寫入區 (Put area)
xsputn [虛擬]	將多個字元寫入輸出序列 (虛擬受保護成員函數)
overflow [虛擬]	將寫入區的字元寫入關聯的輸出序列 (虛擬受保護成員函數)
pbasepptrepptr	回傳指向寫入區開頭、當前字元及結尾的指標 (受保護成員函式)
pbump	推進輸出序列中的下一個指標 (受保護成員函式)
setp	重新定位輸出序列的開頭、下一個及結尾指標 (受保護成員函式)
回寫 (Putback)
pbackfail [虛擬]	將字元放回輸入序列，可能會修改輸入序列 (虛擬受保護成員函數)

參見

FILE	物件型別，能夠保存控制 C I/O 串流所需的所有資訊 (typedef)