24 Iterators library [iterators]

24.6 Stream iterators [stream.iterators]

24.6.3 Class template istreambuf_iterator [istreambuf.iterator]

1

The class template istreambuf_iterator defines an input iterator ([input.iterators]) that reads successive characters from the streambuf for which it was constructed. operator* provides access to the current input character, if any. [ Note: operator-> may return a proxy.  — end note ] Each time operator++ is evaluated, the iterator advances to the next input character. If the end of stream is reached (streambuf_type::sgetc() returns traits::eof()), the iterator becomes equal to the end-of-stream iterator value. The default constructor istreambuf_iterator() and the constructor istreambuf_iterator(0) both construct an end-of-stream iterator object suitable for use as an end-of-range. All specializations of istreambuf_iterator shall have a trivial copy constructor, a constexpr default constructor, and a trivial destructor.

2

The result of operator*() on an end-of-stream iterator is undefined. For any other iterator value a char_type value is returned. It is impossible to assign a character via an input iterator.

namespace std {
  template<class charT, class traits = char_traits<charT> >
  class istreambuf_iterator
     : public iterator<input_iterator_tag, charT,
                       typename traits::off_type, unspecified, 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;                          // exposition only

    constexpr istreambuf_iterator() noexcept;
    istreambuf_iterator(const istreambuf_iterator&) noexcept = default;
    ~istreambuf_iterator() = default;
    istreambuf_iterator(istream_type& s) noexcept;
    istreambuf_iterator(streambuf_type* s) noexcept;
    istreambuf_iterator(const proxy& p) noexcept;
    charT operator*() const;
    pointer operator->() const;
    istreambuf_iterator<charT,traits>& operator++();
    proxy operator++(int);
    bool equal(const istreambuf_iterator& b) const;
  private:
    streambuf_type* sbuf_;                // exposition only
  };

  template <class charT, class traits>
    bool operator==(const istreambuf_iterator<charT,traits>& a,
            const istreambuf_iterator<charT,traits>& b);
  template <class charT, class traits>
    bool operator!=(const istreambuf_iterator<charT,traits>& a,
            const istreambuf_iterator<charT,traits>& b);
}

24.6.3.1 Class template istreambuf_iterator::proxy [istreambuf.iterator::proxy]

namespace std {
  template <class charT, class traits = char_traits<charT> >
  class istreambuf_iterator<charT, traits>::proxy {
    charT keep_;
    basic_streambuf<charT,traits>* sbuf_;
    proxy(charT c,
      basic_streambuf<charT,traits>* sbuf)
      : keep_(c), sbuf_(sbuf) { }
  public:
    charT operator*() { return keep_; }
  };
}
1

Class istreambuf_iterator<charT,traits>::proxy is for exposition only. An implementation is permitted to provide equivalent functionality without providing a class with this name. Class istreambuf_iterator<charT, traits>::proxy provides a temporary placeholder as the return value of the post-increment operator (operator++). It keeps the character pointed to by the previous value of the iterator for some possible future access to get the character.

24.6.3.2 istreambuf_iterator constructors [istreambuf.iterator.cons]

constexpr istreambuf_iterator() noexcept;

1

Effects: Constructs the end-of-stream iterator.

istreambuf_iterator(basic_istream<charT,traits>& s) noexcept; istreambuf_iterator(basic_streambuf<charT,traits>* s) noexcept;

2

Effects: Constructs an istreambuf_iterator<> that uses the basic_streambuf<> object *(s.rdbuf()), or *s, respectively. Constructs an end-of-stream iterator if s.rdbuf() is null.

istreambuf_iterator(const proxy& p) noexcept;

3

Effects: Constructs a istreambuf_iterator<> that uses the basic_streambuf<> object pointed to by the proxy object's constructor argument p.

24.6.3.3 istreambuf_iterator::operator* [istreambuf.iterator::op*]

charT operator*() const

1

Returns: The character obtained via the streambuf member sbuf_->sgetc().

24.6.3.4 istreambuf_iterator::operator++ [istreambuf.iterator::op++]

istreambuf_iterator<charT,traits>& istreambuf_iterator<charT,traits>::operator++();

1

Effects: sbuf_->sbumpc().

2

Returns: *this.

proxy istreambuf_iterator<charT,traits>::operator++(int);

3

Returns: proxy(sbuf_->sbumpc(), sbuf_).

24.6.3.5 istreambuf_iterator::equal [istreambuf.iterator::equal]

bool equal(const istreambuf_iterator<charT,traits>& b) const;

1

Returns: true if and only if both iterators are at end-of-stream, or neither is at end-of-stream, regardless of what streambuf object they use.

24.6.3.6 operator== [istreambuf.iterator::op==]

template <class charT, class traits> bool operator==(const istreambuf_iterator<charT,traits>& a, const istreambuf_iterator<charT,traits>& b);

1

Returns: a.equal(b).

24.6.3.7 operator!= [istreambuf.iterator::op!=]

template <class charT, class traits> bool operator!=(const istreambuf_iterator<charT,traits>& a, const istreambuf_iterator<charT,traits>& b);

1

Returns: !a.equal(b).