共用方式為


basic_istream 類別

描述物件,此物件控制從數據流緩衝區擷取元素和編碼的物件,其類型 Char_T為 ,也稱為 char_type,其字元特性是由 類別 Tr所決定,也稱為 traits_type

語法

template <class Char_T, class Tr = char_traits<Char_T>>
class basic_istream : virtual public basic_ios<Char_T, Tr>

備註

多載 operator>> 的大部分成員函式都是格式化的輸入函式。 它們遵循下列模式:

iostate state = goodbit;
const sentry ok(*this);

if (ok)
{
    try
    {
        /*extract elements and convert
            accumulate flags in state.
            store a successful conversion*/
    }
    catch (...)
    {
        try
        {
            setstate(badbit);

        }
        catch (...)
        {
        }
        if ((exceptions()& badbit) != 0)
            throw;
    }
}
setstate(state);

return (*this);

許多其他的成員函式為未經格式化的輸入函式。 它們遵循下列模式:

iostate state = goodbit;
count = 0;    // the value returned by gcount
const sentry ok(*this, true);

if (ok)
{
    try
    {
        /* extract elements and deliver
            count extracted elements in count
            accumulate flags in state */
    }
    catch (...)
    {
        try
        {
            setstate(badbit);

        }
        catch (...)
        {
        }
        if ((exceptions()& badbit) != 0)
            throw;
    }
}
setstate(state);

如果兩組函式在擷取元素時遇到檔案尾,就會呼叫 setstate(eofbit) 。 如需詳細資訊,請參閱setstate

類別 basic_istream<Char_T, Tr> 存放區的物件:

  • 類別 basic_ios<Char_T, Tr>的虛擬公用基底物件。 如需詳細資訊,請參閱basic_ios

  • 最後一個未格式化輸入作業的擷取計數(在先前的程式代碼中呼叫 count )。

範例

如需深入瞭解輸入數據流,請參閱 Class 的範例。basic_ifstream

建構函式

建構函式 描述
basic_istream 建構類型 basic_istream 的物件。

成員函式

成員函數 描述
gcount 傳回最後一個未經格式化的輸入期間,讀取的字元數。
get 從輸入資料流讀取一或多個字元。
getline 從輸入資料流讀取一行。
ignore 導致從目前的讀取位置略過一些項目。
peek 傳回要讀取的下一個字元。
putback 將指定的字元放入資料流。
read 從資料流讀取指定的字元數,並將其儲存在陣列中。
readsome 只從緩衝區讀取。
seekg 移動資料流中的讀取位置。
sentry 此巢狀類別會描述物件,該物件的宣告會建構格式化的輸入函式以及未經格式化的輸入函式。
swap basic_istream 物件交換所提供的 basic_istream 物件參數。
sync 同步處理數據流的相關聯輸入裝置與數據流的緩衝區。
tellg 回報在資料流中目前的讀取位置。
unget 將最近讀取的字元放回資料流。

操作員

運算子 描述
operator>> 呼叫輸入資料流上的函式,或從輸入資料流讀取經格式化的資料。
operator= 將位於運算子右側的 basic_istream 指派給此物件。 這是一個移動指派,涉及 rvalue 不會留下複本的參考。

需求

頁眉: <istream>

命名空間std

basic_istream::basic_istream

建構類型 basic_istream 的物件。

explicit basic_istream(
    basic_streambuf<Char_T, Tr>* strbuf,
    bool _Isstd = false);

basic_istream(basic_istream&& right);

參數

strbuf
basic_streambuf 類型的物件。

_Isstd
true 如果它是標準數據流,則為 ;否則為 false

right
要複製的 basic_istream 物件。

備註

第一個建構函式會呼叫 init(strbuf)來初始化基類。 它也會在擷取計數中儲存零。 如需詳細資訊,請參閱init。 如需此擷取計數的詳細資訊,請參閱類別概觀的basic_istream一節。

