basic_streambuf 類別

描述抽象的基底類別，用以衍生資料流緩衝區，其控制項目如何傳入或傳出資料流的特定表示。

語法

template <class Elem, class Tr = char_traits<Elem>>
class basic_streambuf;

參數

Elem
char_type。

Tr
字元 traits_type。

備註

類別範本描述衍生數據流緩衝區的抽象基類，該緩衝區會控制專案在數據流的特定表示法和傳出之間的傳輸。 類別basic_streambuf的 對象可協助控制具有 Tr 類型元素的數據流，也稱為char_type，其字元特性是由類別char_traits所決定，也稱為traits_type。

每個資料流緩衝區在概念上會控制兩個獨立的資料流：一個用於擷取 (輸入)，一個用於插入 (輸出)。 不過，特定的表示法可能使這些資料流之一或兩者無法存取。 它通常會維護兩個資料流之間的某種關聯性。 例如，您在basic_stringbuf<中插入的內容，就是您稍後從其輸入數據流擷取的內容。 當您放置basic_filebuf個數據流置成一起。

類別範本 basic_streambuf 的公用介面會提供所有數據流緩衝區通用的作業，但特殊化。 受保護的介面會提供資料流的特定表示法以執行其工作所需的作業。 受保護的虛擬成員函式可讓您針對資料流的特定表示法量身訂做衍生之資料流緩衝區的行為。 此程式庫中每個衍生的資料流緩衝區會描述其特製化受保護之虛擬成員函式行為的方式。 本文說明基類的預設行為，通常不會執行任何動作。

剩餘的受保護成員函式會控制要提供給資料流往返傳輸之任何儲存體之間的複製。 例如，輸入緩衝區的特性有：

• eback，緩衝區開頭的指標。

• gptr，下個待讀取元素的指標。

• egptr，一個指標超過緩衝區的結尾。

同樣地，輸出緩衝區的特性有：

• pbase，緩衝區開頭的指標。

• pptr，下個待寫入元素的指標。

• epptr，指標超過緩衝區的結尾。

針對任何緩衝區，會使用下列通訊協定：

• 如果下一個指標為 null，則沒有緩衝區存在。 否則，所有三個指標都指向相同的順序。 它們可以安全地比較順序。

• 針對輸出緩衝區，如果下一個指標比較起來會小於結尾指標，您可以將項目儲存在下個指標所指定的寫入位置。

• 針對輸入緩衝區，如果下一個指標比較起來會小於結尾指標，您可以在下個指標所指定的讀取位置讀取項目。

• 針對輸入緩衝區，如果開始指標比較起來會小於下個指標，您可以將項目放回遞減過之下個指標所指定的放回位置。

您為衍生自 basic_streambuf<ElemTr> 之類別撰寫的任何受保護虛擬成員函式，都必須配合維護此通訊協定。

類別 basic_streambuf<Elem的物件， Tr> 會儲存先前所述的六個指標。 它也會在 locale 類型的物件中儲存地區設定物件，以供衍生的資料流緩衝區使用。

建構函式

Typedefs（類型定義）

成員函式

操作員

需求

Header：<streambuf>

命名空間：std

basic_streambuf：：basic_streambuf

建構類型 basic_streambuf 的物件。

basic_streambuf();

basic_streambuf(const basic_streambuf& right);

參數

右
basic_streambuf 物件的左值參考，用來設定這個 basic_streambuf 物件的值。

備註

第一個受保護的建構函式會在控制輸入緩衝區和輸出緩衝區的所有指標中儲存一個 null 指標。 它也會在地區設定物件中儲存 locale::classic。 如需詳細資訊，請參閱 locale::classic。

第二個受保護的建構函式會從 右側複製指標和地區設定。

basic_streambuf：：char_type

將類型名稱與 Elem 樣板參數產生關聯。

typedef Elem char_type;

basic_streambuf：：eback

受保護的函式，會傳回輸入緩衝區開頭的指標。

char_type *eback() const;

傳回值

輸入緩衝區開頭的指標。

basic_streambuf：：egptr

受保護的函式，傳回超過輸入緩衝區結尾的指標。

char_type *egptr() const;

傳回值

超過輸入緩衝區結尾的指標。

