std:: 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.

Member types

The member type pointer is usually CharT* (see below ).

Member functions

Non-member functions

Notes

The resolution of LWG issue 659 introduced operator - > . It is expected that given an std::istreambuf_iterator i , the expressions ( * i ) . m and i - > m have the same effect.

However, the resolution does not provide a formal specification of its behavior. Thus it is implemented differently, including returning nullptr , returning the address of a temporary, or does even provide the member at all. Its intended behavior can hardly be achieved, and it is removed by the resolution of LWG issue 2790 .

The resolution of LWG issue 659 also made the member type pointer unspecified in order to allow operator-> to return a proxy. This is to allow operator-> to compile when CharT is not a class type.

Example

#include <iostream>
#include <iterator>
#include <sstream>
#include <string>
 
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";
}

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'

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also