第二個建構函式會藉由呼叫 move(right) 初始化基底類別。 它也會儲存 right.gcount() 在擷取計數中,並將零儲存在 的擷取計數 right中。

範例

如需深入瞭解輸入數據流,請參閱 的 basic_ifstream::basic_ifstream 範例。

basic_istream::gcount

傳回最後一個未經格式化的輸入期間,讀取的字元數。

streamsize gcount() const;

傳回值

擷取計數。

備註

用來 basic_istream::get 讀取未格式化的字元。

範例

// basic_istream_gcount.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   cout << "Type the letter 'a': ";

   ws( cin );
   char c[10];

   cin.get( &c[0],9 );
   cout << c << endl;

   cout << cin.gcount( ) << endl;
}
a
Type the letter 'a': a
1

basic_istream::get

從輸入資料流讀取一或多個字元。

int_type get();

basic_istream<Char_T, Tr>& get(Char_T& Ch);
basic_istream<Char_T, Tr>& get(Char_T* str, streamsize count);
basic_istream<Char_T, Tr>& get(Char_T* str, streamsize count, Char_T delimiter);

basic_istream<Char_T, Tr>& get(basic_streambuf<Char_T, Tr>& strbuf);
basic_istream<Char_T, Tr>& get(basic_streambuf<Char_T, Tr>& strbuf, Char_T delimiter);

參數

count
要從 strbuf 中讀取的字元數。

delimiter
如果在 之前 count遇到讀取,則應該終止讀取的字元。

str
要在其中寫入的字串。

Ch
要取得的字元。

strbuf
要在其中寫入的緩衝區。

傳回值

的無參數形式 get 會傳回讀取為整數或檔尾的專案。 其餘窗體會傳回數據流 (*this)。

備註

第一個未格式化的輸入函式會盡可能擷取專案,就像傳回 rdbuf->sbumpc一樣。 否則會傳回 traits_type::eof。 如果函式未擷取任何專案,它會呼叫 setstate(failbit)。 如需詳細資訊,請參閱setstate

第二個函式會以相同方式擷取 int_type 元素 meta 。 如果 meta 比較 等於 traits_type::eof,則函式會呼叫 setstate(failbit)。 否則,它會儲存 traits_type::to_char_type(meta) 在 中 Ch。 函式會傳回 *this。 如需詳細資訊,請參閱to_char_type

第三個函式會傳 get(str, count, widen('\n'))回 。

第四個函式會擷取最多元素 count - 1 ,並將其儲存在從 開始 str的陣列中。 它一律會在所儲存的任何已擷取元素之後儲存 char_type。 為了進行測試,在下列情況下會停止擷取:

  • 到達檔案結尾時。

  • 函式擷取與 相等 delimiter的項目之後。 在此情況下,元素會放回受控制序列。

  • 函式擷 count - 1 取項目之後。

如果此函式未擷取任何元素,則會呼叫 setstate(failbit). 在任何情況下,它都會傳回 *this

第五個函式會傳 get(strbuf, widen('\n'))回 。

第六個函式會擷取專案,並將其插入 。strbuf 擷取會在檔尾或比較等於 delimiter的專案上停止,但不會擷取。 如果插入失敗或擲回例外狀況 (會攔截但不會再次擲回),也會停止,而不會擷取有問題的元素。 如果此函式未擷取任何元素,則會呼叫 setstate(failbit). 在任何情況下,函式會傳 *this回 。

範例

// basic_istream_get.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10];

   c[0] = cin.get( );
   cin.get( c[1] );
   cin.get( &c[2],3 );
   cin.get( &c[4], 4, '7' );

   cout << c << endl;
}
1111

basic_istream::getline

從輸入資料流取得一行。

basic_istream<Char_T, Tr>& getline(
    char_type* str,
    streamsize count);