basic_streambuf：：epptr

受保護的函式，傳回輸出緩衝區結尾的指標。

char_type *epptr() const;

傳回值

輸出緩衝區結尾的指標。

basic_streambuf：：gbump

受保護的函式，會將計數新增至輸入緩衝區的下一個指標。

void gbump(int count);

參數

計數
用來將指標向前移的數量。

basic_streambuf：：getloc

取得 basic_streambuf 物件的地區設定。

locale getloc() const;

傳回值

已儲存的地區設定物件。

備註

如需相關資訊，請參閱 ios_base::getloc。

範例

// basic_streambuf_getloc.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
   using namespace std;
   cout << cout.rdbuf( )->getloc( ).name( ).c_str( ) << endl;
}

C

basic_streambuf：：gptr

受保護的函式，會傳回輸入緩衝區下個項目的指標。

char_type *gptr() const;

傳回值

輸入緩衝區中下一個元素的指標。

basic_streambuf：：imbue

受保護的虛擬函式，由 pubimbue 呼叫。

virtual void imbue(const locale& _Loc);

參數

_Loc
地區設定的參考。

備註

預設行為是不執行任何動作。

basic_streambuf：：in_avail

傳回可以從緩衝區讀取的項目數。

streamsize in_avail();

傳回值

準備從緩衝區讀取的元素數目。

備註

如果讀取位置可用，成員函式會傳回 egptr - gptr。 否則會傳回 showmanyc。

範例

// basic_streambuf_in_avail.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
   using namespace std;
   char c;
   // cin's buffer is empty, in_avail will return 0
   cout << cin.rdbuf( )->in_avail( ) << endl;
   cin >> c;
   cout << cin.rdbuf( )->in_avail( ) << endl;
}

basic_streambuf：：int_type

將 basic_streambuf 範圍內的類型名稱與樣板參數中的其中一個類型產生關聯。

typedef typename traits_type::int_type int_type;

basic_streambuf：：off_type

將 basic_streambuf 範圍內的類型名稱與樣板參數中的其中一個類型產生關聯。

typedef typename traits_type::off_type off_type;

basic_streambuf：：operator=

從另一個 basic_streambuf 物件指派這個物件的值。

basic_streambuf& operator=(const basic_streambuf& right);

參數

右
用來指派值給此物件的 basic_streambuf 左值參考物件。

備註

受保護的成員運算符會從 控制輸入緩衝區和輸出緩衝區的指標右側 複製。 它也會在 right. 中儲存 locale object。 它會傳回 *this。

basic_streambuf：：overflow

受保護的虛擬函式，可在將新字元插入已滿的緩衝區時呼叫。

virtual int_type overflow(int_type _Meta = traits_type::eof());

參數

_元
要插入緩衝區的字元，或 traits_type::eof。

傳回值

如果函式無法成功，它會傳回 traits_type：：eof 或擲回例外狀況。 否則會傳回 traits_type::not_eof(_ Meta)。 預設行為是傳回 traits_type::eof。

備註

如果_Meta不等於 traits_type：：eof，受保護的虛擬成員函式會努力將元素插入輸出數據流traits_type：：to_char_type（_Meta）。 它可以透過下列各種方式來執行：

• 如果有write position可供使用，它可以將元素儲存在寫入位置，並遞增輸出緩衝區的下一個指標。

• 為輸出緩衝區配置新的或額外的儲存空間，即可提供寫入位置。

• 藉由將輸出緩衝區的開頭指標和下一個指標之間的部分或所有元素寫出至特定外部目的地，即可提供寫入位置。

此虛擬 overflow 函式可搭配 sync 和 underflow 函式，定義 streambuf 衍生類別的特性。 每個衍生類別可能會以不同的方式來實作 overflow，但呼叫資料流類別的介面則相同。

overflow 函式最常在 put 區域已滿的情況下，由公開 streambuf 函式 (例如 sputc 和 sputn) 呼叫，但其他類別 (包括資料流類別) 也可以隨時呼叫 overflow。

此函式會取用 put 區域中介於 pbase 和 pptr 指標之間的字元，然後將 put 區域重新初始化。 函 overflow 式也必須取用 nCh （如果 nCh 不是 EOF），或者它可能會選擇將該字元放在新的放置區域中，以便在下一次呼叫時取用該字元。

