class template
<iterator>

std::istreambuf_iterator

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

Istreambuf iterators are input iterators that read successive elements from a stream buffer.

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

This kind of iterator has a special state as an end-of-stream iterator, which is acquired when the end of the stream is reached, and is also the resulting value of a default-constructed 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 a behavior 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_;
  
};


Header <iterator> defines the comparison with operator== and operator!=: 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 types

memberdefinition in istreambuf_iteratordescription
streambuf_typebasic_streambuf<charT,traits>Type of the associated basic_streambuf object
istream_typebasic_istream<charT,traits>
iterator_categoryinput_iterator_tagInput iterator
value_typeTType of the elements pointed by the iterator
char_typecharTType of the characters handled by the associated stream buffer
traits_typetraitsCharacter traits for associated stream buffer
int_typetraits::int_typeInt type to represent character values or end-of-file
difference_typetraits::off_type
pointercharT*
referencecharT&
memberdefinition in istreambuf_iteratordescription
streambuf_typebasic_streambuf<charT,traits>Type of the associated basic_streambuf object
istream_typebasic_istream<charT,traits>
iterator_categoryinput_iterator_tagInput iterator
value_typeTType of the elements pointed by the iterator
char_typecharTType of the characters handled by the associated stream buffer
traits_typetraitsCharacter traits for associated stream buffer
int_typetraits::int_typeInt type to represent character values or end-of-file
difference_typetraits::off_type
pointerunspecified
referencecharT

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 basic_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. Some 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
// istreambuf_iterator example
#include <iostream>     // std::cin, std::cout
#include <iterator>     // std::istreambuf_iterator
#include <string>       // std::string

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

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

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

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

  return 0;
}


Possible output:

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

See also