basic_istream Class

Article
2015-07-29

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.

template <class Elem, class Tr = char_traits<Elem> > 
   class basic_istream 
      : virtual public basic_ios<Elem, Tr>

Remarks

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 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 previous code).

Example

See the example for basic_ifstream Class to learn more about input streams.

Constructors

basic_istream

Constructs an object of type basic_istream.

Member Functions

gcount	Returns the number of characters read during the last unformatted input.
get	Reads one or more characters from the input stream.
getline	Reads a line from the input stream.
ignore	Causes a number of elements to be skipped from the current read position.
peek	Returns the next character to be read.
putback	Puts a specified character into the stream.
read	Reads a specified number of characters from the stream and stores them in an array.
readsome	Read from buffer only.
seekg	Moves the read position in a stream.
sentry	The nested class describes an object whose declaration structures the formatted input functions and the unformatted input functions.
swap	Exchanges this basic_istream object for the provided basic_istream object parameter.
sync	Synchronizes the input device associated with the stream with the stream's buffer.
tellg	Reports the current read position in the stream.
unget	Puts the most recently read character back into the stream.

Operators

operator>>	Calls a function on the input stream or reads formatted data from the input stream.
operator=	Assigns the basic_istream on the right side of the operator to this object. This is a move assignment involving an rvalue reference that does not leave a copy behind.

Requirements

Header: <istream>

Namespace: std

Share via