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 (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 Traits::off_type
pointer /* unspecified, usually CharT* */
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.
Deferencing 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, Traits::off_type, /*
unspecified, usually CharT* */, CharT>.

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
operator-> accesses a member of the current character, if CharT has
(since C++11)(until C++17) members
(public member function)
operator++ advances the iterator
operator++(int) (public member function)
tests if both istreambuf_iterators are end-of-stream or
equal if both are valid
(public member function)

Non-member functions

operator== compares two istreambuf_iterators
operator!= (function template)
(removed in C++20)

Example

// Run this code

#include <string>
#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::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'