istreambuf_iterator


class template
<iterator> 
template <class charT, class traits=char_traits<charT> >
  class istreambuf_iterator;

Input stream buffer iterator

Istreambuf iterators are a special input iterator class designed to read successive elements from a stream buffer (streambuf or another basic_streambuf class).

They are constructed from a basic_streambuf object open for reading, to which they become associated.

A special value for this iterator exists: the end-of-stream; When an iterator is set to this value has either reached the end of the stream or has been constructed using its default constructor (without associating it with any basic_streambuf object).
This value can be used as the end of a range in any function accepting iterator ranges to indicate that the range includes all the elements up to the end of the input buffer.

It is defined with an operation similar to:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
template <class charT=char, class traits=char_traits<charT> >
  class istreambuf_iterator :
    public iterator<input_iterator_tag, charT,
                    typename traits::off_type, charT*, charT&>
{
public:
  typedef charT char_type;
  typedef traits traits_type;
  typedef typename traits::int_type int_type;
  typedef basic_streambuf<charT,traits> streambuf_type;
  typedef basic_istream<charT,traits> istream_type;

  class proxy {
    charT keep_; streambuf_type* sbuf_;
  public:
    proxy (charT c, streambuf_type* sbuf) : keep_(c), sbuf_(sbuf) { }
    charT operator*() {return keep_;}
  };

  istreambuf_iterator() throw() : sbuf_(0) { }
  istreambuf_iterator(istream_type& s) throw(): sbuf_(s.rdbuf()) { }
  istreambuf_iterator(streambuf_type* s) throw(): sbuf_(s) { }
  istreambuf_iterator(const proxy& p) throw(): sbuf_(p.sbuf_) { }

  charT operator*() const { return sbuf_->sgetc(); }
  istreambuf_iterator<charT,traits>& operator++() { sbuf_->sbumpc(); return *this; }
  proxy operator++(int) {return proxy(sbuf_->sbumpc(),sbuf_);}

  bool equal (istreambuf_iterator& b) const {
    if ( sbuf_==0 || *(*this)==traits::eof() ) 
    { if ( b.sbuf_==0 || *b==traits::eof() ) return true; }
    else if ( b.sbuf_!=0 && *b!= traits::eof() ) return true;
    return false;
  }

private:
  streambuf_type* sbuf_;
  
};


The <iterator> header file also defines two overloaded global operator functions (== and !=), which compare iterators: Two istreambuf_iterators compare equal if both are end-of-stream iterators or neither is, regardless of the streambuf object they use.

Template parameters

charT
Character type. This is the first template parameter in the basic_streambuf object.
traits
Character traits. This is the second template parameter in basic_streambuf object.


Member functions

constructor
istreambuf_iterator objects are constructed from either a basic_streambuf object or a basic_istream object.
The default constructor constructs an end-of-stream iterator and the copy constructor constructs a copy of the iterator passed as argument.
operator*
Returns the current value in the stream buffer.
operator++
Advances the position of the streambuf object by one element.
proxy
Temporary type returned by the post-increment operator (which can be implicitly converted to the class type). A member class is just one of the possible ways to preserve a streambuf_iterator value. Other implementations of istreambuf_iterator may not have this member class if they use an alternate method.


Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
// istreambuf_iterator example
#include <iostream>
#include <iterator>
#include <string>
using namespace std;

int main () {
  istreambuf_iterator<char> eos;               // end-of-range iterator
  istreambuf_iterator<char> iit (cin.rdbuf()); // stdin iterator
  string mystring;

  cout << "Please, enter your name: ";

  while (iit!=eos && *iit!='\n') mystring+=*iit++;

  cout << "Your name is " << mystring << ".\n";

  return 0;
}


Possible output:

Please, enter your name: HAL 9000
Your name is HAL 9000.


See also

ostreambuf_iterator Output stream buffer iterator (class template)
InputIterator Input iterator category
istream Input stream (class)