Name

basic_istream class template — Base class for input stream

Synopsis

template <typename chT, typename traits = char_traits<chT> >
class basic_istream : virtual public basic_ios<chT,traits>
{
public:
  // Types
  typedef chT char_type;
  typedef typename traits::int_type int_type;
  typedef typename traits::pos_type pos_type;
  typedef typename traits::off_type off_type;
  typedef traits traits_type;
   
  explicit basic_istream(basic_streambuf<chT,traits>* sb);
  virtual ~basic_istream(  );
  class sentry;
  // Formatted input
  basic_istream<chT,traits>& operator>>(basic_istream<chT,traits>&
    (*pf)(basic_istream<chT,traits>&));
  basic_istream<chT,traits>& operator>> (basic_ios<chT,traits>& |
    (*pf)(basic_ios<chT,traits>&));
  basic_istream<chT,traits>& operator>>(ios_base& (*pf)(ios_base&));
  basic_istream<chT,traits>& operator>>(bool& n);
  basic_istream<chT,traits>& operator>>(short& n);
  basic_istream<chT,traits>& operator>>(unsigned short& n);
  basic_istream<chT,traits>& operator>>(int& n);
  basic_istream<chT,traits>& operator>>(unsigned int& n);
  basic_istream<chT,traits>& operator>>(long& n);
  basic_istream<chT,traits>& operator>>(unsigned long& n);
  basic_istream<chT,traits>& operator>>(float& f);
  basic_istream<chT,traits>& operator>>(double& f);
  basic_istream<chT,traits>& operator>>(long double& f);
  basic_istream<chT,traits>& operator>>(void*& p);
  basic_istream<chT,traits>& operator>> (basic_streambuf<char_type,traits>* sb);
  // Unformatted input
  streamsize gcount(  ) const;
  int_type get(  );
  basic_istream<chT,traits>& get(char_type& c);
  basic_istream<chT,traits>& get(char_type* s, streamsize n);
  basic_istream<chT,traits>& get(char_type* s, streamsize n, char_type delim);
  basic_istream<chT,traits>& get(basic_streambuf<char_type,traits>& sb);
  basic_istream<chT,traits>& get(basic_streambuf<char_type,traits>& sb, 
                                 char_type delim);
  basic_istream<chT,traits>& getline(char_type* s, streamsize n);
  basic_istream<chT,traits>& getline(char_type* s, streamsize n, 
                                        char_type delim);
  basic_istream<chT,traits>& ignore (streamsize n = 1, int_type 
                                     delim=traits::eof(  ));
  int_type peek(  );
  basic_istream<chT,traits>& read(char_type* s, streamsize n);
  streamsize readsome(char_type* s, streamsize n);
  basic_istream<chT,traits>& putback(char_type c);
  basic_istream<chT,traits>& unget(  );
  int sync(  );
  pos_type tellg(  );
  basic_istream<chT,traits>& seekg(pos_type);
  basic_istream<chT,traits>& seekg(off_type, ios_base::seekdir);
};

The basic_istream class template is the base for all input streams. It declares members for reading from streams and for managing streams. The act of reading from a stream is also known as extracting from the stream.

All reads go through a stream buffer, which provides the low-level access to the stream data. (See the sbumpc and sgetc functions for basic_streambuf in the <streambuf> header.) If the stream buffer returns traits::eof( ) for an input operation, the stream sets failbit | eofbit in the stream's I/O state. If the buffer object throws an exception, the stream sets badbit.

Before performing an input operation (e.g., operator>> or a get( ) function), the stream constructs a sentry object. If the sentry evaluates to true, the read operation continues. If the read throws an exception, badbit is set. The second (noskipws) argument to the sentry constructor is false for the formatted functions (operator>>) and true for all other input operations. The sentry object is destroyed before the input function returns. See basic_istream::sentry later in this section for more information.

When an input operation throws an exception, the stream sets badbit. If badbit is set in the exceptions( ) mask, the stream does not throw ios_base::failure, but instead rethrows the original exception. If any input operation sets eofbit or failbit, and that bit is set in the exceptions( ) mask, the usual ios_base::failure exception is thrown.

The following are the basic_istream member functions:

explicit basic_istream (basic_streambuf<chT,traits>* sb)

Calls the basic_ios(sb) constructor and initializes gcount( ) to 0.

basic_istream<chT,traits>& operator>> (basic_istream<chT,traits>& (*manip)(basic_istream<chT,traits>&))

Returns manip(*this). See the ws function for an example of such a manipulator.

basic_istream<chT,traits>& operator>> (basic_ios<chT,traits>&(*manip)(basic_ios<chT,traits>&)), basic_istream<chT,traits>& operator>> (ios_base& (*manip)(ios_base&))

Calls manip(*this) and returns *this. See the dec function in <ios> for an example of such a manipulator.

basic_istream<chT,traits>& operator>> (bool& n), basic_istream<chT,traits>& operator>> (short& n), basic_istream<chT,traits>& operator>> (unsigned short& n), basic_istream<chT,traits>& operator>> (int& n), basic_istream<chT,traits>& operator>> (unsigned int& n), basic_istream<chT,traits>& operator>> (long& n), basic_istream<chT,traits>& operator>> (unsigned long& n), basic_istream<chT,traits>& operator>> (float& f), basic_istream<chT,traits>& operator>> (double& f), basic_istream<chT,traits>& operator>> (long double& f), basic_istream<chT,traits>& operator>> (void*& p)

