##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

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

`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.

### [edit] 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>

| This section is incomplete Reason: the proxy member type

### [edit] Member functions

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

### [edit] Non-member functions

operator==operator!= | compares two `istreambuf_iterator`s (function template) [edit]

## Inherited from std::iterator

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

### [edit] 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

### [edit] See also

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

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

- Todo with reason