24 Iterators library [iterators]

24.6 Stream iterators [stream.iterators]

24.6.1 Class template istream_iterator [istream.iterator]

The class template istream_iterator is an input iterator ([input.iterators]) that reads (using operator>>) successive elements from the input stream for which it was constructed. After it is constructed, and every time ++ is used, the iterator reads and stores a value of T. If the iterator fails to read and store a value of T (fail() on the stream returns true), the iterator becomes equal to the end-of-stream iterator value. The constructor with no arguments istream_iterator() always constructs an end-of-stream input iterator object, which is the only legitimate iterator to be used for the end condition. The result of operator* on an end-of-stream iterator is not defined. For any other iterator value a const T& is returned. The result of operator-> on an end-of-stream iterator is not defined. For any other iterator value a const T* is returned. The behavior of a program that applies operator++() to an end-of-stream iterator is undefined. It is impossible to store things into istream iterators.

Two end-of-stream iterators are always equal. An end-of-stream iterator is not equal to a non-end-of-stream iterator. Two non-end-of-stream iterators are equal when they are constructed from the same stream.

namespace std {
  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&> {
  public:
    typedef charT char_type;
    typedef traits traits_type;
    typedef basic_istream<charT,traits> istream_type;
    see below istream_iterator();
    istream_iterator(istream_type& s);
    istream_iterator(const istream_iterator& x) = default;
   ~istream_iterator() = default;

    const T& operator*() const;
    const T* operator->() const;
    istream_iterator<T,charT,traits,Distance>& operator++();
    istream_iterator<T,charT,traits,Distance>  operator++(int);
  private:
    basic_istream<charT,traits>* in_stream; // exposition only
    T value;                                // exposition only
  };

  template <class T, class charT, class traits, class Distance>
    bool operator==(const istream_iterator<T,charT,traits,Distance>& x,
            const istream_iterator<T,charT,traits,Distance>& y);
  template <class T, class charT, class traits, class Distance>
    bool operator!=(const istream_iterator<T,charT,traits,Distance>& x,
            const istream_iterator<T,charT,traits,Distance>& y);
}

24.6.1.1 istream_iterator constructors and destructor [istream.iterator.cons]

see below istream_iterator();

Effects: Constructs the end-of-stream iterator. If T is a literal type, then this constructor shall be a constexpr constructor.

Postcondition: in_stream == 0.

istream_iterator(istream_type& s);

Effects: Initializes in_stream with &s. value may be initialized during construction or the first time it is referenced.

Postcondition: in_stream == &s.

istream_iterator(const istream_iterator& x) = default;

Effects: Constructs a copy of x. If T is a literal type, then this constructor shall be a trivial copy constructor.

Postcondition: in_stream == x.in_stream.

~istream_iterator() = default;

Effects: The iterator is destroyed. If T is a literal type, then this destructor shall be a trivial destructor.

24.6.1.2 istream_iterator operations [istream.iterator.ops]

const T& operator*() const;

Returns: value.

const T* operator->() const;

Returns: &(operator*()).

istream_iterator<T,charT,traits,Distance>& operator++();

Requires: in_stream != 0.

Effects: *in_stream >> value.

Returns: *this.

istream_iterator<T,charT,traits,Distance> operator++(int);

Requires: in_stream != 0.

Effects:

istream_iterator<T,charT,traits,Distance> tmp = *this;
*in_stream >> value;
return (tmp);

template <class T, class charT, class traits, class Distance> bool operator==(const istream_iterator<T,charT,traits,Distance> &x, const istream_iterator<T,charT,traits,Distance> &y);

Returns: x.in_stream == y.in_stream.

template <class T, class charT, class traits, class Distance> bool operator!=(const istream_iterator<T,charT,traits,Distance> &x, const istream_iterator<T,charT,traits,Distance> &y);

Returns: !(x == y)