basic_istream<Char_T, Tr>& getline(
    char_type* str,
    streamsize count,
    char_type delimiter);

參數

count
要從 strbuf 中讀取的字元數。

delimiter
如果在 之前 count遇到讀取,則應該終止讀取的字元。

str
要在其中寫入的字串。

傳回值

數據流 (*this)。

備註

這些未格式化輸入函式的第一個會傳 getline(str, count, widen('\n'))回 。

第二個函式會擷取至 count - 1 專案,並將其儲存在從 開始 str的陣列中。 它一律會在所儲存的任何已擷取元素之後儲存字串結束字元。 為了進行測試,在下列情況下會停止擷取:

  • 到達檔案結尾時。

  • 函式擷取與 相等 delimiter的項目之後。 在此情況下,專案不會放回,而且不會附加至受控制序列。

  • 函式擷 count - 1 取項目之後。

如果函式未擷取任何項目或 count - 1 專案,則會呼叫 setstate(failbit)。 在任何情況下,它都會傳回 *this。 如需詳細資訊,請參閱setstate

範例

// basic_istream_getline.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10];

   cin.getline( &c[0], 5, '2' );
   cout << c << endl;
}
121

basic_istream::ignore

導致從目前的讀取位置略過一些項目。

basic_istream<Char_T, Tr>& ignore(
    streamsize count = 1,
    int_type delimiter = traits_type::eof());

參數

count
要從目前的讀取位置略過的元素數目。

delimiter
在計數之前遇到的專案會導致 ignore 傳回並允許讀取之後 delimiter 的所有元素。

傳回值

數據流 (*this)。

備註

未格式化的輸入函式最多會擷取並捨棄 count 個元素。 不過,如果 count 等於 numeric_limits<int>::max,則會將它視為任意大。 擷取會在檔尾或 Ch 專案上提早停止, traits_type::to_int_type(Ch) 因此會比較等於 delimiter (也會擷取)。 函式會傳回 *this。 如需詳細資訊,請參閱to_int_type

範例

// basic_istream_ignore.cpp
// compile with: /EHsc
#include <iostream>
int main( )
{
   using namespace std;
   char chararray[10];
   cout << "Type 'abcdef': ";
   cin.ignore( 5, 'c' );
   cin >> chararray;
   cout << chararray;
}
Type 'abcdef': abcdef
def

basic\_istream::operator>>

呼叫輸入資料流上的函式,或從輸入資料流讀取經格式化的資料。

basic_istream& operator>>(basic_istream& (* Pfn)(basic_istream&));
basic_istream& operator>>(ios_base& (* Pfn)(ios_base&));
basic_istream& operator>>(basic_ios<Char_T, Tr>& (* Pfn)(basic_ios<Char_T, Tr>&));
basic_istream& operator>>(basic_streambuf<Char_T, Tr>* strbuf);
basic_istream& operator>>(bool& val);
basic_istream& operator>>(short& val);
basic_istream& operator>>(unsigned short& val);
basic_istream& operator>>(int& val);
basic_istream& operator>>(unsigned int& val);
basic_istream& operator>>(long& val);
basic_istream& operator>>(unsigned long& val);
basic_istream& operator>>(long long& val);
basic_istream& operator>>(unsigned long long& val);
basic_istream& operator>>(void *& val);
basic_istream& operator>>(float& val);
basic_istream& operator>>(double& val);
basic_istream& operator>>(long double& val);

參數

Pfn
函式指標。

strbuf
stream_buf 類型的物件。

val
要從資料流中讀取的值。

傳回值

數據流 (*this)。

備註

<istream> 標頭也會定義數個全域擷取運算子。 如需詳細資訊,請參閱operator>> (\<istream>)

第一個成員函式可確保表單 istr >> ws 的運算式會呼叫 ws(istr),然後傳 *this回 。 如需詳細資訊,請參閱ws

第二個和第三個函式可確保其他操作工具,例如 hex,的行為也類似。 其餘的函式是格式化的輸入函式。

