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

NAME
     std::istreambuf_iterator - std::istreambuf_iterator

Synopsis
	Defined in header <iterator>
	template< class CharT, class Traits = std::char_traits<CharT> >

	class istreambuf_iterator
	    :  public std::iterator<std::input_iterator_tag,		  (until
     C++17)
				   CharT, typename Traits::off_type,

				   /* unspecified */, CharT>
	template< class CharT, class Traits = std::char_traits<CharT> >   (since
     C++17)
	class istreambuf_iterator;

	std::istreambuf_iterator is a single-pass input iterator that reads suc-
     cessive
	characters  from  the  std::basic_streambuf object for which it was con-
     structed.

	The default-constructed std::istreambuf_iterator is known as the end-of-
     stream
	iterator. When a valid std::istreambuf_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.

	std::istreambuf_iterator  has  a  trivial  copy constructor, a constexpr
     (since C++11)
	default constructor, and a trivial destructor.

Member types
	Member type	  Definition
	iterator_category std::input_iterator_tag
	value_type	  CharT
	difference_type   typename Traits::off_type
	pointer 	  /* unspecified */
	reference	  CharT
	char_type	  CharT
	traits_type	  Traits
	int_type	  typename Traits::int_type
	streambuf_type	  std::basic_streambuf<CharT, Traits>
	istream_type	  std::basic_istream<CharT, Traits>
			  Implementation-defined class type. The name  proxy  is
     for
			  exposition only.
	/*  proxy  */	     A	proxy  object  holds a char_type character and a
     streambuf_type*
			  pointer.
			  Dereferencing a proxy object with operator* yields the
     stored
			  character.

	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, CharT, typename
	Traits::off_type, /* unspecified */, CharT>.

	The member type pointer is usually CharT* (see below).

Member functions
	constructor	      constructs a new istreambuf_iterator
			      (public member function)
	destructor	      destructs an istreambuf_iterator
	(implicitly declared) (public member function)
	operator*	      obtains a copy of the current character
			      (public member function)
	operator++	      advances the iterator
	operator++(int)       (public member function)
			      tests  if  both  istreambuf_iterators  are end-of-
     stream or if
	equal		      both are valid
			      (public member function)

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

Notes
	The resolution of LWG issue 659 introduced operator->.	It  is	expected
     that given an
	std::istreambuf_iterator  i,  the  expressions	(*i).m and i->m have the
     same effect.

	However, the resolution does not provide a formal specification  of  its
     behavior.
	Thus it is implemented differently, including returning nullptr, return-
     ing the
	address  of a temporary, or does even provide the member at all. Its in-
     tended
	behavior can hardly be achieved, and it is removed by the resolution  of
     LWG issue
	2790.

	The  resolution  of  LWG issue 659 also made the member type pointer un-
     specified in
	order to allow operator-> to return a proxy. This is to allow operator->
     to compile
	when CharT is not a class type.

Example
     // Run this code

      #include <iostream>
      #include <iterator>
      #include <sstream>
      #include <string>

      int main()
      {
	  // typical use case: an input stream represented as a pair  of  itera-
     tors
	  std::istringstream in{"Hello, world"};
	  std::istreambuf_iterator<char> it{in}, end;
	  std::string ss{it, end};
	  std::cout << "ss has " << ss.size() << " bytes; "
		       "it holds \"" << ss << "\"\n";

	  // demonstration of the single-pass nature
	  std::istringstream s{"abc"};
	  std::istreambuf_iterator<char> i1{s}, i2{s};
	  std::cout << "i1 returns '" << *i1 << "'\n"
		       "i2 returns '" << *i2 << "'\n";

	  ++i1;
	  std::cout << "after incrementing i1, but not i2:\n"
		       "i1 returns '" << *i1 << "'\n"
		       "i2 returns '" << *i2 << "'\n";

	  ++i2;
	  std::cout << "after incrementing i2, but not i1:\n"
		       "i1 returns '" << *i1 << "'\n"
		       "i2 returns '" << *i2 << "'\n";
      }

Output:
      ss has 12 bytes; it holds "Hello, world"
      i1 returns 'a'
      i2 returns 'a'
      after incrementing i1, but not i2:
      i1 returns 'b'
      i2 returns 'b'
      after incrementing i2, but not i1:
      i1 returns 'c'
      i2 returns 'c'

	Defect reports

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

	   DR	 Applied to	       Behavior as  published		    Cor-
     rect behavior
			    1. std::istreambuf_iterator did not have
	LWG   659   C++98	operator->				      1.
     added
			    2. the member type pointer was specified as  2. made
     unspecified
			    CharT*
	LWG 2790 C++98	    the operator-> added by LWG issue 659 was	 removed
			    not useful

See also
	ostreambuf_iterator output iterator that writes to std::basic_streambuf
			    (class template)
	istream_iterator    input iterator that reads from std::basic_istream
			    (class template)

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