std::istream_iterator (3) - Linux Manuals

std::istream_iterator: std::istream_iterator

NAME

std::istream_iterator - std::istream_iterator

Synopsis

Defined in header <iterator>
template< class T,
class CharT = char,
class Traits = std::char_traits<CharT>, (until C++17)
class Distance = std::ptrdiff_t >
class istream_iterator: public std::iterator<std::input_iterator_tag,
T, Distance, const T*, const T&>
template< class T,
class CharT = char,
class Traits = std::char_traits<CharT>, (since C++17)
class Distance = std::ptrdiff_t >
class istream_iterator;

std::istream_iterator is a single-pass input iterator that reads successive objects of type T from the std::basic_istream object for which it was constructed, by calling the appropriate operator>>. The actual read operation is performed when the iterator is incremented, not when it is dereferenced. The first object is read when the iterator is constructed. Dereferencing only returns a copy of the most recently read object.
The default-constructed std::istream_iterator is known as the end-of-stream iterator. When a valid std::istream_iterator reaches the end of the underlying stream, it becomes equal to the end-of-stream iterator. Dereferencing or incrementing it further invokes undefined behavior.
A typical implementation of std::istream_iterator holds two data members: a pointer to the associated std::basic_istream object and the most recently read value of type T.
T must meet the DefaultConstructible, CopyConstructible, and CopyAssignable requirements.

Member types

Member type Definition
char_type CharT
traits_type Traits
istream_type std::basic_istream<CharT, Traits>

Member functions

                constructs a new istream_iterator
constructor (public member function)
                destructs an istream_iterator, including the cached value
destructor (public member function)
                returns the current element
operator* (public member function)
operator->
                advances the iterator
operator++ (public member function)
operator++(int)

Non-member functions

           compares two istream_iterators
operator== (function template)
operator!=

Member types

Member type Definition
value_type T
difference_type Distance
pointer const T*
reference const T&
iterator_category std::input_iterator_tag

These member types are required to be obtained by inheriting from std::iterator<std::input_iterator_tag, T, Distance, const T*, const T&>. (until C++17)

Notes

When reading characters, std::istream_iterator skips whitespace by default (unless disabled with std::noskipws or equivalent), while std::istreambuf_iterator does not. In addition, std::istreambuf_iterator is more efficient, since it avoids the overhead of constructing and destructing the sentry object once per character.

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
P0738R2 C++98 the first read may be deferred to the first dereferencing the first read is performed in the constructor

Example

// Run this code

  #include <iostream>
  #include <sstream>
  #include <iterator>
  #include <numeric>
  #include <algorithm>

  int main()
  {
      std::istringstream str("0.1 0.2 0.3 0.4");
      std::partial_sum(std::istream_iterator<double>(str),
                       std::istream_iterator<double>(),
                       std::ostream_iterator<double>(std::cout, " "));

      std::istringstream str2("1 3 5 7 8 9 10");
      std::cout << "\nThe first even number is " <<
          *std::find_if(std::istream_iterator<int>(str2),
                        std::istream_iterator<int>(),
                        [](int i){return i%2 == 0;})
          << ".\n";
      //" 9 10" left in the stream
  }

Output:

  0.1 0.3 0.6 1
  The first even number is 8.