<istream>

Include the iostreams standard header <istream> to define class istream, which mediates extractions for the iostreams. 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.)

        // DECLARATIONS
class istream;

        // EXTRACTORS
istream&
    operator>>(istream& istr, char *str);
istream&
    operator>>(istream& istr, char& ch);
istream&
    operator>>(istream& istr, signed char *str);
istream&
    operator>>(istream& istr, signed char& ch);
istream&
    operator>>(istream& istr, unsigned char *str);
istream&
    operator>>(istream& istr, unsigned char& ch);

        // MANIPULATORS
istream& ws(istream& istr);
        // END OF DECLARATIONS

istream

istream · gcount · get · getline · ignore · operator>> · peek · putback · read · readsome · seekg · sentry · sync · tellg · unget

class istream : public ios {
public:
    explicit istream(streambuf *strbuf);

    class sentry;
    virtual ~istream();

    istream& operator>>(
        istream& (*pfn)(istream&));
    istream& operator>>(
        ios_base& (*pfn)(ios_base&));
    istream& operator>>(
        ios& (*pfn)(ios&));
    istream& operator>>(
        streambuf *strbuf);
    istream& operator>>(bool& val);
    istream& operator>>(short& val);
    istream& operator>>(unsigned short& val);
    istream& operator>>(int& val);
    istream& operator>>(unsigned int& val);
    istream& operator>>(long& val);
    istream& operator>>(unsigned long& val);
    istream& operator>>(void *& val);
    istream& operator>>(float& val);
    istream& operator>>(double& val);
    istream& operator>>(long double& val);

    streamsize gcount() const;

    int_type get();
    istream& get(char_type& ch);
    istream& get(char_type *str, streamsize count);
    istream&
        get(char_type *str, streamsize count, char_type delim);
    istream& get(streambuf& strbuf);
    istream& get(streambuf& strbuf, char_type delim);

    istream& getline(char_type *str, streamsize count);
    istream& getline(char_type *str, streamsize count,
        char_type delim);

    istream& ignore(streamsize count = 1,
        int_type delim = traits_type::eof());
    int_type peek();
    istream& read(char_type *str, streamsize count);
    streamsize readsome(char_type *str, streamsize count);

    istream& putback(char_type ch);
    istream& unget();

    pos_type tellg();
    istream& seekg(pos_type pos);
    istream& seekg(off_type off,
        ios_base::seek_dir way);
    int sync();
    };

The class describes an object that controls extraction of elements and encoded objects from a stream buffer with elements of type char, also known as char_type, whose character traits are determined by the class char_traits, 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 (...)
            {try
                {setstate(badbit); }
            catch (...)
                {}
            if ((exceptions() & badbit) != 0)
                throw; }}
    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 (...)
            {try
                {setstate(badbit); }
            catch (...)
                {}
            if ((exceptions() & badbit) != 0)
                throw; }}
    setstate(state);

Both groups of functions call setstate(eofbit) if they encounter end-of-file while extracting elements.

An object of class istream stores:

• a public base object of class ios
• an extraction count for the last unformatted input operation (called count in the code above)

istream::istream

explicit istream(streambuf *strbuf);

The constructor initializes the base class by calling init(strbuf). It also stores zero in the extraction count.

istream::gcount

streamsize gcount() const;

The member function returns the extraction count.

istream::get

int_type get();
istream& get(char_type& ch);
istream& get(char_type *str, streamsize count);
istream& get(char_type *str, streamsize count,
    char_type delim);
