# <istream>
<istream>
# ``
* * *
Include the [iostreams](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#iostreams)
standard header **``**
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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ios.html#manipulators).
(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 basic_istream;
typedef basic_istream >
istream;
typedef basic_istream >
wistream;
template >
class basic_iostream;
typedef basic_iostream >
iostream;
typedef basic_iostream >
wiostream;
// EXTRACTORS
template
basic_istream&
operator>>(basic_istream& istr, Elem *str);
template
basic_istream&
operator>>(basic_istream& istr, Elem& ch);
template
basic_istream&
operator>>(basic_istream& istr,
signed char *str);
template
basic_istream&
operator>>(basic_istream& istr,
signed char& ch);
template
basic_istream&
operator>>(basic_istream& istr,
unsigned char *str);
template
basic_istream&
operator>>(basic_istream& istr,
unsigned char& ch);
// MANIPULATORS
template class
basic_istream& ws(basic_istream& istr);
} // namespace stdCopy to clipboard
## `basic_iostream`
template >
class basic_iostream : public basic_istream,
public basic_ostream {
public:
explicit basic_iostream(basic_streambuf& *strbuf);
virtual ~basic_iostream();
};Copy to clipboard
The template class describes an object that controls
insertions, through its base object
`basic_ostream`,
and extractions, through its base object
`basic_istream`.
The two objects share a common virtual base object
`basic_ios`.
They also manage a common
[stream buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#stream%20buffer),
with elements of type `Elem`, whose
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits) are determined
by the class `Tr`. The constructor initializes its base objects
via `basic_istream(strbuf)` and `basic_ostream(strbuf)`.
## `basic_istream`
* * *
**`basic_istream· gcount· get· getline· ignore· operator>>· peek· putback· read· readsome· seekg· sentry· sync· tellg· unget`**
* * *
template >
class basic_istream
: virtual public basic_ios {
public:
typedef typename basic_ios::char_type char_type;
typedef typename basic_ios::traits_type traits_type;
typedef typename basic_ios::int_type int_type;
typedef typename basic_ios::pos_type pos_type;
typedef typename basic_ios::off_type off_type;
explicit basic_istream(basic_streambuf *strbuf);
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& (*pfn)(basic_ios&));
basic_istream& operator>>(
basic_streambuf *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>>(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& strbuf);
basic_istream&
get(basic_streambuf& 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();
};Copy to clipboard
The template class describes an object that controls
extraction of elements and encoded objects from a
[stream buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#stream%20buffer)
with elements of type `Elem`, also known as
`char_type`, whose
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits) 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
{ }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
setstate(state);
return (*this);Copy to clipboard
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
{ }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
setstate(state);Copy to clipboard
Both groups of functions call
`setstate(eofbit)`
if they encounter end-of-file while extracting elements.
An object of class `basic_istream` stores:
- a virtual public base object of class
**`basic_ios`**
- an **extraction count**
for the last unformatted input operation (called `count`
in the code above)
### `basic_istream::basic_istream`
explicit basic_istream(basic_streambuf *strbuf);Copy to clipboard
The constructor initializes the base class by calling
`init(strbuf)`.
It also stores zero in the
[extraction count](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#extraction%20count).
### `basic_istream::gcount`
streamsize gcount() const;Copy to clipboard
The member function returns the
[extraction count](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#extraction%20count).
### `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& strbuf);
basic_istream& get(basic_streambuf& strbuf,
char_type delim);Copy to clipboard
The first of these
[unformatted input functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#unformatted%20input%20functions)
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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ios.html#basic_ios::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 `count - 1` elements
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:
1. at end of file
2. after the function extracts an element that compares equal to
`delim`, in which case the element is put back
to the controlled sequence
3. after the function extracts `count - 1` elements
If 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);Copy to clipboard
The first of these
[unformatted input functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#unformatted%20input%20functions)
returns `getline(str, count, widen('\n'))`.
The second function extracts up to `count - 1` elements
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:
1. at end of file
2. after the function extracts an element that compares equal to
`delim`, in which case the element is neither put back nor
appended to the controlled sequence
3. after the function extracts `count - 1` elements
If the function extracts no elements or `count - 1` 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());Copy to clipboard
The [unformatted input function](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#unformatted%20input%20functions)
extracts up to `count` elements and discards them.
If `count` equals
`numeric_limits::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& (*pfn)(basic_istream&));
basic_istream& operator>>(
ios_base& (*pfn)(ios_base&));
basic_istream& operator>>(
basic_ios& (*pfn)(basic_ios&));
basic_istream& operator>>(
basic_streambuf *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>>(void *& val);
basic_istream& operator>>(float& val);
basic_istream& operator>>(double& val);
basic_istream& operator>>(long double& val);Copy to clipboard
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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ios.html#manipulators),
such as `hex` behave
similarly. The remaining functions constitute the
[formatted input functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#formatted%20input%20functions).
The function:
basic_istream& operator>>(
basic_streambuf *strbuf);Copy to clipboard
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 function:
basic_istream& operator>>(bool& val);Copy to clipboard
extracts a field and converts it to a boolean value by calling
`use_facet(getloc()).
get(InIt(
rdbuf()), Init(0), *this,
getloc(), val)`. Here, `InIt` is defined as
`istreambuf_iterator`.
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>>(void *& val);Copy to clipboard
each extract a field and convert it to a numeric value by calling
`use_facet(getloc()).
get(InIt(
rdbuf()), Init(0), *this,
getloc(), val)`. Here, `InIt` is defined as
`istreambuf_iterator`, 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);Copy to clipboard
each extract a field and convert it to a numeric value by calling
`use_facet(getloc()).
get(InIt(
rdbuf()), Init(0), *this,
getloc(), val)`. Here, `InIt` is defined as
`istreambuf_iterator`, 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();Copy to clipboard
The [unformatted input function](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#unformatted%20input%20functions)
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);Copy to clipboard
The [unformatted input function](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#unformatted%20input%20functions)
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);Copy to clipboard
The [unformatted input function](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#unformatted%20input%20functions)
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);Copy to clipboard
The [unformatted input function](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#unformatted%20input%20functions)
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);Copy to clipboard
If `fail()` is false,
the first member function calls
`newpos = rdbuf()->
pubseekpos(pos,
in)`,
for some `pos_type` temporary object `newpos`.
If `fail()` is false, the second 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
`istr.setstate(failbit)`.
Both functions return `*this`.
### `basic_istream::sentry`
class sentry {
public:
explicit sentry(basic_istream& istr,
bool noskip = false);
operator bool() const;
};Copy to clipboard
The nested class describes an object whose declaration structures the
[formatted input functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#formatted%20input%20functions) and the
[unformatted input functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#unformatted%20input%20functions).
If `istr.good()`
is true, the constructor:
- calls `istr.tie->
flush()`
if `istr.tie()` is not a null pointer
- effectively calls `ws(istr)` if
`istr.flags() &
skipws` is nonzero
If, after any such preparation,
`istr.good()` is false, the constructor calls
`istr.setstate(failbit)`.
In any case, the constructor stores the value returned by `istr.good()`
in **status**.
A later call to `operator bool()` delivers this stored value.
### `basic_istream::sync`
int sync();Copy to clipboard
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::tellg`
pos_type tellg();Copy to clipboard
If `fail()` is false,
the member function returns
`rdbuf()->
pubseekoff(0,
cur,
in)`.
Otherwise, it returns `pos_type(-1)`.
### `basic_istream::unget`
basic_istream& unget();Copy to clipboard
The [unformatted input function](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#unformatted%20input%20functions)
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 > iostream;Copy to clipboard
The type is a synonym for template class
[`basic_iostream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#basic_iostream), specialized
for elements of type *char* with default
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits).
## `istream`
typedef basic_istream > istream;Copy to clipboard
The type is a synonym for template class
[`basic_istream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#basic_istream), specialized
for elements of type *char* with default
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits).
## `operator>>`
template
basic_istream&
operator>>(basic_istream& istr, Elem *str);
template
basic_istream&
operator>>(basic_istream& istr, Elem& ch);
template
basic_istream&
operator>>(basic_istream& istr,
signed char *str);
template
basic_istream&
operator>>(basic_istream& istr,
signed char& ch);
template
basic_istream&
operator>>(basic_istream& istr,
unsigned char *str);
template
basic_istream&
operator>>(basic_istream& istr,
unsigned char& ch);Copy to clipboard
The template function:
template
basic_istream&
operator>>(basic_istream& istr, Elem *str);Copy to clipboard
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
basic_istream&
operator>>(basic_istream& istr, char& ch);Copy to clipboard
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
basic_istream&
operator>>(basic_istream& istr,
signed char *str);Copy to clipboard
returns `istr >> (char *)str`.
The template function:
template
basic_istream&
operator>>(basic_istream& istr,
signed char& ch);Copy to clipboard
returns `istr >> (char&)ch`.
The template function:
template
basic_istream&
operator>>(basic_istream& istr,
unsigned char *str);Copy to clipboard
returns `istr >> (char *)str`.
The template function:
template
basic_istream&
operator>>(basic_istream& istr,
unsigned char& ch);Copy to clipboard
returns `istr >> (char&)ch`.
## `wiostream`
typedef basic_iostream >
wiostream;Copy to clipboard
The type is a synonym for template class
[`basic_iostream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#basic_iostream), specialized
for elements of type `wchar_t` with default
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits).
## `wistream`
typedef basic_istream >
wistream;Copy to clipboard
The type is a synonym for template class
[`basic_istream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#basic_istream), specialized
for elements of type `wchar_t` with default
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits).
## `ws`
template class
basic_istream& ws(basic_istream& istr);Copy to clipboard
The manipulator extracts and discards any elements
`ch` for which
`use_facet<
ctype >(
getloc()).
is(
ctype::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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.
*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. All rights reserved.*
Last Published: Oct 06, 2026
Previous Topic
Next Topic