template <class T, class charT=char, class traits=char_traits<charT>, 
          class Distance = ptrdiff_t>
  class istream_iterator;

<iterator>

Istream iterator

Istream iterators are a special input iterator class designed to read successive elements from an input stream (istream or another basic_istream class).

They are constructed from a basic_istream object, to which they become associated, so that whenever operator++ is used on the iterator, it extracts an element (with >>) from the stream.

A special value for this iterator exists: the end-of-stream; When an iterator is set to this value has either reached the end of the stream (operator void* applied to the stream returns false) or has been constructed using its default constructor (without associating it with any basic_istream object).

It is defined with an operation similar to:

template <class T, class charT=char, class traits=char_traits<charT>, class Distance=ptrdiff_t>
  class istream_iterator :
    public iterator<input_iterator_tag, T, Distance, const T*, const T&>
{
  basic_istream<charT,traits>* in_stream;
  T value;

public:
  typedef charT char_type;
  typedef traits traits_type;
  typedef basic_istream<charT,traits> istream_type;
  istream_iterator() : in_stream(0) {}
  istream_iterator(istream_type& s) : in_stream(&s) { ++*this; }
  istream_iterator(const istream_iterator<T,charT,traits,Distance>& x)
    : in_stream(x.in_stream), value(x.value) {}
  ~istream_iterator() {}

  const T& operator*() const { return value; }
  const T* operator->() const { return &value; }
  istream_iterator<T,charT,traits,Distance>& operator++() {
    if (in_stream && !(*in_stream >> value)) in_stream=0;
    return *this;
  }
  istream_iterator<T,charT,traits,Distance> operator++(int) {
    istream_iterator<T,charT,traits,Distance> tmp = *this;
    ++*this;
    return tmp;
  }
};

The <iterator> header file also defines two overloaded global operator functions (== and !=), which compare iterators: Two istream_iterators compare equal if they are constructed from the same stream, or if they are both end-of-stream iterators (either because they reached the end of the stream or because they were default-constructed).

Template parameters

T

Element type for the iterator: The type of elements extracted from the stream

charT

First template parameter for the basic_istream: The type of elements the stream manages (char for istream).

traits

Second template parameter for the basic_istream: Character traits for the elements the stream manages.

Distance

Type to represent the difference between two iterators (generally an integral type, such as ptrdiff_t).

Member functions

constructor

istream_iterator objects are constructed from an istream object.
The default constructor constructs an end-of-stream iterator and the copy constructor constructs a copy of the iterator passed as argument.

operator*

Returns the next value in the stream.

operator->

Returns a pointer the next value in the stream in order to access one of its members.

operator++

Extracts a new element from the associated istream object, unless the iterator is an end-of-stream iterator.

Example

// istream_iterator example
#include <iostream>
#include <iterator>
using namespace std;

int main () {
  double value1, value2;
  cout << "Please, insert two values: ";

  istream_iterator<double> eos;         // end-of-stream iterator
  istream_iterator<double> iit (cin);   // stdin iterator

  if (iit!=eos) value1=*iit;

  iit++;
  if (iit!=eos) value2=*iit;

  cout << value1 << "*" << value2 << "=" << (value1*value2) << endl;

  return 0;
}

Possible output:

Please, insert two values: 2 32
2*32=64

See also