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 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:
n
characters have
been read and discarded if n
!=
numeric_limits<streamsize>::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
.