函式:

basic_istream& operator>>(
    basic_streambuf<Char_T, Tr>* strbuf);

如果 strbuf 不是 Null 指標,則會擷取專案,並在中 strbuf插入這些專案。 到達檔案結尾時,會停止擷取。 如果插入失敗或擲回例外狀況 (會攔截但不會再次擲回),也會停止,而不會擷取有問題的元素。 如果此函式未擷取任何元素,則會呼叫 setstate(failbit). 在任何情況下,函式會傳 *this回 。 如需詳細資訊,請參閱setstate

函式:

basic_istream& operator>>(bool& val);

藉由呼叫 use_facet< num_get<Char_T, InIt>(getloc).get( InIt(rdbuf), Init(0), *this, getloc, val)來擷取字段,並將它轉換成布爾值。 在這裡, InIt 定義為 istreambuf_iterator<Char_T, Tr>。 函式會傳回 *this

如需詳細資訊,請參閱 use_facetgetloc, getrdbufistreambuf_iterator

每個函式:

basic_istream& operator>>(short& val);
basic_istream& operator>>(unsigned short& val);
basic_istream& operator>>(int& val);
basic_istream& operator>>(unsigned int& val);
basic_istream& operator>>(long& val);
basic_istream& operator>>(unsigned long& val);
basic_istream& operator>>(long long& val);
basic_istream& operator>>(unsigned long long& val);
basic_istream& operator>>(void *& val);

藉由呼叫 use_facet<num_get<Char_T, InIt>(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val)來擷取字段,並將其轉換成數值。 在這裡,InIt定義為 ,並val視需要具有 類型longunsigned longvoid *istreambuf_iterator<Char_T, Tr>

如果轉換的值不能表示為 的 val型別,函式會呼叫 setstate(failbit)。 在任何情況下,函式會傳 *this回 。 如需詳細資訊,請參閱setstate

每個函式:

basic_istream& operator>>(float& val);
basic_istream& operator>>(double& val);
basic_istream& operator>>(long double& val);

藉由呼叫 use_facet<num_get<Char_T, InIt>(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val)來擷取字段,並將其轉換成數值。 在這裡, InIt 定義為 istreambuf_iterator<Char_T, Tr>,並 val 具有 類型 doublelong double 視需要。

如果轉換的值不能表示為 的 val型別,函式會呼叫 setstate(failbit)。 在任何情況下,它都會傳回 *this

範例

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

using namespace std;

ios_base& hex2( ios_base& ib )
{
   ib.unsetf( ios_base::dec );
   ib.setf( ios_base::hex );
   return ib;
}

basic_istream<char, char_traits<char> >& somefunc(basic_istream<char, char_traits<char> > &i)
{
   if ( i == cin )
   {
      cerr << "i is cin" << endl;
   }
   return i;
}

int main( )
{
   int i = 0;
   cin >> somefunc;
   cin >> i;
   cout << i << endl;
   cin >> hex2;
   cin >> i;
   cout << i << endl;
}

basic_istream::operator=

將位於運算子右側的 basic_istream 指派給此物件。 這是一個移動指派,涉及 rvalue 不會留下複本的參考。

basic_istream& operator=(basic_istream&& right);

參數

right
basic_ifstream 物件的 rvalue 參考。

傳回值

傳回 *this

備註

成員運算子會呼叫 swap(right)

basic_istream::peek

傳回要讀取的下一個字元。

int_type peek();

傳回值

要讀取的下一個字元。

備註

未格式化的輸入函式會盡可能擷取專案,就像傳回 rdbuf->sgetc一樣。 否則會傳回 traits_type::eof。 如需詳細資訊,請參閱 sgetceof

範例

// basic_istream_peek.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10], c2;
   cout << "Type 'abcde': ";

   c2 = cin.peek( );
   cin.getline( &c[0], 9 );

   cout << c2 << " " << c << endl;
}
abcde
Type 'abcde': abcde
a abcde

