std::istreambuf_iterator (3) - Linux Manuals

std::istreambuf_iterator: std::istreambuf_iterator

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,
CharT, (until C++17)
typename Traits::off_type,
/* unspecified, usually CharT* */,
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. Dereferencing or incrementing it further invokes undefined behavior.
std::istreambuf_iterator has a trivial copy constructor, a constexpr default constructor, and a trivial destructor.

Member types

Member type Definition
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.
               Deferencing a proxy object with operator* yields the stored character.

Member functions

                           constructs a new istreambuf_iterator
constructor (public member function)

destructor destructs an istreambuf_iterator
                           (public member function)
(implicitly declared)

operator* obtains a copy of the current character
operator-> accesses a member of the current character, if CharT has members
                           (public member function)

(since C++11)(until C++17)
                           advances the iterator
operator++ (public member function)
operator++(int)
                           tests if both istreambuf_iterators are end-of-stream or if both are valid
equal (public member function)

Non-member functions

           compares two istreambuf_iterators
operator== (function template)
operator!=

Member types

Member type Definition
value_type CharT
difference_type Traits::off_type
pointer /* unspecified, usually CharT* */
reference CharT
iterator_category std::input_iterator_tag

These member types are required to be obtained by inheriting from std::iterator<std::input_iterator_tag, CharT, Traits::off_type, /* unspecified, usually CharT* */, CharT>. (until C++17)

Example

// Run this code

  #include <vector>
  #include <sstream>
  #include <iostream>
  #include <iterator>

  int main()
  {
      // typical use case: an input stream represented as a pair of iterators
      std::istringstream in("Hello, world");
      std::vector<char> v( (std::istreambuf_iterator<char>(in)),
                            std::istreambuf_iterator<char>() );
      std::cout << "v has " << v.size() << " bytes. ";
      v.push_back('\0');
      std::cout << "it holds \"" << &v[0] << "\"\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; // this makes the apparent value of *i2 to jump from 'a' to 'c'
      std::cout << "after incrementing i2, but not i1\n"
                << "i1 returns " << *i1 << '\n'
                << "i2 returns " << *i2 << '\n';

  }

Output:

  v has 12 bytes. it holds "Hello, world"
  i1 returns a
  i2 returns a
  after incrementing i1, but not i2
  i1 returns b
  i2 returns a
  after incrementing i2, but not i1
  i1 returns b
  i2 returns c