Namespaces
Variants
Views
Actions

std::istreambuf_iterator

From cppreference.com
< cpp‎ | iterator
 
 
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
Utilities
(C++20)
Iterator adaptors
Stream iterators
istreambuf_iterator
Iterator customization points
Iterator operations
(C++11)
(C++11)
Range access
(C++11)(C++14)
(C++11)(C++14)
(C++17)(C++20)
(C++14)(C++14)
(C++14)(C++14)
(C++17)
(C++17)
 
 
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.

(since C++11)

Contents

[edit] 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>
/* 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 types iterator_category, value_type, difference_type, pointer and reference 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)

[edit] Member functions

constructs a new istreambuf_iterator
(public member function) [edit]
(destructor)
(implicitly declared)
destructs an istreambuf_iterator
(public member function) [edit]
(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) [edit]
advances the iterator
(public member function) [edit]
tests if both istreambuf_iterators are end-of-stream or if both are valid
(public member function) [edit]

[edit] Non-member functions

(removed in C++20)
compares two istreambuf_iterators
(function template) [edit]

[edit] Example

#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'

[edit] See also

output iterator that writes to std::basic_streambuf
(class template) [edit]
input iterator that reads from std::basic_istream
(class template) [edit]