basic_istream::putback

將指定的字元放入資料流。

basic_istream<Char_T, Tr>& putback(
    char_type Ch);

參數

Ch
要放回資料流的字元。

傳回值

數據流 (*this)。

備註

未格式化的輸入函式會盡可能重Ch播 ,就像呼叫 rdbuf->sputbackc一樣。 如果 rdbuf 是 Null 指標,或呼叫 傳 sputbackctraits_type::eof,則函式會呼叫 setstate(badbit)。 在任何情況下,它都會傳回 *this

如需詳細資訊,請參閱rdbuf, sputbackc, eofsetstate.

範例

// basic_istream_putback.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10], c2, c3;

   c2 = cin.get( );
   c3 = cin.get( );
   cin.putback( c2 );
   cin.getline( &c[0], 9 );
   cout << c << endl;
}
qwq

basic_istream::read

從資料流讀取指定的字元數,並將其儲存在陣列中。

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

basic_istream<Char_T, Tr>& read(
    char_type* str,
    streamsize count);

參數

str
要讀取其中字元的陣列。

count
要讀取的字元數。

傳回值

資料流 ( *this)。

備註

未格式化的輸入函式會擷取至 count 專案,並將其儲存在從 開始 str的數位中。 擷取會在檔案結尾提早停止,在此情況下,函式會呼叫 setstate(failbit)。 在任何情況下,它都會傳回 *this。 如需詳細資訊,請參閱setstate

範例

// basic_istream_read.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main()
{
    char c[10];
    int count = 5;

    cout << "Type 'abcde': ";

    // Note: cin::read is potentially unsafe, consider
    // using cin::_Read_s instead.
    cin.read(&c[0], count);
    c[count] = 0;

    cout << c << endl;
}
abcde
Type 'abcde': abcde
abcde

basic_istream::readsome

讀取指定數目的字元值。

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

streamsize readsome(
    char_type* str,
    streamsize count);

參數

str
readsome 要在其中儲存所讀取字元的陣列。

count
要讀取的字元數。

傳回值

實際讀取的字元數, gcount

備註

此未格式化的輸入函式最多會從輸入資料流中擷取 count 個元素,並將其儲存在陣列 str 中。

此函式不會等候輸入。 它會讀取任何可用的資料。

範例

// basic_istream_readsome.cpp
// compile with: /EHsc /W3
#include <iostream>
using namespace std;

int main( )
{
   char c[10];
   int count = 5;

   cout << "Type 'abcdefgh': ";

   // cin.read blocks until user types input.
   // Note: cin::read is potentially unsafe, consider
   // using cin::_Read_s instead.
   cin.read(&c[0], 2);

   // Note: cin::readsome is potentially unsafe, consider
   // using cin::_Readsome_s instead.
   int n = cin.readsome(&c[0], count);  // C4996
   c[n] = 0;
   cout << n << " characters read" << endl;
   cout << c << endl;
}

basic_istream::seekg

移動資料流中的讀取位置。

basic_istream<Char_T, Tr>& seekg(pos_type pos);

basic_istream<Char_T, Tr>& seekg(off_type off, ios_base::seekdir way);

參數

pos
要在其中移動讀取指標的絕對位置。

off
要相對於 way 移動讀取指標的位移。

way
其中 ios_base::seekdir 一個列舉。

傳回值

數據流 (*this)。

備註

第一個成員函式會執行絕對搜尋,第二個成員函式會執行相對搜尋。

注意

請勿對文字檔案使用第二個成員函式,因為標準 C++ 不支援在文字檔案中執行相對搜尋。

