# <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