Share via


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

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

See Also

Reference

Thread Safety in the C++ Standard Library

iostream Programming

iostreams Conventions