取用的定義會因衍生類別而異。 例如，filebuf 類別會將其字元寫入至檔案，而 strstreambuf 類別會將這些字元保留在其緩衝區中 (如果緩衝區已指定為動態)，並擴充緩衝區以回應溢位呼叫。 此擴充可透過釋放舊緩衝區並取代為較大的新緩衝區來達成。 這些指標會視需要進行調整。

basic_streambuf：:p backfail

受保護的虛擬成員函式，會嘗試將項目放回輸入資料流，然後將其設成目前的項目 (由下一個指標指向)。

virtual int_type pbackfail(int_type _Meta = traits_type::eof());

參數

_元
要插入緩衝區的字元，或 traits_type::eof。

傳回值

如果函式無法成功，它會傳回 traits_type：：eof 或擲回例外狀況。 否則，它會傳回其他值。 預設行為是傳回 traits_type::eof。

備註

如果 _Meta 比較等於 traits_type：：eof，則要回推的項目實際上是目前專案之前已在數據流中的元素。 否則，該元素會取代為 traits_type：：to_char_type（_Meta）。 此函式可以透過下列各種方式來放回元素：

• 如果有放回位置可供使用，它可以將元素儲存在放回位置，並遞減輸入緩衝區的下一個指標。

• 藉由為輸入緩衝區配置新的或額外的儲存體，即可提供放回位置。

• 針對具有通用輸入和輸出資料流的資料流緩衝區，藉由將輸出緩衝區的開頭指標和下一個指標之間的部分或所有元素寫出至特定外部目的地，即可提供放回位置。

basic_streambuf：:p base

受保護的函式，會傳回輸出緩衝區開頭的指標。

char_type *pbase() const;

傳回值

輸出緩衝區開頭的指標。

basic_streambuf：:p bump

受保護的函式，會將計數新增至輸出緩衝區的下一個指標。

void pbump(int count);

參數

計數
用來將寫入位置向前移動的字元數。

basic_streambuf：:p os_type

將 basic_streambuf 範圍內的類型名稱與樣板參數中的其中一個類型產生關聯。

typedef typename traits_type::pos_type pos_type;

basic_streambuf：:p ptr

受保護的函式，會傳回輸出緩衝區下個項目的指標。

char_type *pptr() const;

傳回值

輸出緩衝區中下一個元素的指標。

basic_streambuf：:p ubimbue

設定 basic_streambuf 物件的地區設定。

locale pubimbue(const locale& _Loc);

參數

_Loc
地區設定的參考。

傳回值

先前儲存在地區設定物件中的值。

備註

此成員函式會在地區設定物件中儲存 _ Loc，並呼叫 imbue。

範例

如需使用 的範例，請參閱 pubimbue。

basic_streambuf：:p ubseekoff

呼叫 seekoff，這是在衍生類別中遭覆寫的受保護虛擬函式。

pos_type pubseekoff(off_type _Off,
    ios_base::seekdir _Way,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

參數

_Off
要尋找相對於 _Way的位置。

_道路
位移作業的起點。 如需可能的值，請參閱 seekdir。

_哪
指定指標位置的模式。 預設為允許您修改讀取和寫入位置。

傳回值

傳回新位置或無效的數據流位置（seekoff（_ Off、 _Way、 _Which））。

備註

將指標相對於 _Way移動。

basic_streambuf：:p ubseekpos

呼叫 seekpos，這是在衍生類別中遭覆寫的受保護虛擬函式，並且重設目前的指標位置。

pos_type pubseekpos(pos_type _Sp, ios_base::openmode _Which = ios_base::in | ios_base::out);

參數

_Sp
要搜尋的位置。

_哪
指定指標位置的模式。 預設為允許您修改讀取和寫入位置。

傳回值

新位置或無效的資料流位置。 若要判斷資料流位置是否無效，請比較傳回值與 pos_type(off_type(-1))。

備註

此成員函式會傳回 seekpos(_ Sp, _Which)。

basic_streambuf：:p ubsetbuf

呼叫 setbuf，這是在衍生類別中遭覆寫的受保護虛擬函式。

basic_streambuf<Elem, Tr> *pubsetbuf(
    char_type* _Buffer,
    streamsize count);

參數

_緩衝區
此具現化的 char_type 指標。

計數
緩衝區的大小。

傳回值

會傳回 setbuf（_Buffer， count）。

basic_streambuf：:p ubsync

呼叫 sync，這是在衍生類別中遭覆寫的受保護虛擬函式，並且更新這個緩衝區相關聯的外部資料流。

int pubsync();

傳回值

如果失敗，則傳 回 sync 或 -1。

basic_streambuf：：sbumpc

讀取並傳回目前項目，同時移動資料流指標。

int_type sbumpc();

傳回值

目前的元素。

備註

如果讀取位置可用，成員函式會傳回 traits_type：：to_int_type（*gptr），並遞增輸入緩衝區的下一個指標。 否則會傳回 uflow。

範例

// basic_streambuf_sbumpc.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
   using namespace std;
   int i = 0;
   i = cin.rdbuf( )->sbumpc( );
   cout << i << endl;
}

