std::istream_iterator
| Defined in header <iterator>
|
||
template< class T, class CharT = char, class Traits = std::char_traits<CharT>, class Distance = std::ptrdiff_t > class istream_iterator : public std::iterator<std::input_iterator_tag, T, Distance, const T*, const T&> |
(until C++17) | |
template< class T, class CharT = char, class Traits = std::char_traits<CharT>, class Distance = std::ptrdiff_t > class istream_iterator; |
(since C++17) | |
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. An end-of-stream iterator remains in the end-of-stream state even if the underlying stream changes state. Absent a reassignment, it cannot become a non-end-of-stream iterator anymore.
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 |
iterator_category
|
std::input_iterator_tag
|
value_type
|
T
|
difference_type
|
Distance
|
pointer
|
const T*
|
reference
|
const T&
|
char_type
|
CharT
|
traits_type
|
Traits
|
istream_type
|
std::basic_istream<CharT, Traits>
|
|
Member types |
(until C++17) |
Member functions
constructs a new istream_iterator (public member function) | |
destructs an istream_iterator, including the cached value (public member function) | |
| returns the current element (public member function) | |
| advances the iterator (public member function) |
Non-member functions
(removed in C++20) |
compares two istream_iterators (function template) |
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.
Example
#include <algorithm>
#include <iostream>
#include <iterator>
#include <numeric>
#include <sstream>
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");
auto it = std::find_if(std::istream_iterator<int>(str2),
std::istream_iterator<int>(),
[](int i){ return i % 2 == 0; });
if (it != std::istream_iterator<int>())
std::cout << "\nThe first even number is " << *it << ".\n";
//" 9 10" left in the stream
}
Output:
0.1 0.3 0.6 1
The first even number is 8.
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 might be deferred to the first dereference | always performed in the constructor |
See also
| output iterator that writes to std::basic_ostream (class template) | |
| input iterator that reads from std::basic_streambuf (class template) |