Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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
       successive
	  characters from the std::basic_streambuf object  for	which  it  was
       constructed.

	  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. Dereferenc-
       ing 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 ex-
       pected 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, re-
       turning the
	  address  of a	temporary, or does even	provide	the member at all. Its
       intended
	  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
       unspecified in
	  order	to allow operator-> to return a	proxy. This is to allow	opera-
       tor-> 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 it-
       erators
	    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
       Correct 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	   re-
       moved
			      not useful

See also
	  ostreambuf_iterator	output	 iterator   that  writes  to  std::ba-
       sic_streambuf
			      (class template)
	  istream_iterator     input  iterator	that   reads   from   std::ba-
       sic_istream
			      (class template)

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

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::istreambuf_iterator&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help