std::istreambuf_iterator

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

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
size (C++17)
empty (C++17)
data (C++17)

 

std::istreambuf_iterator

Member functions

istreambuf_iterator::istreambuf_iterator

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

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 actual read operation is performed when the iterator is incremented, not when it is dereferenced. The first character may be read when the iterator is constructed or when the first dereferencing is done. Otherwise, dereferencing only returns a copy of the most recently read character.

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>

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)	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

Note: before C++17, 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>.

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)