istreambuf_iterator<T>

An istreambuf_iterator is an iterator adapter that reads raw data from an input stream. Using the ++ operator normally used to advance an iterator instead reads a single unformatted character from the stream. Unlike istream_iterator, istreambuf_iterator does not use the << operator and consequently ignores formatting. For situations where reading binary data is useful, istreambuf_iterator is preferable over istream_iterator.

istreambuf_iterator is a class template whose template argument indicates what type should be used to store the binary data read from the stream. In virtually all cases, this should be char.

As with other input iterator classes, you will need two istreambuf_iterators to delineate a range. While you can construct an istreambuf_iterator for any input stream, the STL only defines a single istreambuf_iterator suitable for use as an end iterator. An istreambuf_iterator constructed using the default constructor (which has no parameters) creates an istreambuf_iterator indicating "end of stream." Reading values from such an istreambuf_iterator results in undefined behavior, so be sure to avoid doing so.

istreambuf_iterator<T> Member Functions

istreambuf_iterator<T>(istream &input)

Constructs an istreambuf_iterator that reads from the specified stream.

istreambuf_iterator<char> itr(myBinaryStream); // An iterator that reads binary data from a stream.

Constructs a new istreambuf_iterator that reads raw binary data from the specified stream. When the iterator encounters an end of file or the stream enters a fail state, the iterator will take on the sentinel value istreambuf_iterator<T>().

istreambuf_iterator<T>()

Constructs a special istreambuf_iterator indicating end-of-stream.

istreambuf_iterator<char> itr(); // An end-of-stream indicator.

accumulate(istreambuf_iterator<char>(myStream), istreambuf_iterator<char>(), 0); // Add the ASCII values of all chars in the stream.

Constructs a new istreambuf_iterator that acts as an "end-of-stream" iterator. Use this iterator when defining iterator ranges with an istreambuf_iterator.

bool equal(const istreambuf_iterator<T> &other) const;

Returns whether both iterators are end-of-stream or both not end-of-stream

if(itr.equal(istreambuf_iterator<char>())) { /* ... */ } // Iterator at end-of-stream.

Despite the name of this function, the equal function does not test whether the two iterators both point to the same element. Instead, it returns true if both iterators are at end-of-stream or if both iterators are not at end-of-stream.