std::istreambuf_iterator

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Iterator library

Iterator primitives
iterator_traits
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tag
iterator
Iterator adaptors
reverse_iterator move_iterator (C++11) back_insert_iterator front_insert_iterator insert_iterator	make_reverse_iterator (C++14) make_move_iterator (C++11) back_inserter front_inserter inserter
Stream iterators
istream_iterator
ostream_iterator
istreambuf_iterator
ostreambuf_iterator
Iterator operations
advance
distance
prev (C++11)
next (C++11)
Range access
begincbegin (C++11)(C++14)
endcend (C++11)(C++14)
rbegincrbegin (C++14)(C++14)
rendcrend (C++14)(C++14)
Container access
sizessize (C++17)(C++20)
empty (C++17)
data (C++17)

 

std::istreambuf_iterator

Member functions

istreambuf_iterator::istreambuf_iterator

istreambuf_iterator::operator*istreambuf_iterator::operator-> (C++11)(until C++17)

istreambuf_iterator::operator++istreambuf_iterator::operator++(int)

istreambuf_iterator::equal

Non-member functions

operator==operator!=

 

Defined in header <iterator>
template< class CharT, class Traits = std::char_traits<CharT> > class istreambuf_iterator : public std::iterator< std::input_iterator_tag,                                                   CharT,                                                   typename Traits::off_type,                                                   /* unspecified, usually CharT* */,                                                   CharT >		(until C++17)
template< class CharT, class Traits = std::char_traits<CharT> > class istreambuf_iterator;		(since C++17)

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>
/* proxy */	Implementation defined class type. The name proxy is for exposition only. 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

(constructor)	constructs a new istreambuf_iterator (public member function)
(destructor) (implicitly declared)	destructs an istreambuf_iterator (public member function)
operator*operator-> (since C++11)(until C++17)	obtains a copy of the current character accesses a member of the current character, if CharT has members (public member function)
operator++operator++(int)	advances the iterator (public member function)
equal	tests if both istreambuf_iterators are end-of-stream or if both are valid (public member function)

Non-member functions

operator==operator!=

compares two istreambuf_iterators (function template)

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

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)