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_facet
、getloc
, get
、rdbuf
和 istreambuf_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
視需要具有 類型long
、 unsigned long
或 void *
。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
具有 類型 double
或 long 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
。 如需詳細資訊,請參閱 sgetc
和 eof
。
範例
// 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 指標,或呼叫 傳 sputbackc
回 traits_type::eof
,則函式會呼叫 setstate(badbit)
。 在任何情況下,它都會傳回 *this
。
如需詳細資訊,請參閱rdbuf
, sputbackc
, eof
和setstate
.
範例
// 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++ 不支援在文字檔案中執行相對搜尋。
如果 fail
為 false
,則第一個成員函式會針對某些pos_type
暫存物件newpos
呼叫 newpos = rdbuf->pubseekpos(pos)
。 如果 fail
為 false
,則第二個函式會呼叫 newpos = rdbuf->pubseekoff( off, way)
。 在任一情況下,如果 (off_type)newpos == (off_type)(-1)
(定位作業失敗),函式會呼叫 istr.setstate(failbit)
。 兩個函式都會傳回 *this
。
如果 fail
為 true
,則成員函式不會執行任何動作。
如需詳細資訊,請參閱rdbuf
, pubseekpos
, pubseekoff
和setstate
.
範例
// 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.good
為 true
,則建構函式:
如果
_Istr.tie
不是 Null 指標,則呼叫_Istr.tie->flush
。如果
_Istr.flags & skipws
非零值,則有效呼叫ws(_Istr)
。
如果有任何這類準備之後, 是 false
,_Istr.good
建構函式會呼叫 _Istr.setstate(failbit)
。 在任何情況下,建構函式會將 所 _Istr.good
傳回的值儲存在 中 status
。 稍後的 operator bool
呼叫會傳遞這個預存值。
如需詳細資訊,請參閱 good
、tie
、flush
、ws
、flags
、skipws
和 setstate
。
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。 否則,此函式會傳回零。 如需詳細資訊,請參閱 pubsync
和 setstate
。
basic_istream::tellg
回報在資料流中目前的讀取位置。
pos_type tellg();
傳回值
在資料流中的目前位置。
備註
如果 fail
為 false
,則成員函式會傳 rdbuf->pubseekoff(0, cur, in)
回 。 否則會傳回 pos_type(-1)
。 如需詳細資訊,請參閱 rdbuf
和 pubseekoff
。
範例
// 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
。
如需詳細資訊,請參閱sungetc
、eof
及 setstate
。 如需失敗方式 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