<istream>
basic_iostream
· basic_istream
· iostream
· istream
· operator>>
· wiostream
· wistream
· ws
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.)
namespace std { template<class Elem, class Tr = char_traits<Elem> > class basic_istream; typedef basic_istream<char, char_traits<char> > istream; typedef basic_istream<wchar_t, char_traits<wchar_t> > wistream; template<class Elem, class Tr = char_traits<Elem> > class basic_iostream; typedef basic_iostream<char, char_traits<char> > iostream; typedef basic_iostream<wchar_t, char_traits<wchar_t> > wiostream; // EXTRACTORS template<class Elem, class Tr> basic_istream<Elem, Tr>& operator>>(basic_istream<Elem, Tr>& istr, Elem *str); template<class Elem, class Tr> basic_istream<Elem, Tr>& operator>>(basic_istream<Elem, Tr>& istr, Elem& ch); template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, signed char *str); template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, signed char& ch); template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, unsigned char *str); template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, unsigned char& ch); template<class Elem, class Tr, class Ty> basic_istream<Elem, Tr>& operator>>(basic_istream<char, Tr>&& istr, Ty& val); [added with C++11] // MANIPULATORS template class<Elem, Tr> basic_istream<Elem, Tr>& ws(basic_istream<Elem, Tr>& istr); } // namespace std
basic_iostream
template <class Elem, class Tr = char_traits<Elem> > class basic_iostream : public basic_istream<Elem, Tr>, public basic_ostream<Elem, Tr> { public: explicit basic_iostream(basic_streambuf<Elem, Tr>& *strbuf); virtual ~basic_iostream(); protected: basic_iostream(basic_iostream&& right); [added with C++11] basic_iostream(const basic_iostream& right) = delete; [added with C++11] basic_iostream& operator=(basic_iostream&& right); [added with C++11] basic_iostream& operator=(const basic_iostream& right) = delete; [added with C++11] void swap(basic_iostream& right); [added with C++11] };
The template class describes an object that controls
insertions, through its base object
basic_ostream<Elem, Tr>
,
and extractions, through its base object
basic_istream<Elem, Tr>
.
The two objects share a common virtual base object
basic_ios<Elem, Tr>
.
They also manage a common
stream buffer,
with elements of type Elem
, whose
character traits are determined
by the class Tr
.
basic_iostream::basic_iostream
explicit basic_iostream(basic_streambuf<Elem, Tr> *strbuf); basic_iostream(basic_iostream&& right); [added with C++11]
The first constructor initializes the base objects
via basic_istream(strbuf)
and basic_ostream(strbuf)
.
The second constructor initializes the base objects by calling
move(right)
.
basic_iostream::operator=
basic_iostream& operator=(basic_iostream&& right); [added with C++11]
The member operator calls
swap(right)
.
basic_iostream::swap
void swap(basic_iostream& right); [added with C++11]
The member function calls
swap(right)
.
basic_istream
basic_istream
· gcount
· get
· getline
· ignore
· operator=
· operator>>
· peek
· putback
· read
· readsome
· seekg
· sentry
· swap
· sync
· tellg
· unget
template <class Elem, class Tr = char_traits<Elem> > class basic_istream : virtual public basic_ios<Elem, Tr> { public: typedef typename basic_ios<Elem, Tr>::char_type char_type; typedef typename basic_ios<Elem, Tr>::traits_type traits_type; typedef typename basic_ios<Elem, Tr>::int_type int_type; typedef typename basic_ios<Elem, Tr>::pos_type pos_type; typedef typename basic_ios<Elem, Tr>::off_type off_type; explicit basic_istream(basic_streambuf<Elem, Tr> *strbuf); protected: basic_istream(basic_istream&& right); [added with C++11] basic_istream(const basic_istream& right) = delete; [added with C++11] basic_istream& operator=(basic_istream&& right); [added with C++11] basic_istream& operator=(const basic_istream& right) = delete; [added with C++11] void swap(basic_istream& right); [added with C++11] public: class sentry; virtual ~basic_istream(); basic_istream& operator>>( basic_istream& (*pfn)(basic_istream&)); basic_istream& operator>>( ios_base& (*pfn)(ios_base&)); basic_istream& operator>>( basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&)); basic_istream& operator>>( basic_streambuf<Elem, Tr> *strbuf); basic_istream& operator>>(bool& val); basic_istream& operator>>(short& val); basic_istream& operator>>(unsigned short& val); basic_istream& operator>>(int& val); basic_istream& operator>>(unsigned int& val); basic_istream& operator>>(long& val); basic_istream& operator>>(unsigned long& val); basic_istream& operator>>(long long& val); [added with C++11] basic_istream& operator>>(unsigned long long& val); [added with C++11] basic_istream& operator>>(void *& val); basic_istream& operator>>(float& val); basic_istream& operator>>(double& val); basic_istream& operator>>(long double& val); streamsize gcount() const; int_type get(); basic_istream& get(char_type& ch); basic_istream& get(char_type *str, streamsize count); basic_istream& get(char_type *str, streamsize count, char_type delim); basic_istream& get(basic_streambuf<char_type, Tr>& strbuf); basic_istream& get(basic_streambuf<Elem, Tr>& strbuf, char_type delim); basic_istream& getline(char_type *str, streamsize count); basic_istream& getline(char_type *str, streamsize count, char_type delim); basic_istream& ignore(streamsize count = 1, int_type delim = traits_type::eof()); int_type peek(); basic_istream& read(char_type *str, streamsize count); streamsize readsome(char_type *str, streamsize count); basic_istream& putback(char_type ch); basic_istream& unget(); pos_type 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 Elem
, also known as
char_type
, whose
character traits are determined by the
class Tr
, 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> } setstate(state); return (*this);
Other member functions are unformatted input functions. They follow the pattern:
count = 0; // the value returned by gcount iostate state = goodbit; const sentry ok(*this, true); if (ok) try {<extract elements and deliver count extracted elements in count accumulate flags in state> } setstate(state);
Still other member functions are positioning functions. They follow the pattern:
iostate state = goodbit; const sentry ok(*this, true); if (!fail()) {<perform positioning operation accumulate (flags) in state> } setstate(state);
All groups of functions call
setstate(eofbit)
if they encounter end-of-file while extracting elements.
An object of class basic_istream<Elem, Tr>
stores:
basic_ios<Elem, Tr>
count
in the code above)basic_istream::basic_istream
explicit basic_istream(basic_streambuf<Elem, Tr> *strbuf); basic_istream(basic_istream&& right); [added with C++11]
The first constructor initializes the base class by calling
init(strbuf)
.
It also stores zero in the
extraction count.
The second constructor initializes the base class by calling
move(right)
.
It also stores right.gcount()
in the
extraction count and stores zero in the extraction count for right
.
basic_istream::gcount
streamsize gcount() const;
The member function returns the extraction count.
basic_istream::get
int_type get(); basic_istream& get(char_type& ch); basic_istream& get(char_type *str, streamsize count); basic_istream& get(char_type *str, streamsize count, char_type delim); basic_istream& get(basic_streambuf<Elem, Tr>& strbuf); basic_istream& get(basic_streambuf<Elem, Tr>& strbuf, 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
meta
the same way. If meta
compares equal to
traits_type::eof()
,
the function calls
setstate(failbit)
.
Otherwise, it stores
traits_type::to_char_type(meta)
in ch
. The function returns *this
.
The third function returns get(str, count, widen('\n'))
.
The fourth function extracts up to N
elements,
where N = count <= 1 ? 0 : count - 1
,
and stores them in the array beginning at str
. It always stores
char_type()
after
any extracted elements it stores. In order of testing, extraction stops:
delim
, in which case the element is put back
to the controlled sequenceN
elementsIf the function extracts no elements, it calls
setstate(failbit)
.
In any case, it returns *this
.
The fifth function returns get(strbuf, widen('\n'))
.
The sixth function extracts elements and inserts them in
strbuf
. 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::getline
basic_istream& getline(char_type *str, streamsize count); basic_istream& getline(char_type *str, streamsize count, char_type delim);
The first of these
unformatted input functions
returns getline(str, count, widen('\n'))
.
The second function extracts up to N
elements,
where N = count <= 1 ? 0 : count - 1
,
and stores them in the array beginning at str
. 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
elementsIf the function extracts no elements or N
elements, it calls
setstate(failbit)
.
In any case, it returns *this
.
basic_istream::ignore
basic_istream& ignore(streamsize count = 1, int_type delim = traits_type::eof());
The unformatted input function
extracts up to count
elements and discards them.
If count
equals
numeric_limits<int>::max()
,
however, it is taken as arbitrarily large.
Extraction stops early on end-of-file or
on an element ch
such that
traits_type::to_int_type(ch)
compares equal to delim
(which is also extracted).
The function returns *this
.
basic_istream::operator=
basic_istream& operator=(basic_istream&& right); [added with C++11]
The member operator calls
swap(right)
.
basic_istream::operator>>
basic_istream& operator>>( basic_istream& (*pfn)(basic_istream&)); basic_istream& operator>>( ios_base& (*pfn)(ios_base&)); basic_istream& operator>>( basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&)); basic_istream& operator>>( basic_streambuf<Elem, Tr> *strbuf); basic_istream& operator>>(bool& val); basic_istream& operator>>(short& val); basic_istream& operator>>(unsigned short& val); basic_istream& operator>>(int& val); basic_istream& operator>>(unsigned int& val); basic_istream& operator>>(long& val); basic_istream& operator>>(unsigned long& val); basic_istream& operator>>(long long& val); [added with C++11] basic_istream& operator>>(unsigned long long& val); [added with C++11] basic_istream& operator>>(void *& val); basic_istream& operator>>(float& val); basic_istream& operator>>(double& val); basic_istream& operator>>(long double& val);
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 function:
basic_istream& operator>>( basic_streambuf<Elem, Tr> *strbuf);
extracts elements, if strbuf
is not a null pointer,
and inserts them in strbuf
. 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 remaining functions constitute the formatted input functions.
The function:
basic_istream& operator>>(bool& val);
extracts a field and converts it to a boolean value by calling
use_facet<num_get<Elem,
InIt>(getloc()).
get(InIt(
rdbuf()), Init(0), *this,
getloc(), val)
. Here, InIt
is defined as
istreambuf_iterator<Elem,
Tr>
.
The function returns *this
.
The functions:
basic_istream& operator>>(short& val); basic_istream& operator>>(unsigned short& val); basic_istream& operator>>(int& val); basic_istream& operator>>(unsigned int& val); basic_istream& operator>>(long& val); basic_istream& operator>>(unsigned long& val); basic_istream& operator>>(long long& val); [added with C++11] basic_istream& operator>>(unsigned long long& val); [added with C++11] basic_istream& operator>>(void *& val);
each extract a field and convert it to a numeric value by calling
use_facet<num_get<Elem,
InIt>(getloc()).
get(InIt(
rdbuf()), Init(0), *this,
getloc(), val)
. Here, InIt
is defined as
istreambuf_iterator<Elem,
Tr>
, and val
has type long,
unsigned long, or void * as needed.
If the converted value cannot
be represented as the type of val
, the function calls
setstate(failbit)
.
In any case, the function returns *this
.
The functions:
basic_istream& operator>>(float& val); basic_istream& operator>>(double& val); basic_istream& operator>>(long double& val);
each extract a field and convert it to a numeric value by calling
use_facet<num_get<Elem,
InIt>(getloc()).
get(InIt(
rdbuf()), Init(0), *this,
getloc(), val)
. Here, InIt
is defined as
istreambuf_iterator<Elem,
Tr>
, and val
has type double or
long double as needed.
If the converted value cannot
be represented as the type of val
, the function calls
setstate(failbit)
.
In any case, it returns *this
.
basic_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()
.
basic_istream::putback
basic_istream& putback(char_type ch);
The positioning function
first clears eofbit
(before constructing sentry
), then
puts back ch
, 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::read
basic_istream& read(char_type *str, streamsize count);
The unformatted input function
extracts up to count
elements
and stores them in the array beginning at str
.
Extraction stops early on end-of-file, in which case the function calls
setstate(failbit)
.
In any case, it returns *this
.
basic_istream::readsome
streamsize readsome(char_type *str, streamsize count);
The unformatted input function
extracts up to count
elements
and stores them in the array beginning at str
.
If good()
is
false, 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 count
and N
, then calls
read(str, N)
.
In any case, the function returns
gcount()
.
basic_istream::seekg
basic_istream& seekg(pos_type pos); basic_istream& seekg(off_type off, ios_base::seek_dir way);
Both positioning function
first clear eofbit
(before constructing sentry
).
If fail()
is false,
the first positioning function calls
newpos = rdbuf()->
pubseekpos(pos,
in)
,
for some pos_type
temporary object newpos
.
If fail()
is false, the second positioning function calls
newpos = rdbuf()->
pubseekoff(off, way,
in)
.
In either case, if (off_type)newpos == (off_type)(-1)
(the positioning operation fails) the function calls
setstate(failbit)
.
Both functions return *this
.
basic_istream::sentry
class sentry { public: explicit sentry(basic_istream& istr, bool noskip = false); explicit operator bool() const; sentry(const sentry& right) = delete; [added with C++11] sentry& operator=(const sentry& right) = delete; [added with C++11] };
The nested class describes an object whose declaration structures the
formatted input functions and the
unformatted input functions.
If good()
is true, the constructor:
istr.tie->
flush()
if tie()
is not a null pointerws(istr)
if
flags() &
skipws
is nonzeroIf, after any such preparation,
good()
is false, the constructor calls
setstate(failbit)
.
In any case, the constructor stores the value returned by good()
in status.
A later call to operator bool()
delivers this stored value.
basic_istream::swap
void swap(basic_istream& right); [added with C++11]
The member function calls
swap(right)
.
It also exchanges the
extraction count
with the extraction count for right
.
basic_istream::sync
int sync();
If rdbuf()
is
a null pointer,
the positioning 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::tellg
pos_type tellg();
If fail()
is false,
the positioning function returns
rdbuf()->
pubseekoff(0,
cur,
in)
.
Otherwise, it returns pos_type(-1)
.
basic_istream::unget
basic_istream& unget();
The positioning function
first clears eofbit
(before constructing sentry
), then
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
.
iostream
typedef 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.
istream
typedef 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 Elem, class Tr> basic_istream<Elem, Tr>& operator>>(basic_istream<Elem, Tr>& istr, Elem *str); template<class Elem, class Tr> basic_istream<Elem, Tr>& operator>>(basic_istream<Elem, Tr>& istr, Elem& ch); template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, signed char *str); template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, signed char& ch); template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, unsigned char *str); template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, unsigned char& ch); template<class Elem, class Tr, class Ty> basic_istream<Elem, Tr>& operator>>(basic_istream<char, Tr>&& istr, Ty& val); [added with C++11]
The template function:
template<class Elem, class Tr> basic_istream<Elem, Tr>& operator>>(basic_istream<Elem, Tr>& istr, Elem *str);
extracts up to N - 1
elements
and stores them in the array beginning at str
.
If istr.width()
is greater
than zero, N
is istr.width()
; otherwise it is
the size of
the largest array of Elem
that can be declared.
The function always stores
Elem()
after
any extracted elements it stores. Extraction stops early on end-of-file,
on a character with value Elem(0)
(which is not extracted),
or on any element (which is not extracted) that would be discarded by
ws
.
If the function extracts no elements, it calls
istr.setstate(failbit)
.
In any case, it calls istr.width(0)
and
returns istr
.
The template function:
template<class Elem, class Tr> basic_istream<Elem, Tr>& operator>>(basic_istream<Elem, Tr>& istr, char& ch);
extracts an element, if possible, and stores it in ch
.
Otherwise, it calls
is.setstate(failbit)
.
In any case, it returns istr
.
The template function:
template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, signed char *str);
returns istr >> (char *)str
.
The template function:
template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, signed char& ch);
returns istr >> (char&)ch
.
The template function:
template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, unsigned char *str);
returns istr >> (char *)str
.
The template function:
template<class Tr> basic_istream<char, Tr>& operator>>(basic_istream<char, Tr>& istr, unsigned char& ch);
returns istr >> (char&)ch
.
The template function:
template<class Elem, class Tr, class Ty> basic_istream<Elem, Tr>& operator>>(basic_istream<char, Tr>&& istr, Ty& val); [added with C++11]
returns istr >> val
(and converts an
rvalue reference to
istr
to an lvalue in the process).
wiostream
typedef 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.
wistream
typedef 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.
ws
template class<Elem, Tr> basic_istream<Elem, Tr>& ws(basic_istream<Elem, Tr>& istr);
The manipulator extracts and discards any elements
ch
for which
use_facet<
ctype<Elem> >(
getloc()).
is(
ctype<Elem>::space, ch)
is true.
The function calls
setstate(eofbit)
if it encounters end-of-file while extracting elements.
It returns istr
.
See also the Table of Contents and the Index.
Copyright © 1992-2013 by P.J. Plauger. All rights reserved.