13.30 <istream>

The <istream> header declares the input stream classes, templates, and an input manipulator.

istream is declared in <istream>, and ostream is declared in <ostream>, but iostream is declared in <istream>, not <iostream>.

See <fstream> for derived-class templates that read from files and <sstream> for derived-class templates that read from strings. See <ios> for the base-class declarations. Refer to Chapter 9 for general information about I/O.

template <typename charT, typename traits = char_traits<charT> >
class basic_iostream : public basic_istream<charT,traits>, 
                        public basic_ostream<charT,traits>
{
public:
  explicit basic_iostream(basic_streambuf<charT,traits>* sb);
  virtual ~basic_iostream(  );
};

The basic_iostream class template represents a stream that can perform input and output. (For details, see its base class templates, basic_istream in this section and basic_ostream in <ostream>.) Note that the two base-class templates share a common stream buffer, sb. Note also that basic_istream and basic_ostream inherit virtually from basic_ios; basic_iostream inherits a single instance of the formatting flags, iostate, and so on.

See Also

basic_istream class template, iostream class, wiostream class, basic_iostream in <ios>, basic_ostream in <ostream>

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.

Example 13-16. Using the num_get facet to format input

typedef
    std::num_get<char_type,
      std::istreambuf_iterator<char_type, traits_type> >
  numget;
std::ios_base::iostate err = 0;
std::use_facet<numget>(getloc(  )).(*this, 0, *this, err, val);
this->setstate(err);

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:

• n characters have been read and discarded if n != numeric_limits<int>::max.

• End-of-file is reached, in which case eofbit is set.

• delim is read if delim != traits::eof( ).

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:

• in_avail( ) == -1: eofbit is set and no characters are read

• in_avail( ) == 0: no characters are read

• in_avail( ) > 0: min(in_avail( ), n) characters are read into s

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.

See Also

istream class, wistream class

template <typename chT, typename traits=char_traits<chT> >
class basic_istream<chT,traits>::sentry{
  public: explicit sentry(basic_istream<chT,traits>& stream, 
                          bool noskipws = false);
  ~sentry(  );
  operator bool(  ) const;
private:
  sentry(const sentry&);            // Not defined
  sentry& operator=(const sentry&); // Not defined
};

A basic_istream object constructs a temporary sentry object prior to each input operation. The sentry object is destroyed when the input operation finishes and the function returns. The sentry manages tied streams and is responsible for skipping whitespace prior to a formatted read.

The stream passes itself and a flag to the sentry's constructor. Formatted reads (operator>>) use false for the second argument; unformatted reads (get, getline, etc.) use true.

If stream.good( ) is true, the sentry first flushes any tied stream. That is, if stream.tie( ) is not null, the sentry calls stream.tie( )->flush( ). This ensures that prompts and similar output appears before the input is requested. Then, if the noskipws argument is false, and if the skipws bit is not set in the stream's formatting flags ((ios_base::skipws & stream.fmtflags( )) == 0), the sentry's constructor reads and discards whitespace characters. The sentry uses code similar to that shown in Example 13-17.

Example

Example 13-17. Skipping whitespace in an input sentry

const std::ctype<char_type>& ctype =
  std::use_facet<ctype<char_type> >(stream.getloc(  ));
int_type c;
while ((c = stream.rdbuf(  )->snextc(  )) != traits::eof(  ))
  if (ctype.is(ctype.space,c) == 0) {
    // Put back the non-space character.
    stream.rdbuf(  )->sputbackc(c);
    break;
  }

If anything goes wrong, the sentry calls stream.setstate(failbit). The sentry's operator bool( ) returns true if stream.good( ) is true, and false otherwise.

See Also

basic_istream class template, basic_ostream::sentry in <ostream>

typedef basic_iostream<char> iostream;

The iostream class specializes basic_iostream for the char type.

See Also

basic_iostream class template, istream class, wiostream class, ostream in <ostream>

typedef basic_istream<char> istream;

The istream class specializes basic_istream for the char type.

See Also

basic_istream class template, iostream class, wistream class, ostream in <ostream>

template<typename charT, typename traits>
  basic_istream<charT,traits>& operator>>
   (basic_istream<charT,traits>& stream, charT& c);
   
template<typename traits> basic_istream<char,traits>&
  operator>>(basic_istream<char,traits>& stream, unsigned char& c);
template<typename traits> basic_istream<char,traits>&
  operator>>(basic_istream<char,traits>& stream, signed char& c);

The operator>> function reads a character from an input stream using the rules for a formatted read (that is, a sentry object is constructed and initial whitespace is skipped). The character is stored in c. If no character is available, failbit is set. The return value is stream.

Note that the first form of operator>> reads the stream's character type. If the stream's character type is char, the second and third forms read signed char and unsigned char.

See Also

basic_istream class template

template<typename charT, typename traits>
  basic_istream<charT,traits>& operator>>
   (basic_istream<charT,traits>& stream, charT* str);
   
template<typename traits> basic_istream<char,traits>&
  operator>>(basic_istream<char,traits>& stream, unsigned char* str);
template<typename traits> basic_istream<char,traits>&
  operator>>(basic_istream<char,traits>& stream, signed char* str);

The operator>> function reads characters from stream into str. As with any formatted input, a sentry object is created and initial whitespace is skipped. Characters are then read from the stream into str until an end-of-file is reached or the next character read would be a whitespace character (the space is not read from the stream).

To limit the number of characters read (always a good idea), set the stream's width to n. At most, n - 1 characters will be read into s. The function resets the width to 0 after reading the stream. A null character is always appended to the end of the string.

If no characters are read from the stream, failbit is set.

Note that the first form of operator>> reads with the stream's character type. If the stream's character type is char, the second and third forms read signed char and unsigned char.

See Also

basic_istream class template

typedef basic_iostream<wchar_t> wiostream;

The wiostream class specializes basic_iostream for the wchar_t type.

See Also

basic_iostream class template, iostream class, wistream class, wostream in <ostream>

typedef basic_istream<wchar_t> wistream;

The wistream class specializes basic_istream for the wchar_t type.

See Also

basic_istream class template, istream class, wiostream class, wostream in <ostream>

template <class charT, class traits>
  basic_istream<charT,traits>& ws(basic_istream<charT,traits>& stream);

The ws function is an input stream manipulator that skips whitespace characters in stream using the same technique as basic_istream::sentry. If the manipulator reaches the end-of-file, it sets eofbit, but not failbit.

Example

Suppose you want to read a line of text by calling getline, but you also want to skip whitespace at the beginning of the line. (Because getline is an unformatted input function, it does not automatically skip whitespace.) The following example shows one way to skip whitespace and read the line using ws:

char buffer[BUFSIZ];
 . . . 
in >> ws;
in.getline(buffer, sizeof(buffer));

See Also

basic_istream class template, basic_istream::sentry class template