如果 failfalse,則第一個成員函式會針對某些pos_type暫存物件newpos呼叫 newpos = rdbuf->pubseekpos(pos)。 如果 failfalse,則第二個函式會呼叫 newpos = rdbuf->pubseekoff( off, way)。 在任一情況下,如果 (off_type)newpos == (off_type)(-1) (定位作業失敗),函式會呼叫 istr.setstate(failbit)。 兩個函式都會傳回 *this

如果 failtrue,則成員函式不會執行任何動作。

如需詳細資訊,請參閱rdbuf, pubseekpos, pubseekoffsetstate.

範例

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

int main ( )
{
   using namespace std;
   ifstream file;
   char c, c1;

   file.open( "basic_istream_seekg.txt" );
   file.seekg(2);   // seek to position 2
   file >> c;
   cout << c << endl;
}

basic_istream::sentry

此巢狀類別描述一個物件,該物件的宣告會建構格式化和未格式化的輸入函式。

class sentry {
   public:
   explicit sentry(
      basic_istream<Char_T, Tr>& _Istr,
      bool _Noskip = false);
   operator bool() const;
   };

備註

如果 _Istr.goodtrue,則建構函式:

  • 如果 _Istr.tie 不是 Null 指標,則呼叫 _Istr.tie->flush

  • 如果 _Istr.flags & skipws 非零值,則有效呼叫 ws(_Istr)

如果有任何這類準備之後, 是 false_Istr.good建構函式會呼叫 _Istr.setstate(failbit)。 在任何情況下,建構函式會將 所 _Istr.good 傳回的值儲存在 中 status。 稍後的 operator bool 呼叫會傳遞這個預存值。

如需詳細資訊,請參閱 goodtieflushwsflagsskipwssetstate

basic_istream::swap

交換兩個 basic_istream 物件的內容。

void swap(basic_istream& right);

參數

right
basic_istream 物件的 lvalue 參考。

備註

成員函式會呼叫 basic_ios::swap(right)。 它也會與 right 交換擷取計數。 如需詳細資訊,請參閱basic_ios::swap

basic_istream::sync

同步處理數據流的相關聯輸入裝置與數據流的緩衝區。

int sync();

傳回值

如果 rdbuf 為 Null 指標,則函式會傳回 -1。 否則,它會呼叫 rdbuf->pubsync。 如果該呼叫傳回 -1,函式會呼叫 setstate(badbit) 並傳回 -1。 否則,此函式會傳回零。 如需詳細資訊,請參閱 pubsyncsetstate

basic_istream::tellg

回報在資料流中目前的讀取位置。

pos_type tellg();

傳回值

在資料流中的目前位置。

備註

如果 failfalse,則成員函式會傳 rdbuf->pubseekoff(0, cur, in)回 。 否則會傳回 pos_type(-1)。 如需詳細資訊,請參閱 rdbufpubseekoff

範例

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

int main()
{
    using namespace std;
    ifstream file;
    char c;
    streamoff i;

    file.open("basic_istream_tellg.txt");
    i = file.tellg();
    file >> c;
    cout << c << " " << i << endl;

    i = file.tellg();
    file >> c;
    cout << c << " " << i << endl;
}

basic_istream::unget

將最近讀取的字元放回資料流。

basic_istream<Char_T, Tr>& unget();

傳回值

數據流 (*this)。

備註

未格式化的輸入函式會盡可能將上一個元素放回數據流中,就像呼叫 rdbuf->sungetc If rdbuf 是 Null 指標,或呼叫 傳回 traits_type::eof,則函式會呼叫 sungetc setstate(badbit)。 在任何情況下,它都會傳回 *this

如需詳細資訊,請參閱sungetceofsetstate。 如需失敗方式 unget 的詳細資訊,請參閱 basic_streambuf::sungetc

範例

// basic_istream_unget.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10], c2;

   cout << "Type 'abc': ";
   c2 = cin.get( );
   cin.unget( );
   cin.getline( &c[0], 9 );
   cout << c << endl;
}
abc
Type 'abc': abc
abc

另請參閱

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