3

33
51

basic_streambuf：：seekoff

受保護虛擬成員函式嘗試改變受控制資料流目前的位置。

virtual pos_type seekoff(
    off_type _Off,
    ios_base::seekdir _Way,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

參數

_Off
要尋找相對於 _Way的位置。

_道路
位移作業的起點。 如需可能的值，請參閱 seekdir。

_哪
指定指標位置的模式。 預設為允許您修改讀取和寫入位置。

傳回值

傳回新位置或無效的數據流位置（seekoff _ Off、 _Way、 _Which））。

備註

新位置的判斷如下：

• 如果 _Way == ios_base::beg，新位置是資料流開頭加上 _ Off。

• 如果 _Way == ios_base::cur，新位置是目前的資料流位置加上 _ Off。

• 如果 _Way == ios_base::end，新位置是資料流結尾加上 _ Off。

一般而言，如果 which & ios_base::in 為非零值，則會影響輸入資料流；如果 which & ios_base::out 為非零值，則會影響輸出資料流。 不過，此參數的實際用法會因衍生的資料流緩衝區而異。

如果此函式成功改變一或多個資料流位置，則會傳回產生的資料流位置或其中一個產生的資料流位置。 否則會傳回無效的資料流位置。 預設行為是傳回無效的資料流位置。

basic_streambuf：：seekpos

受保護虛擬成員函式嘗試改變受控制資料流目前的位置。

virtual pos_type seekpos(pos_type _Sp, ios_base::openmode _Which = ios_base::in | ios_base::out);

參數

_Sp
要搜尋的位置。

_哪
指定指標位置的模式。 預設為允許您修改讀取和寫入位置。

傳回值

新位置或無效的資料流位置。 若要判斷資料流位置是否無效，請比較傳回值與 pos_type(off_type(-1))。

備註

新位置為 _ Sp。

一般而言，如果 which & ios_base::in 為非零值，則會影響輸入資料流；如果 which & ios_base::out 為非零值，則會影響輸出資料流。 不過，此參數的實際用法會因衍生的資料流緩衝區而異。

如果此函式成功改變一或多個資料流位置，則會傳回產生的資料流位置或其中一個產生的資料流位置。 否則會傳回無效的資料流位置 (-1)。 預設行為是傳回無效的資料流位置。

basic_streambuf：：setbuf

受保護的虛擬成員函式，會執行每個衍生資料流緩衝區的特定作業。

virtual basic_streambuf<Elem, Tr> *setbuf(
    char_type* _Buffer,
    streamsize count);

參數

_緩衝區
緩衝區的指標。

計數
緩衝區的大小。

傳回值

預設行為是傳回 this。

備註

請參閱 basic_filebuf。 setbuf 會提供一個記憶體區域給 streambuf 物件使用。 緩衝區的使用方式會定義於衍生類別中。

basic_streambuf：：setg

受保護的函式，會在輸入緩衝區的開頭指標儲存 _ Gbeg，在下一個指標儲存 _Gnext，以及在結尾指標儲存 _Gend。

void setg(char_type* _Gbeg,
    char_type* _Gnext,
    char_type* _Gend);

參數

_Gbeg
緩衝區開頭的指標。

_Gnext
緩衝區中間某個位置的指標。

_Gend
緩衝區結尾的指標。

basic_streambuf：：setp

受保護的函式，會將 _Pbeg 儲存在開頭指標中，並在 輸出緩衝區的結尾指標中_Pend 。

void setp(char_type* _Pbeg, char_type* _Pend);

參數

_Pbeg
緩衝區開頭的指標。

_Pend
緩衝區結尾的指標。

basic_streambuf：：sgetc

傳回目前的項目而不變更資料流中的位置。

int_type sgetc();

傳回值

目前的元素。

備註

如果讀取位置可用，成員函式會傳回 traits_type：：to_int_type（*gptr）。 否則會傳回 underflow。

範例

// basic_streambuf_sgetc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;
   ifstream myfile( "basic_streambuf_sgetc.txt", ios::in );

   char i = myfile.rdbuf( )->sgetc( );
   cout << i << endl;
   i = myfile.rdbuf( )->sgetc( );
   cout << i << endl;
}

