`basic_istream` 类

项目
04/03/2023

描述一个对象，它控制从具有类型为 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;
}

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;
}

`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;
}

`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_facet、getlocget、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 定义为 istreambuf_iterator<Char_T, Tr>，而 val 根据需要具有类型 long、unsigned long 或 void *。

如果转换的值不能表示为 val 类型，则函数调用 setstate(failbit)。不管怎样，该函数均将返回 *this。有关详细信息，请参阅 setstate。

每个函数：

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

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

对于某些 pos_type 临时对象 newpos，如果 fail 为 false，则第一个成员函数调用 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 不是空指针，则调用 _Istr.tie->flush。
如果 _Istr.flags & skipws 为非零，则有效调用 ws(_Istr)。

经过任何此类准备工作之后，如果 _Istr.good 为 false，则构造函数调用 _Istr.setstate(failbit)。不管怎样，构造函数将 _Istr.good 返回的值存储在 status 中。稍后对 operator bool 的调用可提供此存储值。

有关更多信息，请参阅 good、tieflushws、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 是空指针，则该函数将返回 -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 一样。如果 rdbuf 是空指针，或者如果对 sungetc 的调用返回 traits_type::eof，则该函数将调用 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

另请参阅

C++ 标准库中的线程安全
 iostream 编程
 iostreams 约定

通过

basic_istream 类

语法

备注

示例

构造函数

成员函数

运算符

要求

basic_istream::basic_istream

参数

备注

示例

basic_istream::gcount

返回值

备注

示例

basic_istream::get

参数

返回值

备注

示例

basic_istream::getline

参数

返回值

备注

示例

basic_istream::ignore

参数

返回值

备注

示例

basic\_istream::operator>>

参数

返回值

注解

示例

basic_istream::operator=

参数

返回值

注解

basic_istream::peek

返回值

备注

示例

basic_istream::putback

参数

返回值

备注

示例

basic_istream::read

参数

返回值

注解

示例

basic_istream::readsome

参数

返回值

备注

示例

basic_istream::seekg

参数

返回值

注解

示例

basic_istream::sentry

注解

basic_istream::swap

参数

备注

basic_istream::sync

返回值

basic_istream::tellg

返回值

备注

示例

basic_istream::unget

返回值

备注

示例

`basic_istream` 类

`basic_istream::basic_istream`

`basic_istream::gcount`

`basic_istream::get`

`basic_istream::getline`

`basic_istream::ignore`

`basic\_istream::operator>>`

`basic_istream::operator=`

`basic_istream::peek`

`basic_istream::putback`

`basic_istream::read`

`basic_istream::readsome`

`basic_istream::seekg`

`basic_istream::sentry`

`basic_istream::swap`

`basic_istream::sync`

`basic_istream::tellg`

`basic_istream::unget`