Reads a formatted item from the stream. These formatted input functions use the num_get facet of the stream's imbued locale as shown in Example 13-16. See the <locale> header for information about num_get and locales.

basic_istream<chT,traits>& operator>> (basic_streambuf<char_type,traits>* sb)

Copies input to the stream buffer sb. If sb is a null pointer, the stream sets failbit and returns immediately. Otherwise, the function copies characters from the input stream to sb until it reaches the end of the input stream, writing to sb fails, or an exception is caught. If no characters are copied to sb, failbit is set. The return value is *this.

streamsize gcount ( ) const

Returns the number of characters extracted by the most recent call to an unformatted member function (get, getline, ignore, peek, putback, read, readsome, and unget).

int_type get ( )

Reads a single character and returns it. If no character is available, the function sets failbit and returns traits::eof( ).

basic_istream<chT,traits>& get (char_type& c)

Reads a single character and stores it in c. If no character is available, the function sets failbit and does not modify c. The return value is *this.

basic_istream<chT,traits>& get (char_type* s, streamsize n)

Returns get(s, n, widen('\n')).

basic_istream<chT,traits>& get (char_type* s, streamsize n, char_type delim)

Reads up to n - 1 characters into the character array that s points to. Reading stops at the end-of-file (which sets eofbit) or when the next character would be delim (but the delimiter character is not read from the buffer). If no characters are stored in s, failbit is set.

A null character is always appended to the end of s. The return value is *this.

basic_istream<chT,traits>& get (basic_streambuf<char_type,traits>& sb)

Returns get(sb, widen('\n')).

basic_istream<chT,traits>& get (basic_streambuf<char_type,traits>& sb, char_type delim)

Copies characters to the output buffer sb. Copying stops when an end-of-file is reached, when writing to sb fails, or when the next character to read would be delim (the delimiter is not read from the input buffer). If no characters are copied to sb, failbit is set.

basic_istream<chT,traits>& getline (char_type* s, streamsize n)

Returns getline(s, n, widen('\n')).

basic_istream<chT,traits>& getline (char_type* s, streamsize n, char_type delim)

Reads up to n - 1 characters into the character array that s points to. Reading stops at the end-of-file (which sets eofbit) or when delim is read (the delimiter character is read from the buffer but not stored in s).

If no characters are read from the stream, failbit is set. If exactly n - 1 characters are read before reaching the end-of-file, eofbit is set; otherwise, if the limit of n - 1 characters is reached before reading a delimiter, failbit is set.

A null character is always appended to the end of s. The return value is *this.

basic_istream<chT,traits>& ignore (streamsize n=1, int_type delim=traits::eof( ))

Reads characters from the input buffer and discards them. The operation stops when one of the following occurs:

The return value is *this.

int_type peek ( )

Looks ahead to the next character in the input stream. If good( ) returns true, rdbuf( )->sgetc( ) is returned; otherwise, traits::eof( ) is returned. No characters are extracted from the stream, so a subsequent call to gcount( ) returns 0.

basic_istream<chT,traits>& read (char_type* s, streamsize n)

Reads up to n characters and stores them in the array that s points to. Before reading anything, if good( ) is false, failbit is set, and nothing is read. Otherwise, if end-of-file is reached before reading n characters, eofbit and failbit are set. A null character is not appended to s. The return value is *this.

streamsize readsome (char_type* s, streamsize n)

Tries to read as many immediately available characters as possible into the array that s points to. If good( ) is false before reading, failbit is set, and readsome returns immediately. Otherwise, readsome calls rdbuf( )->in_avail( ) and does one of the following:

A null character is not appended to s. The return value is the number of characters stored in s.

basic_istream<chT,traits>& putback (char_type c)

Tries to push back the character c so it will be the next character read from the input stream. If good( ) is false, failbit is set and putback returns. Otherwise, if rdbuf( ) is not null, putback calls rdbuf( )->sputbackc(c). If rdbuf( ) is null or sputbackc returns traits::eof( ), badbit is set. The return value is *this. A subsequent call to gcount( ) returns 0.

basic_istream<chT,traits>& seekg (pos_type pos), basic_istream<chT,traits>& seekg (off_type off, ios_base::seekdir dir)

Tries to seek to a new position in the stream. The first form specifies the position explicitly; the second form specifies the new position as an offset from a known position (beginning of file, current position, or end-of-file). If fail( ) is false, seekg calls rdbuf( )->pubseekoff(pos) or rdbuf( )->pubseekoff(off, dir). The return value is *this.

int sync ( )

Synchronizes the stream buffer. If rdbuf( ) is null, sync returns -1; otherwise, sync calls rdbuf( )->pubsync( ). If pubsync returns -1, badbit is set, and sync returns -1. Otherwise, sync returns 0.

pos_type tellg ( )

Returns the current position in the stream. If fail( ) is true, the return value is pos_type(-1); otherwise, the return value is rdbuf( )->pubseekoff(0, ios_base::cur, ios_base::in).

basic_istream<chT,traits>& unget ( )

Tries to push back the last input character. If good( ) is false, failbit is set and unget returns. Otherwise, if rdbuf( ) is not null, putback calls rdbuf( )->sungetc( ). If rdbuf( ) is null or sungetc returns traits::eof( ), badbit is set. The return value is *this. A subsequent call to gcount( ) returns 0.