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)。

示例

请参阅 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
如果在 count 之前遇到该元素,则会导致 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 不是空指针,则提取元素,并将其插入到 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_facetgetlocgetrdbufistreambuf_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 定义为 istreambuf_iterator<Char_T, Tr>,而 val 根据需要具有类型 longunsigned longvoid *

如果转换的值不能表示为 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 是空指针,或者如果对 sputbackc 的调用返回 traits_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++ 不支持在文本文件中进行相对查找。

对于某些 pos_type 临时对象 newpos,如果 failfalse,则第一个成员函数调用 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 不是空指针,则调用 _Istr.tie->flush

  • 如果 _Istr.flags & skipws 为非零,则有效调用 ws(_Istr)

经过任何此类准备工作之后,如果 _Istr.goodfalse,则构造函数调用 _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 是空指针,则该函数将返回 -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 一样。如果 rdbuf 是空指针,或者如果对 sungetc 的调用返回 traits_type::eof,则该函数将调用 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 约定