<istream>namespace std {
template<class E, class T = char_traits<E> >
class basic_istream;
typedef basic_istream<char, char_traits<char> >
istream;
typedef basic_istream<wchar_t, char_traits<wchar_t> >
wistream;
template<class E, class T = char_traits<E> >
class basic_iostream;
typedef basic_iostream<char, char_traits<char> >
iostream;
typedef basic_iostream<wchar_t, char_traits<wchar_t> >
wiostream;
// EXTRACTORS
template<class E, class T>
basic_istream<E, T>&
operator>>(basic_istream<E, T>& is, E *s);
template<class E, class T>
basic_istream<E, T>&
operator>>(basic_istream<E, T>& is, E& c);
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
signed char *s);
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
signed char& c);
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
unsigned char *s);
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
unsigned char& c);
// MANIPULATORS
template class<E, T>
basic_istream<E, T>& ws(basic_istream<E, T>& is);
};
Include the iostreams
standard header <istream> to define
template class basic_istream,
which mediates extractions for the iostreams, and the template
class. basic_iostream,
which mediates both insertions and extractions. 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.)
basic_iostreamtemplate <class E, class T = char_traits<E> >
class basic_iostream : public basic_istream<E, T>,
public basic_ostream<E, T> {
public:
explicit basic_iostream(basic_streambuf<E, T>& *sb);
virtual ~basic_iostream();
};
The template class describes an object that controls
insertions, through its base object basic_ostream<E, T>,
and extractions, through its base object basic_istream<E,
T>. The two objects share a common virtual base object basic_ios<E, T>. They
also manage a common stream
buffer, with elements of type E, whose character traits are
determined by the class T. The constructor
initializes its base objects via basic_istream(sb)
and basic_ostream(sb).
basic_istreambasic_istream
· gcount · get
· getline · ignore
· ipfx
· isfx
· operator>>
· peek
· putback · read
· readsome · seekg
· sentry · sync
· tellg · unget
template <class E, class T = char_traits<E> >
class basic_istream
: virtual public basic_ios<E, T> {
public:
explicit basic_istream(basic_streambuf<E, T> *sb);
class sentry;
virtual ~istream();
bool ipfx(bool noskip = false);
void isfx();
basic_istream& operator>>(
basic_istream& (*pf)(basic_istream&));
basic_istream& operator>>(
ios_base& (*pf)(ios_base&));
basic_istream& operator>>(
basic_ios<E, T>& (*pf)(basic_ios<E, T>&));
basic_istream& operator>>(
basic_streambuf<E, T> *sb);
basic_istream& operator>>(bool& n);
basic_istream& operator>>(short& n);
basic_istream& operator>>(unsigned short& n);
basic_istream& operator>>(int& n);
basic_istream& operator>>(unsigned int& n);
basic_istream& operator>>(long& n);
basic_istream& operator>>(unsigned long& n);
basic_istream& operator>>(const void *& n);
basic_istream& operator>>(float& n);
basic_istream& operator>>(double& n);
basic_istream& operator>>(long double& n);
streamsize gcount() const;
int_type get();
basic_istream& get(char_type& c);
basic_istream& get(char_type *s, streamsize n);
basic_istream&
get(char_type *s, streamsize n, char_type delim);
basic_istream&
get(basic_streambuf<char_type, T> *sb);
basic_istream&
get(basic_streambuf<E, T> *sb, char_type delim);
basic_istream& getline(char_type *s, streamsize n);
basic_istream& getline(char_type *s, streamsize n,
char_type delim);
basic_istream& ignore(streamsize n = 1,
int_type delim = traits_type::eof());
int_type peek();
basic_istream& read(char_type *s, streamsize n);
streamsize readsome(char_type *s, streamsize n);
basic_istream& putback(char_type c);
basic_istream& unget();
basic_istream& tellg();
basic_istream& seekg(pos_type pos);
basic_istream& seekg(off_type off,
ios_base::seek_dir way);
int sync();
};
The template class describes an object that controls
extraction of elements and encoded objects from a stream buffer with elements
of type E, also known as char_type, whose character traits are
determined by the class T, 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 basic_istream<E, T>
stores:
basic_ios<E, T>count
in the code abovebasic_istream::basic_istreamexplicit basic_istream(basic_streambuf<E, T> *sb);
The constructor initializes the base class by calling init(sb). It also
stores zero in the extraction count.
basic_istream::gcountstreamsize gcount() const;
The member function returns the extraction count.
basic_istream::getint_type get();
basic_istream& get(char_type& c);
basic_istream& get(char_type *s, streamsize n);
basic_istream& get(char_type *s, streamsize n,
char_type delim);
basic_istream& get(basic_streambuf<E, T> *sb);
basic_istream& get(basic_streambuf<E, T> *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.
basic_istream::getlinebasic_istream& getline(char_type *s, streamsize n);
basic_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.
basic_istream::ignorebasic_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 numeric_limits<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.
basic_istream::ipfxbool 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.
basic_istream::isfxvoid 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.
basic_istream::operator>>basic_istream& operator>>(
basic_istream& (*pf)(basic_istream&));
basic_istream& operator>>(
ios_base& (*pf)(ios_base&));
basic_istream& operator>>(
basic_ios<E, T>& (*pf)(basic_ios<E, T>&));
basic_istream& operator>>(
basic_streambuf<E, T> *sb);
basic_istream& operator>>(bool& n);
basic_istream& operator>>(short& n);
basic_istream& operator>>(unsigned short& n);
basic_istream& operator>>(int& n);
basic_istream& operator>>(unsigned int& n);
basic_istream& operator>>(long& n);
basic_istream& operator>>(unsigned long& n);
basic_istream& operator>>(const void *& n);
basic_istream& operator>>(float& n);
basic_istream& operator>>(double& n);
basic_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:
basic_istream& operator>>(
basic_streambuf<E, T> *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:
basic_istream& operator>>(bool& n);
extracts a field and converts it to a boolean value by calling
use_facet<num_get<E,
InIt>(getloc()). get(InIt( rdbuf()), Init(0), *this,
getloc(), n). Here, InIt is defined as istreambuf_iterator<E,
T>. The function returns *this.
The functions:
basic_istream& operator>>(short& n); basic_istream& operator>>(unsigned short& n); basic_istream& operator>>(int& n); basic_istream& operator>>(unsigned int& n); basic_istream& operator>>(long& n); basic_istream& operator>>(unsigned long& n); basic_istream& operator>>(const void *& n);
each extract a field and convert it to a numeric value by
calling use_facet<num_get<E,
InIt>(getloc()). get(InIt( rdbuf()), Init(0), *this,
getloc(), x). Here, InIt is defined as istreambuf_iterator<E,
T>, and x has type long, unsigned
long, or void * as needed.
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:
basic_istream& operator>>(float& n); basic_istream& operator>>(double& n); basic_istream& operator>>(long double& n);
each extract a field and convert it to a numeric value by
calling use_facet<num_get<E,
InIt>(getloc()). get(InIt( rdbuf()), Init(0), *this,
getloc(), x). Here, InIt is defined as istreambuf_iterator<E,
T>, and x has type double or long
double as needed.
If the converted value cannot be represented as the type of n,
the function calls setstate(failbit).
In any case, it returns *this.
basic_istream::peekint_type peek();
The unformatted
input function extracts an element, if possible, as if by
returning rdbuf()->sgetc().
Otherwise, it returns traits_type::eof().
basic_istream::putbackbasic_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.
basic_istream::readbasic_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.
basic_istream::readsomestreamsize 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().
basic_istream::seekgbasic_istream& seekg(pos_type pos); basic_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.
basic_istream::sentryclass sentry {
public:
explicit sentry(basic_istream& 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().
basic_istream::syncint 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.
basic_istream::tellgbasic_istream& tellg();
If fail()
is false, the member function returns rdbuf()-> pubseekoff(0,
cur, in). Otherwise, it returns
streampos(-1).
basic_istream::ungetbasic_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.
iostreamtypedef basic_iostream<char, char_traits<char> > iostream;
The type is a synonym for template class basic_iostream,
specialized for elements of type char with default character traits.
istreamtypedef basic_istream<char, char_traits<char> > istream;
The type is a synonym for template class basic_istream,
specialized for elements of type char with default character traits.
operator>>template<class E, class T>
basic_istream<E, T>&
operator>>(basic_istream<E, T>& is, E *s);
template<class E, class T>
basic_istream<E, T>&
operator>>(basic_istream<E, T>& is, E& c);
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
signed char *s);
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
signed char& c);
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
unsigned char *s);
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
unsigned char& c);
The template function:
template<class E, class T>
basic_istream<E, T>&
operator>>(basic_istream<E, T>& is, E *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 E that can be declared. The
function always stores E() 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 template function:
template<class E, class T>
basic_istream<E, T>&
operator>>(basic_istream<E, T>& 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 template function:
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
signed char *s);
returns is >> (char *)s.
The template function:
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
signed char& c);
returns is >> (char&)c.
The template function:
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
unsigned char *s);
returns is >> (char *)s.
The template function:
template<class T>
basic_istream<char, T>&
operator>>(basic_istream<char, T>& is,
unsigned char& c);
returns is >> (char&)c.
wiostreamtypedef basic_iostream<wchar_t, char_traits<wchar_t> >
wiostream;
The type is a synonym for template class basic_iostream,
specialized for elements of type wchar_t with
default character traits.
wistreamtypedef basic_istream<wchar_t, char_traits<wchar_t> >
wistream;
The type is a synonym for template class basic_istream,
specialized for elements of type wchar_t with
default character traits.
wstemplate class<E, T>
basic_istream<E, T>& ws(basic_istream<E, T>& is);
The manipulator extracts and discards any elements x
for which use_facet<
ctype<E> >( getloc()). is( ctype<E>::space, 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 .
Copyright © 1992-1996 by P.J. Plauger. All rights reserved.