istream& get(streambuf& strbuf);
istream& get(streambuf& 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 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.

istream::getline

istream& getline(char_type *str, streamsize count);
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 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.

istream::ignore

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

istream::operator>>

istream& operator>>(
    istream& (*pfn)(istream&));
istream& operator>>(
    ios_base& (*pfn)(ios_base&));
istream& operator>>(
    ios& (*pfn)(ios&));
istream& operator>>(
    streambuf *strbuf);
istream& operator>>(bool& val);
istream& operator>>(short& val);
istream& operator>>(unsigned short& val);
istream& operator>>(int& val);
istream& operator>>(unsigned int& val);
istream& operator>>(long& val);
istream& operator>>(unsigned long& val);
istream& operator>>(void *& val);
istream& operator>>(float& val);
istream& operator>>(double& val);
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 remaining functions constitute the formatted input functions.

The function:

istream& operator>>(
    streambuf *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 function:

istream& operator>>(bool& val);

extracts a field and converts it to a boolean value. The function endeavors to match a complete, nonempty boolean input field. If successful it converts the boolean input field to a value of type bool and stores that value in val.

A boolean input field takes one of two forms. If flags() & ios_base::boolalpha is false, it is the same as an integer input field, except that the converted value must be either 0 (for false) or 1 (for true). Otherwise, the sequence must match either false (for false), or true (for true). The function returns *this.

The functions:

istream& operator>>(short& val);
istream& operator>>(unsigned short& val);
istream& operator>>(int& val);
istream& operator>>(unsigned int& val);
istream& operator>>(long& val);
istream& operator>>(unsigned long& val);
istream& operator>>(void *& val);

each extract a field and convert it to a numeric value. Each function endeavors to match a complete, nonempty integer input field. If successful, it stores the result in val. Otherwise, the function stores nothing in val and calls setstate(ios_base::failbit). If the function encounters end of file, it calls setstate(ios_base::eofbit).

The integer input field is converted by the same rules used by the scan functions for matching and converting a series of char elements from a file. The equivalent scan conversion specification is determined as follows:

• If flags() & ios_base::basefield == ios_base::oct, the conversion specification is lo.
• If flags() & ios_base::basefield == ios_base::hex, the conversion specification is lx.
• If flags() & ios_base::basefield == 0, the conversion specification is li.
• Otherwise, the conversion specification is ld if val has a signed type, lu if val has an unsigned type, or p if val has type void *.

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:

istream& operator>>(float& val);
istream& operator>>(double& val);
istream& operator>>(long double& val);

each extract a field and convert it to a numeric value. Each function endeavors to match a complete, nonempty A period (.) separates the integer digits from the fraction digits. The equivalent scan conversion specifier is f if val has type float, lf if val has type double, or Lf if val has type long double.

If the converted value cannot be represented as the type of val, the function calls setstate(failbit). In any case, it returns *this.

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().

istream::putback

istream& putback(char_type ch);

The unformatted input function 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.

istream::read

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.

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().

istream::seekg

istream& seekg(pos_type pos);
istream& seekg(off_type off,
    ios_base::seek_dir way);

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.

istream::sentry

class sentry {
public:
    explicit sentry(istream<Elem, Tr>& istr,
        bool noskip = false);
    operator bool() const;
    };

The nested class describes an object whose declaration structures the formatted input functions and the unformatted input functions. 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.

istream::sync

int 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.

istream::tellg

pos_type tellg();

If fail() is false, the member function returns rdbuf()-> pubseekoff(0, cur, in). Otherwise, it returns pos_type(-1).

istream::unget

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.

operator>>

istream&
    operator>>(istream& istr, char *str);
istream&
    operator>>(istream& istr, char& ch);
istream&
    operator>>(istream& istr, signed char *str);
istream&
    operator>>(istream& istr, signed char& ch);
istream&
    operator>>(istream& istr, unsigned char *str);
istream&
    operator>>(istream istr, unsigned char& ch);

All of these functions are formatted input functions. The function:

istream&
    operator>>(istream& istr, char *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 char that can be declared. The function always stores char(0) after any extracted elements it stores. Extraction stops early on end-of-file, on a character with value char(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 function:

istream&
    operator>>(istream& 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 function:

istream&
    operator>>(istream& istr, signed char *str);

returns istr >> (char *)str.

The function:

istream&
    operator>>(istream& istr, signed char& ch);

returns istr >> (char&)ch.

The function:

istream&
    operator>>(istream& istr, unsigned char *str);

returns istr >> (char *)str.

The function:

istream&
    operator>>(istream& istr, unsigned char& ch);

returns istr >> (char&)ch.

ws

istream& ws(istream& istr);

The manipulator extracts and discards any elements ch for which isspace(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-2006 by P.J. Plauger. All rights reserved.