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.
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.
basic_istream class template, iostream class, wiostream class, basic_iostream in <ios>, basic_ostream in <ostream>
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)
basic_ios(sb)
constructor and initializes gcount()
to zero.basic_istream<chT,traits>&
operator>>
(basic_istream<chT,traits>& (*pf)(basic_istream<chT,traits>&))
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&))
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)
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)
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
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
()
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)
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)
get
function returns get(s,
n
, widen('\n'))
.basic_istream<chT,traits>&
get
(char_type* s, streamsize n, char_type delim)
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.s
. The return value is *this
.basic_istream<chT,traits>&
get
(basic_streambuf<char_type,traits>& sb)
get
function returns get(sb,
widen('\n'))
.basic_istream<chT,traits>&
get
(basic_streambuf<char_type,traits>& sb, char_type delim)
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)
getline
function returns getline(s,
n,
widen('\n'))
.basic_istream<chT,traits>&
getline
(char_type* s, streamsize n, char_type delim)
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
).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.s
. The return value is *this
.basic_istream<chT,traits>&
ignore
(streamsize n = 1, int_type delim=traits::eof())
ignore
function reads characters from the input buffer and discards them. The operation stops when the first of the following occurs:n
characters have been read and discarded, if n
!=
numeric_limits<int>::max
;delim
is read, if delim
!=
traits::eof()
.int_type
peek
()
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)
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)
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: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
.s
. The return value is the number of characters stored in s
.basic_istream<chT,traits>&
putback
(char_type c)
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)
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
()
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
()
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
()
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
.istream class, wistream 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.
basic_istream class template, basic_ostream::sentry in <ostream>
Narrow input and output stream
typedef basic_iostream<char> iostream;
The iostream
class specializes basic_iostream
for the char
type.
basic_iostream class template, istream class, wiostream class, ostream in <ostream>
Input stream
typedef basic_istream<char> istream;
The istream
class specializes basic_istream
for the char
type.
basic_istream class template, iostream class, wistream class, ostream in <ostream>
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
.
basic_istream class template
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
.
basic_istream class template
Wide input and output stream
typedef basic_iostream<wchar_t> wiostream;
The wiostream
class specializes basic_iostream
for the wchar_t
type.
basic_iostream class template, iostream class, wistream class, wostream in <ostream>
Wide input stream
typedef basic_istream<wchar_t> wistream;
The wistream
class specializes basic_istream
for the wchar_t
type.
basic_istream class template, istream class, wiostream class, wostream in <ostream>
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));
basic_istream class template, basic_istream::sentry class template