<istream>
// DECLARATIONS class istream; // EXTRACTORS istream& operator>>(istream& is, char *s); istream& operator>>(istream& is, char& c); istream& operator>>(istream& is, signed char *s); istream& operator>>(istream& is, signed char& c); istream& operator>>(istream& is, unsigned char *s); istream& operator>>(istream& is, unsigned char& c); // MANIPULATORS istream& ws(istream& is); // END OF DECLARATIONS
Include the iostreams
standard header <istream>
to define class
istream
,
which mediates extractions for the iostreams.
The header also defines a related
manipulator.
(This header is typically included for you by another
of the iostreams headers. You seldom have occasion to include it
directly.)
istream
istream
· gcount
· get
· getline
· ignore
· ipfx
· isfx
· operator>>
· peek
· putback
· read
· readsome
· seekg
· sentry
· sync
· tellg
· unget
class istream : public ios { public: explicit istream(streambuf *sb); class sentry; virtual ~istream(); bool ipfx(bool noskip = false); void isfx(); istream& operator>>( istream& (*pf)(istream&)); istream& operator>>( ios_base& (*pf)(ios_base&)); istream& operator>>( ios& (*pf)(ios&)); istream& operator>>( streambuf *sb); istream& operator>>(bool& n); istream& operator>>(short& n); istream& operator>>(unsigned short& n); istream& operator>>(int& n); istream& operator>>(unsigned int& n); istream& operator>>(long& n); istream& operator>>(unsigned long& n); istream& operator>>(void *& n); istream& operator>>(float& n); istream& operator>>(double& n); istream& operator>>(long double& n); streamsize gcount() const; int_type get(); istream& get(char_type& c); istream& get(char_type *s, streamsize n); istream& get(char_type *s, streamsize n, char_type delim); istream& get(streambuf *sb); istream& get(streambuf *sb, char_type delim); istream& getline(char_type *s, streamsize n); istream& getline(char_type *s, streamsize n, char_type delim); istream& ignore(streamsize n = 1, int_type delim = traits_type::eof()); int_type peek(); istream& read(char_type *s, streamsize n); streamsize readsome(char_type *s, streamsize n); istream& putback(char_type c); istream& unget(); istream& tellg(); istream& seekg(pos_type pos); istream& seekg(off_type off, ios_base::seek_dir way); int sync(); };
The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer
with elements of type char, also known as
char_type
, whose
character traits are determined by the
class char_traits
,
also known as
traits_type
.
Most of the member functions that overload
operator>>
are formatted input functions.
They follow the pattern:
iostate state = goodbit; const sentry ok(*this); if (ok) {try {extract elements and convert accumulate flags in state store a successful conversion} catch (...) {if (exceptions() & badbit) throw; setstate(badbit); }} setstate(state); return (*this);
Many other member functions are unformatted input functions. They follow the pattern:
iostate state = goodbit; count = 0; // the value returned by gcount const sentry ok(*this, true); if (ok) {try {extract elements and deliver count extracted elements in count accumulate flags in state} catch (...) {if (rdstate() & badbit) throw; setstate(badbit); }} setstate(state);
Both groups of functions call
setstate(eofbit)
if they encounter end-of-file while extracting elements.
An object of class istream
stores:
ios
count
in the code aboveistream::istream
explicit istream(streambuf *sb);
The constructor initializes the base class by calling
init(sb)
.
It also stores zero in the
extraction count.
istream::gcount
streamsize gcount() const;
The member function returns the extraction count.
istream::get
int_type get(); istream& get(char_type& c); istream& get(char_type *s, streamsize n); istream& get(char_type *s, streamsize n, char_type delim); istream& get(streambuf *sb); istream& get(streambuf *sb, char_type delim);
The first of these
unformatted input functions
extracts an element, if possible, as if by returning
rdbuf()->sbumpc()
.
Otherwise, it returns
traits_type::eof()
.
If the function extracts no element, it calls
setstate(failbit)
.
The second function extracts the
int_type
element
x
the same way. If x
compares equal to
traits_type::eof(x)
,
the function calls
setstate(failbit)
.
Otherwise, it stores
traits_type::to_char_type(x)
in c
. The function returns *this
.
The third function returns get(s, n, widen('\n'))
.
The fourth function extracts up to n - 1
elements
and stores them in the array beginning at s
. It always stores
char_type()
after
any extracted elements it stores. Extraction stops early on end-of-file or
on an element that compares equal to delim
(which is
not extracted). If the function extracts no elements, it calls
setstate(failbit)
.
In any case, it returns *this
.
The fifth function returns get(sb, widen('\n'))
.
The sixth function extracts elements and inserts them in
sb
. Extraction stops on end-of-file or on an element
that compares equal to delim
(which is not extracted).
It also stops, without extracting the element in question,
if an insertion fails or throws an exception (which is caught
but not rethrown). If the function extracts no elements, it calls
setstate(failbit)
.
In any case, the function returns *this
.
istream::getline
istream& getline(char_type *s, streamsize n); istream& getline(char_type *s, streamsize n, char_type delim);
The first of these
unformatted input functions
returns getline(s, n, widen('\n'))
.
The second function extracts up to n - 1
elements
and stores them in the array beginning at s
. It always stores
char_type()
after
any extracted elements it stores. In order of testing, extraction stops:
delim
, in which case the element is neither put back nor
appended to the controlled sequencen - 1
elementsIf the function extracts no elements, it calls
setstate(failbit)
.
In any case, it returns *this
.
istream::ignore
istream& ignore(streamsize n = 1, int_type delim = traits_type::eof());
The unformatted input function
extracts up to n
elements and discards them.
If n
equals
INT_MAX
,
however, it is taken as arbitrarily large.
Extraction stops early on end-of-file or
on an element x
such that
traits_type::to_int_type(x)
compares equal to delim
(which is
also extracted).
The function returns *this
.
istream::ipfx
bool ipfx(bool noskip = false);
The member function prepares for
formatted or
unformatted input.
If good()
is true, the function:
tie->
flush()
if tie()
is not a null pointerws(*this)
if
flags() &
skipws
is nonzeroIf, after any such preparation,
good()
is false, the function calls
setstate(failbit)
.
In any case, the function returns good()
.
You should not call ipfx
directly.
It is called as needed by an object of class
sentry
.
istream::isfx
void isfx();
The member function has no official duties, but an implementation
may depend on a call to isfx
by a
formatted or
unformatted input
function to tidy up after an extraction.
You should not call isfx
directly.
It is called as needed by an object of class
sentry
.
istream::operator>>
istream& operator>>( istream& (*pf)(istream&)); istream& operator>>( ios_base& (*pf)(ios_base&)); istream& operator>>( ios& (*pf)(ios&)); istream& operator>>( streambuf *sb); istream& operator>>(bool& n); istream& operator>>(short& n); istream& operator>>(unsigned short& n); istream& operator>>(int& n); istream& operator>>(unsigned int& n); istream& operator>>(long& n); istream& operator>>(unsigned long& n); istream& operator>>(void *& n); istream& operator>>(float& n); istream& operator>>(double& n); istream& operator>>(long double& n);
The first member function ensures that an expression of the
form istr >> ws
calls
ws(istr)
, then returns *this
.
The second and third functions ensure that other
manipulators,
such as hex
behave
similarly. The remaining functions constitute the
formatted input functions.
The function:
istream& operator>>( streambuf *sb);
extracts elements, if sb
is not a null pointer,
and inserts them in sb
. Extraction stops on end-of-file.
It also stops, without extracting the element in question,
if an insertion fails or throws an exception (which is caught
but not rethrown).
If the function extracts no elements, it calls
setstate(failbit)
.
In any case, the function returns *this
.
The function:
istream& operator>>(bool& n);
extracts a field and converts it to a boolean value.
The function endeavors to match a complete, nonempty
boolean input field.
If successful it converts
the boolean input field to a value of type bool
and stores that value in n
.
A boolean input field takes one of two forms.
If flags() &
ios_base::boolalpha
is false, it is the same as an
integer input field, except that the
converted value must be either 0 (for false) or 1 (for true).
Otherwise, the sequence must match either
false
(for false), or
true
(for true).
The function returns *this
.
The functions:
istream& operator>>(short& n); istream& operator>>(unsigned short& n); istream& operator>>(int& n); istream& operator>>(unsigned int& n); istream& operator>>(long& n); istream& operator>>(unsigned long& n); istream& operator>>(void *& n);
each extract a field and convert it to a numeric value.
Each function endeavors to match a complete, nonempty
integer input field.
If successful, it stores the result in n
.
Otherwise, the function stores nothing in n
and calls
setstate(ios_base::failbit)
.
If the function encounters end of file, it calls
setstate(ios_base::eofbit)
.
The integer input field is converted by the same rules used by the scan functions for matching and converting a series of char elements from a file. The equivalent scan conversion specification is determined as follows:
flags() &
ios_base::basefield ==
ios_base::oct
, the
conversion specification is lo
.flags() & ios_base::basefield ==
ios_base::hex
, the
conversion specification is lx
.flags() & ios_base::basefield == 0
, the
conversion specification is li
.ld
if n
has a signed type, lu
if n
has an unsigned type, or p
if n
has type
void *
.If the converted value cannot
be represented as the type of n
, the function calls
setstate(failbit)
.
In any case, the function returns *this
.
The functions:
istream& operator>>(float& n); istream& operator>>(double& n); istream& operator>>(long double& n);
each extract a field and convert it to a numeric value.
Each function endeavors to match a complete, nonempty
A period (.
) separates the integer digits from the
fraction digits.
The equivalent scan conversion specifier is f
if n
has type float, lf
if n
has type double, or Lf
if n
has type
long double.
If the converted value cannot
be represented as the type of n
, the function calls
setstate(failbit)
.
In any case, it returns *this
.
istream::peek
int_type peek();
The unformatted input function
extracts an element, if possible, as if by returning
rdbuf()->sgetc()
.
Otherwise, it returns
traits_type::eof()
.
istream::putback
istream& putback(char_type c);
The unformatted input function
puts back c
, if possible, as if by calling
rdbuf()->sputbackc()
.
If rdbuf()
is a null pointer, or if the call to sputbackc
returns
traits_type::eof()
,
the function calls
setstate(badbit)
.
In any case, it returns *this
.
istream::read
istream& read(char_type *s, streamsize n);
The unformatted input function
extracts up to n
elements
and stores them in the array beginning at s
.
Extraction stops early on end-of-file, in which case the function calls
setstate(failbit)
.
In any case, it returns *this
.
istream::readsome
streamsize readsome(char_type *s, streamsize n);
The member function extracts up to n
elements
and stores them in the array beginning at s
.
If rdbuf()
is
a null pointer, the function calls
setstate(failbit)
.
Otherwise, it assigns the value of
rdbuf()->in_avail()
to N
. if N < 0
, the function calls
setstate(eofbit)
.
Otherwise, it replaces the value stored in N
with
the smaller of n
and N
, then calls
read(s, N)
.
In any case, the function returns
gcount()
.
istream::seekg
istream& seekg(pos_type pos); istream& seekg(off_type off, ios_base::seek_dir way);
If fail()
is false,
the first member function calls
rdbuf()->
pubseekpos(pos)
.
If fail()
is false, the second function calls
rdbuf()->
pubseekoff(off,
way)
. Both functions return *this
.
istream::sentry
class sentry { public: explicit sentry(istream<E, T>& is, bool noskip = false); operator bool() const; };
The nested class describes an object whose declaration structures the
formatted input functions
and the
unformatted input functions.
The constructor effectively calls
is.ipfx(noskip)
and
stores the return value. operator bool()
delivers this
return value. The destructor effectively calls
is.isfx()
.
istream::sync
int sync();
If rdbuf()
is
a null pointer, the function returns -1. Otherwise, it calls
rdbuf()->pubsync()
.
If that returns -1, the function calls
setstate(badbit)
and returns -1. Otherwise, the function returns zero.
istream::tellg
istream& tellg();
If fail()
is false,
the member function returns
rdbuf()->
pubseekoff(0,
cur,
in)
.
Otherwise, it returns
streampos(-1)
.
istream::unget
istream& unget();
The unformatted input function
puts back the previous element in the stream, if possible, as if by calling
rdbuf()->sungetc()
.
If rdbuf()
is a null pointer, or if the call to sungetc
returns
traits_type::eof()
,
the function calls
setstate(badbit)
.
In any case, it returns *this
.
operator>>
istream& operator>>(istream& is, char *s); istream& operator>>(istream& is, char& c); istream& operator>>(istream& is, signed char *s); istream& operator>>(istream& is, signed char& c); istream& operator>>(istream& is, unsigned char *s); istream& operator>>(istream is, unsigned char& c);
The function:
istream& operator>>(istream& is, char *s);
extracts up to n - 1
elements
and stores them in the array beginning at s
.
If is.width()
is greater
than zero, n
is is.width()
; otherwise it is
the largest array of char that can be declared.
The function always stores
char(0)
after
any extracted elements it stores. Extraction stops early on end-of-file
or on any element (which is not extracted) that would be discarded by
ws
.
If the function extracts no elements, it calls
is.setstate(failbit)
.
In any case, it calls is.width(0)
and
returns is
.
The function:
istream& operator>>(istream& is, char& c);
extracts an element, if possible, and stores it in c
.
Otherwise, it calls
is.setstate(failbit)
.
In any case, it returns is
.
The function:
istream& operator>>(istream& is, signed char *s);
returns is >> (char *)s
.
The function:
istream& operator>>(istream& is, signed char& c);
returns is >> (char&)c
.
The function:
istream& operator>>(istream& is, unsigned char *s);
returns is >> (char *)s
.
The function:
istream& operator>>(istream& is, unsigned char& c);
returns is >> (char&)c
.
ws
istream& ws(istream& is);
The manipulator extracts and discards any elements
x
for which
isspace(x)
is true.
The function calls
setstate(eofbit)
if it encounters end-of-file while extracting elements.
It returns is
.
See also the Table of Contents and the Index.
Copyright © 1992-1996 by P.J. Plauger. All rights reserved.