basic_streambuf：：sgetn

從輸入緩衝區擷取最多 計數 字元，並將其儲存在提供的緩衝區 ptr 中。

此方法有賴於呼叫者檢查傳遞的值是否正確，因此可能不安全。

streamsize sgetn(
    char_type* ptr,
    streamsize count);

參數

ptr
要包含所擷取字元的緩衝區。

計數
要讀取的元素數目。

傳回值

所讀取的元素數目。 如需詳細資訊，請參閱 streamsize 以取得詳細資訊。

備註

成員函式會傳回 xsgetn（ptr， count。

範例

// basic_streambuf_sgetn.cpp
// compile with: /EHsc /W3
#include <iostream>
#include <fstream>

int main()
{
    using namespace std;

    ifstream myfile("basic_streambuf_sgetn.txt", ios::in);
    char a[10];

    // Extract 3 characters from myfile and store them in a.
    streamsize i = myfile.rdbuf()->sgetn(&a[0], 3);  // C4996
    a[i] = myfile.widen('\0');

    // Display the size and contents of the buffer passed to sgetn.
    cout << i << " " << a << endl;

    // Display the contents of the original input buffer.
    cout << myfile.rdbuf() << endl;
}

basic_streambuf：：showmanyc

受保護的虛擬成員函式，會傳回可從輸入數據流擷取的字元數計數，並確保程式不受無限期等候的影響。

virtual streamsize showmanyc();

傳回值

預設行為是傳回零。

basic_streambuf：：snextc

讀取目前項目並傳回下個項目。

int_type snextc();

傳回值

資料流中的下一個元素。

備註

此成員函式會呼叫 sbumpc；如果該函式傳回 traits_type::eof，則傳回 traits_type::eof。 否則會傳回 sgetc。

範例

// basic_streambuf_snextc.cpp
// compile with: /EHsc
#include <iostream>
int main( )
{
   using namespace std;
   int i = 0;
   i = cin.rdbuf( )->snextc( );
   // cout << ( int )char_traits<char>::eof << endl;
   cout << i << endl;
}

aa

aa97

basic_streambuf：：sputbackc

將 char_type 放入資料流。

int_type sputbackc(char_type _Ch);

參數

_Ch
字元。

傳回值

傳回字元或失敗。

備註

如果放回位置可用且 _Ch 會比較與儲存在該位置中的字元相等，則成員函式會遞減輸入緩衝區的下一個指標，並傳回 traits_type：：to_int_type（_Ch）。 否則，它會傳回 pbackfail（_Ch）。

範例

// basic_streambuf_sputbackc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
    using namespace std;

    ifstream myfile("basic_streambuf_sputbackc.txt",
        ios::in);

    int i = myfile.rdbuf()->sbumpc();
    cout << (char)i << endl;
    int j = myfile.rdbuf()->sputbackc('z');
    if (j == 'z')
    {
        cout << "it worked" << endl;
    }
    i = myfile.rdbuf()->sgetc();
    cout << (char)i << endl;
}

basic_streambuf：：sputc

將字元放入資料流。

int_type sputc(char_type _Ch);

參數

_Ch
字元。

傳回值

如果成功，則傳回字元。

