home | help 
std::istream_iterator(3)       C++ Standard Libary	std::istream_iterator(3)

NAME
     std::istream_iterator - std::istream_iterator

Synopsis
	Defined in header <iterator>
	template< class T,

		  class CharT = char,
		  class Traits = std::char_traits<CharT>,
		  class 	Distance	=	 std::ptrdiff_t        >
     (until C++17)
	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 succes-
     sive objects
	of  type  T  from  the	std::basic_istream  object for which it was con-
     structed, by
	calling the appropriate operator>>. The actual read  operation	is  per-
     formed 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  un-
     derlying
	stream, it becomes equal to the end-of-stream iterator. Dereferencing or
	incrementing it further invokes undefined behavior. An end-of-stream it-
     erator
	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  mem-
     bers: 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 CopyAssign-
     able
	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 iterator_category, value_type, difference_type, pointer
	and  reference	are  required  to  be  obtained   by   inheriting   from
     (until C++17)
	std::iterator<std::input_iterator_tag, T, Distance, const T*, const
	T&>.

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

Non-member functions
	operator==	   compares two istream_iterators
	operator!=	   (function template)
	(removed in C++20)

Notes
	When reading characters, std::istream_iterator skips whitespace  by  de-
     fault (unless
	disabled with std::noskipws or equivalent), while std::istreambuf_itera-
     tor 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 <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	retroac-
     tively to
	previously published C++ standards.

	  DR	 Applied to	      Behavior as published		 Correct
     behavior
	P0738R2 C++98	   the first read might be deferred to the   always per-
     formed in the
			   first dereference			     constructor

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)

Hidden category:
	  * Pages with unreviewed LWG DR marker

http://cppreference.com 	   2024.06.10		std::istream_iterator(3)
home | help