`<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:

a virtual public base object of class basic_ios<Elem, Tr>
an extraction count for the last unformatted input operation (called 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:

at end of file
after the function extracts an element that compares equal to delim, in which case the element is put back to the controlled sequence
after the function extracts N 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);

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:

at end of file
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
after the function extracts N elements

If 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);

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:

calls istr.tie-> flush() if tie() is not a null pointer
effectively calls ws(istr) if flags() & skipws is nonzero

If, 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.