備註

write position如果 可用，成員函式會將_Ch儲存在寫入位置、遞增輸出緩衝區的下一個指標，並傳回traits_type：：to_int_type（_Ch）。 否則，它會傳回 overflow（_Ch）。

範例

// basic_streambuf_sputc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;

   int i = cout.rdbuf( )->sputc( 'a' );
   cout << endl << ( char )i << endl;
}

a
a

basic_streambuf：：sputn

將字元字串放入資料流。

streamsize sputn(const char_type* ptr, streamsize count);

參數

ptr
字元字串。

計數
字元計數。

傳回值

插入數據流的字元數。

備註

成員函式會傳回 xsputn（ptr， count。 如需詳細資訊，請參閱此成員的一節以取得詳細資訊。

範例

// basic_streambuf_sputn.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main()
{
    using namespace std;

    streamsize i = cout.rdbuf()->sputn("test", 4);
    cout << endl << i << endl;
}

test
4

basic_streambuf：：stossc

移動超過資料流中目前的項目。

void stossc();

備註

此成員函式會呼叫 sbumpc。 提供此成員函式不需要實作。

範例

// basic_streambuf_stossc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;
   ifstream myfile( "basic_streambuf_stossc.txt", ios::in );

   myfile.rdbuf( )->stossc( );
   char i = myfile.rdbuf( )->sgetc( );
   cout << i << endl;
}

basic_streambuf：：sungetc

從資料流取得字元。

int_type sungetc();

傳回值

傳回字元或失敗。

備註

如果有可用的重播位置，成員函式會遞減輸入緩衝區的下一個指標，並傳回 traits_type::to_int_type（*gptr）。 不過，不一定能夠判斷讀取的最後一個字元，以便以目前緩衝區的狀態擷取。 如果是此情況，則函式會傳回 pbackfail。 若要避免這種情況，請追蹤要放回並呼叫 sputbackc(ch)的字元，前提是您未在數據流開頭呼叫該字元，而且您不會嘗試放回一個以上的字元，則不會失敗。

範例

// basic_streambuf_sungetc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;

   ifstream myfile( "basic_streambuf_sungetc.txt", ios::in );

   // Read and increment
   int i = myfile.rdbuf( )->sbumpc( );
   cout << ( char )i << endl;

   // Read and increment
   i = myfile.rdbuf( )->sbumpc( );
   cout << ( char )i << endl;

   // Decrement, read, and do not increment
   i = myfile.rdbuf( )->sungetc( );
   cout << ( char )i << endl;

   i = myfile.rdbuf( )->sungetc( );
   cout << ( char )i << endl;

   i = myfile.rdbuf( )->sbumpc( );
   cout << ( char )i << endl;
}

basic_streambuf：：swap

用此物件的值交換所提供的 basic_streambuf 物件中的值。

void swap(basic_streambuf& right);

參數

右
用來交換值的 basic_streambuf 左值參考物件。

備註

受保護的成員函式會與交換。 它也會將 right.getloc() 與 locale 物件交換。

basic_streambuf：：sync

受保護的虛擬函式，會嘗試與任何相關聯的外部資料流同步處理控制資料流。

virtual int sync();

傳回值

如果函式無法成功，則會傳回 -1。 預設行為是傳回零。

備註

sync 需要將輸出緩衝區的開頭指標和下一個指標之間的任何元素寫出。 這並不牽涉到在輸入緩衝區的下一個和結束指標之間放回任何元素。

basic_streambuf：：traits_type

將類型名稱與 Tr 樣板參數產生關聯。

typedef Tr traits_type;

basic_streambuf：：uflow

受保護的虛擬函式，會從輸入資料流擷取目前的項目。

virtual int_type uflow();

傳回值

目前的元素。

備註

此受保護的虛擬成員函式會嘗試從輸入資料流擷取目前的元素 ch，然後從目前的資料流位置前移，並傳回此元素作為 traits_type::to_int_type( ch)。 它可以透過下列各種方式來執行：

• 如果有讀取位置可供使用，它會接受 ch 作為儲存在讀取位置中的元素，並前進到輸入緩衝區的下一個指標。

• 它可以直接從特定外部來源讀取元素，並提供此元素作為 ch 值。

