# std::istreambuf_iterator

From cppreference.com
< cpp‎ | iterator

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_iterator`s are end-of-stream or if both are valid (public member function)

### Non-member functions

operator==operator!= | compares two `istreambuf_iterator`s (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)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/iterator/istreambuf_iterator&oldid=108409"