27 Iterators library [iterators]

27.6 Stream iterators [stream.iterators]

27.6.3 Class template istreambuf_­iterator [istreambuf.iterator]

1
#

The class template istreambuf_­iterator defines an input iterator that reads successive characters from the streambuf for which it was constructed. operator* provides access to the current input character, if any. 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:
    using iterator_category = input_iterator_tag;
    using value_type        = charT;
    using difference_type   = typename traits::off_type;
    using pointer           = unspecified;
    using reference         = charT;
    using char_type         = charT;
    using traits_type       = traits;
    using int_type          = typename traits::int_type;
    using streambuf_type    = basic_streambuf<charT,traits>;
    using istream_type      = basic_istream<charT,traits>;

    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;
    istreambuf_iterator& 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);
}

27.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 { // exposition only
    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.

27.6.3.2 istreambuf_­iterator constructors [istreambuf.iterator.cons]

1
#

For each istreambuf_­iterator constructor in this section, an end-of-stream iterator is constructed if and only if the exposition-only member sbuf_­ is initialized with a null pointer value.

constexpr istreambuf_iterator() noexcept;

2
#

Effects: Initializes sbuf_­ with nullptr.

istreambuf_iterator(istream_type& s) noexcept;

3
#

Effects: Initializes sbuf_­ with s.rdbuf().

istreambuf_iterator(streambuf_type* s) noexcept;

4
#

Effects: Initializes sbuf_­ with s.

istreambuf_iterator(const proxy& p) noexcept;

5
#

Effects: Initializes sbuf_­ with p.sbuf_­.

27.6.3.3 istreambuf_­iterator operations [istreambuf.iterator.ops]

charT operator*() const

1
#

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

istreambuf_iterator& operator++();

2
#

Effects: As if by sbuf_­->sbumpc().

3
#

Returns: *this.

proxy operator++(int);

4
#

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

bool equal(const istreambuf_iterator& b) const;

5
#

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.

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

6
#

Returns: a.equal(b).

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

7
#

Returns: !a.equal(b).