View source for cpp/iterator/istreambuf iterator

{{cpp/title|istreambuf_iterator}}
{{cpp/iterator/istreambuf_iterator/navbar}}
{{dcl begin}}
{{dcl header|iterator}}
{{dcl rev begin}}
{{dcl|until=c++17|1=
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 */, CharT>
}}
{{dcl|since=c++17|1=
template< class CharT, class Traits = std::char_traits<CharT> >
class istreambuf_iterator;
}}
{{dcl rev end}}
{{dcl end}}

{{tt|std::istreambuf_iterator}} is a single-pass input iterator that reads successive characters from the {{lc|std::basic_streambuf}} object for which it was constructed.

The default-constructed {{tt|std::istreambuf_iterator}} is known as the ''end-of-stream'' iterator. When a valid {{tt|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.

{{rrev|since=c++11|
{{tt|std::istreambuf_iterator}} has a trivial copy constructor, a constexpr default constructor, and a trivial destructor.
}}

{{cpp/iterator/iterator/inherit|std::input_iterator_tag|CharT|typename Traits::off_type|/* unspecified */|CharT|ext=
{{dsc|{{tt|char_type}}|{{tt|CharT}}}}
{{dsc|{{tt|traits_type}}|{{tt|Traits}}}}
{{dsc|{{tt|int_type}}|{{c/core|typename Traits::int_type}}}}
{{dsc|{{tt|streambuf_type}}|{{c/core|std::basic_streambuf<CharT, Traits>}}}}
{{dsc|{{tt|istream_type}}|{{c/core|std::basic_istream<CharT, Traits>}}}}
{{dsc expos mem type|{{c/core|/* proxy */}}|Implementation-defined class type.<br>A {{tt|''proxy''}} object holds a {{tt|char_type}} character and a {{tt|streambuf_type*}} pointer.<br>Dereferencing a {{tt|''proxy''}} object with {{tt|operator*}} yields the stored character.}}
}}

The member type {{tt|pointer}} is usually {{tt|CharT*}} (see [[#Notes|below]]).

===Member functions===
{{dsc begin}}
{{dsc inc|cpp/iterator/istreambuf_iterator/dsc constructor}}
{{dsc inc|cpp/iterator/istreambuf_iterator/dsc destructor}}
{{dsc inc|cpp/iterator/istreambuf_iterator/dsc operator*}}
{{dsc inc|cpp/iterator/istreambuf_iterator/dsc operator_arith}}
{{dsc inc|cpp/iterator/istreambuf_iterator/dsc equal}}
{{dsc end}}

===Non-member functions===
{{dsc begin}}
{{dsc inc|cpp/iterator/istreambuf_iterator/dsc operator_cmp}}
{{dsc end}}

===Notes===
The resolution of {{lwg|659}} introduced {{c/core|operator->}}. It is expected that given an {{tt|std::istreambuf_iterator}} {{c|i}}, the expressions {{c|(*i).m}} and {{c|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 {{c|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|2790}}.

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

===Example===
{{example
|code=
#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";
}
|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'
}}

===Defect reports===
{{dr list begin}}
{{dr list item|wg=lwg|dr=659|std=C++98|before=1. {{tt|std::istreambuf_iterator}} did not have {{c/core|operator->}}<br>2. the member type {{tt|pointer}} was specified as {{tt|CharT*}}|after=1. added<br>2. made unspecified}}
{{dr list item|wg=lwg|dr=2790|std=C++98|before=the {{c/core|operator->}} added by {{lwg|659}} was not useful|after=removed}}
{{dr list end}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/iterator/dsc ostreambuf_iterator}}
{{dsc inc|cpp/iterator/dsc istream_iterator}}
{{dsc end}}

{{langlinks|de|es|fr|it|ja|pt|ru|zh}}