• 針對具有通用輸入和輸出資料流的資料流緩衝區，藉由將輸出緩衝區的開頭指標和下一個指標之間的部分或所有元素寫出至特定外部目的地，即可提供讀取位置。 或者，它可以為輸入緩衝區配置新的或額外的儲存體。 此函式接著會從特定外部來源讀入一或多個元素。

如果函式無法成功，它會傳 回 traits_type：：eof，或擲回例外狀況。 否則，它會傳回輸入資料流中目前的元素 ch (已如上所述進行轉換)，並前進到輸入緩衝區的下一個指標。 預設行為是呼叫 underflow；如果該函式傳回 traits_type::eof，則傳回 traits_type::eof。 否則，此函式會傳回輸入資料流中目前的元素 ch (已如上所述進行轉換)，並前進到輸入緩衝區的下一個指標。

basic_streambuf：：underflow

用於從輸入資料流擷取目前項目之受保護的虛擬函式。

virtual int_type underflow();

傳回值

目前的元素。

備註

此受保護的虛擬成員函式會嘗試從輸入資料流擷取目前的元素 ch，而不需要從目前的資料流位置前移，並傳回此元素作為 traits_type::to_int_type( ch)。 它可以透過下列各種方式來執行：

• 如果有讀取位置可供使用，ch 會是儲存在讀取位置的元素。 如需詳細資訊，請參閱 basic_streambuf 類別的＜備註＞一節。

• 藉由為輸入緩衝區配置新的或額外的儲存體，然後從特定外部來源讀入一或多個元素，即可提供讀取位置。 如需詳細資訊，請參閱 basic_streambuf 類別的＜備註＞一節。

如果函式無法成功，它會傳 traits_type::回 eof() 或擲回例外狀況。 否則會傳回輸入資料流中目前的元素 (已如上所述進行轉換)。 預設行為是傳回 traits_type::eof()。

此虛擬 underflow 函式可搭配 sync 和 overflow 函式，定義 streambuf 衍生類別的特性。 每個衍生類別可能會以不同的方式來實作 underflow，但呼叫資料流類別的介面則相同。

underflow 函式最常在 get 區域為空白的情況下，由公開 streambuf 函式 (例如 sgetc 和 sgetn) 呼叫，但其他類別 (包括資料流類別) 也可以隨時呼叫 underflow。

underflow 函式會將來自輸入來源的字元提供給 get 區域。 如果 get 區域包含字元，underflow 會傳回第一個字元。 如果 get 區域為空白，則會填滿 get 區域，並傳回留在 get 區域中的下一個字元。 如果沒有更多字元可供使用，則 underflow 會傳回 EOF，並將 get 區域保留空白。

在 strstreambuf 類別中，underflow 會調整 egptr 指標，以存取藉由呼叫 overflow 所動態配置的儲存體。

basic_streambuf：：xsgetn

要從輸入資料流擷取元素的受保護虛擬函式。

此方法有賴於呼叫者檢查傳遞的值是否正確，因此可能不安全。

virtual streamsize xsgetn(
    char_type* ptr,
    streamsize count);

參數

ptr
要包含所擷取字元的緩衝區。

計數
要擷取的元素數目。

傳回值

所擷取的元素數目。

備註

受保護的虛擬成員函式會從輸入數據流中擷取最多計數元素，就像透過重複呼叫 sbumpc 一樣，並將其儲存在從 ptr 開始的陣列中。 它會傳回擷取的項目數目。

basic_streambuf：：xsputn

要將元素插入輸出資料流的受保護虛擬函式。

virtual streamsize xsputn(const char_type* ptr, streamsize count);

參數

ptr
要插入的元素指標。

計數
要插入的元素數目。

傳回值

插入數據流的項目數目。

備註

受保護的虛擬成員函式會從從 ptr 開始的數位，將最多插入至輸出數據流中的項目計數，就像透過重複呼叫 sputc 一樣。 一旦寫入所有 計數 字元，或呼叫 sputc( count) 會傳回 traits::eof()，字元插入輸出數據流就會停止。 它會傳回插入的項目數。

另請參閱

C++ 標準程式庫中的執行緒安全
iostream 程式設計
iostreams 慣例