std::istream_iterator

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Iterator library

Iterator primitives
iterator_traits
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tag
iterator
Iterator adaptors
reverse_iterator move_iterator (C++11) back_insert_iterator front_insert_iterator insert_iterator	make_reverse_iterator (C++14) make_move_iterator (C++11) back_inserter front_inserter inserter
Stream iterators
istream_iterator
ostream_iterator
istreambuf_iterator
ostreambuf_iterator
Iterator operations
advance
distance
prev (C++11)
next (C++11)
Range access
begincbegin (C++11)(C++14)
endcend (C++11)(C++14)
rbegincrbegin (C++14)(C++14)
rendcrend (C++14)(C++14)
Container access
size (C++17)
empty (C++17)
data (C++17)

 

std::istream_iterator

Member functions

istream_iterator::istream_iterator

istream_iterator::operator*istream_iterator::operator->

istream_iterator::operator++istream_iterator::operator++(int)

Non-member functions

operator==operator!=

 

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 may be read when the iterator is constructed or when the first dereferencing is done. Otherwise, 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.

Member types

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

Member functions

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

Non-member functions

operator==operator!=

compares two istream_iterators (function template)

Member types

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

Note: before C++17, these member types are required to be obtained by inheriting from std::iterator<std::input_iterator_tag,T,Distance,const T*,const T&>.

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

Run this code

#include <iostream>
#include <sstream>
#include <iterator>
#include <numeric>
 
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, " "));
}

Output:

0.1 0.3 0.6 1

See also

ostream_iterator	output iterator that writes to std::basic_ostream (class template)
istreambuf_iterator	input iterator that reads from std::basic_streambuf (class template)