Draft 2002-08-12

<istream>

The <istream> header declares the input stream classes and an input manipulator. It also declares stream classes for combined input and output. (Note that istream is declared in <istream>, and ostream is declared in <ostream>, but iostream is declared in <istream> not <iostream>.)

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

basic_iostream class template

Base class for input and output stream

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 classes, basic_istream and basic_ostream, in this section. Note that the two base classes share a common stream buffer, sb. Note also that basic_istream and basic_ostream inherit virtually from basic_ios, so 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>

basic_istream class template

Base class for input stream

template <typename chT, typename traits = char_traits<chT> >
class basic_istream : virtual public basic_ios<chT,traits>
{
public:
  // Types (inherited from basic_ios):
  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 the eofbit in the I/O state. If the buffer object throws an exception, the stream sets badbit.

Before performing an input operation (e.g., operator>> or get() function), the stream constructs a sentry object. if the sentry returns 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 destructed 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.

Following are the basic_istream member functions:

explicit basic_istream (basic_streambuf<chT,traits>* sb)
The constructor calls the basic_ios(sb) constructor and initializes gcount() to zero.
basic_istream<chT,traits>& operator>> (basic_istream<chT,traits>& (*pf)(basic_istream<chT,traits>&))
The operator>> function returns pf(*this) and returns *this. See the ws function for an example of such a manipulator.
basic_istream<chT,traits>& operator>> (basic_ios<chT,traits>& (*pf)(basic_ios<chT,traits>&))
basic_istream<chT,traits>& operator>> (ios_base& (*pf)(ios_base&))
The operator>> function calls pf(*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)
These formatted input functions use the num_get facet of the stream's imbued locale as shown in Example 13-18. See the <locale> header for information about num_get and locales.

Example 13-18: 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)
The operator>> function copies input to the stream buffer sb. If sb is a null pointer, the stream sets failbit and returns *this. Otherwise, the function copies characters from the input stream to sb until reaching the end of the input stream, or writing to sb fails, or an exception is caught. If no characters are copied to sb, failbit is set.
streamsize gcount () const
The gcount function returns the number of characters read by the most recent call to an unformatted member function (get, getline, ignore, read, etc.).
int_type get ()
The get function 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)
The get function 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)
The get function returns get(s, n, widen('\n')).
basic_istream<chT,traits>& get (char_type* s, streamsize n, char_type delim)
The get function 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)
The get function returns get(sb, widen('\n')).
basic_istream<chT,traits>& get (basic_streambuf<char_type,traits>& sb, char_type delim)
The get function copies characters to the output buffer sb. Copying stops upon reaching an end of file, 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 not characters are copied to sb, failbit is set.
basic_istream<chT,traits>& getline (char_type* s, streamsize n)
The getline function returns getline(s, n, widen('\n')).
basic_istream<chT,traits>& getline (char_type* s, streamsize n, char_type delim)
The getline function 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 stored in s, 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())
The ignore function reads characters from the input buffer and discards them. The operation stops when the first of the following occurs:
The return value is *this.
int_type peek ()
The peek function peeks ahead to the next character in the input stream. If good() returns true, rdbuf()->sgetc() is returned; otherwise traits::eof() is returned.
basic_istream<chT,traits>& read (char_type* s, streamsize n)
The read function 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 is set and failbit is set. A null character is not appended to s. The return value is *this.
streamsize readsome (char_type* s, streamsize n)
The readsome function tries to read as many characters as are immediately available into the array that s points to. Before reading, if good() is false, 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)
The putback function 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.
basic_istream<chT,traits>& seekg (pos_type pos)
basic_istream<chT,traits>& seekg (off_type off, ios_base::seekdir dir)
The seekg function tries to seek to a new position in the stream. If fail() is false seekg calls rdbuf()->pubseekoff(pos) or rdbuf()->pubseekoff(off, dir). The return value is *this.
int sync ()
The sync function 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 ()
The tellg function 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 ()
The ungetc function 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.

See Also

istream class, wistream class

basic_istream::sentry class

Sentry class for input streams

template <typename chT, typename traits=char_traits<chT> >
class basic_istream<chT,traits>::sentry
{
  typedef traits traits_type;
  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 destructed when the input operation finishes and the function returns. The sentry manages tied streams and is responsible for skipping white space 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 prompts and similar output appear 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 white space characters. The sentry uses code similar to that shown in Example 13-19.

Example 13-19: Skipping white space 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 bool operator() returns true if stream.good() is true and false otherwise.

See Also

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

iostream class

Narrow input and output stream

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>

istream class

Input stream

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>

operator>>

Input operator

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 white space is skipped). The character is stored in c. If no character is available, failbit is set. The return value is stream.

Note that operator>> works with the stream's character type. If the stream's character type is char, additional overloaded functions work with signed char and unsigned char.

See Also

basic_istream class template

operator>>

Input operator

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 white space 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 white space 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 zero 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 operator>> works with the stream's character type. If the stream's character type is char, additional overloaded functions work with signed char and unsigned char.

See Also

basic_istream class template

wiostream class

Wide input and output stream

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>

wistream class

Wide input stream

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>

ws function

Skip white space manipulator

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 white space characters in stream, using the same technique as basic_istream::sentry. If the manipulator reaches the end of file, it self eofbit, but not failbit.

For example, suppose you want to read a line of text by calling getline, but you also want to skip white space at the beginning of the line. (Because getline is an unformatted input function, it does not automatically skip white space.) Example 13-20 is one way to read the line.

Example 13-20: Reading a line of text after white space.

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

See Also

basic_istream class template, basic_istream::sentry class template