27 Iterators library [iterators]

27.6 Stream iterators [stream.iterators]

1
#
To make it possible for algorithmic templates to work directly with input/output streams, appropriate iterator-like class templates are provided.
[ Example
: 
partial_sum(istream_iterator<double, char>(cin),
  istream_iterator<double, char>(),
  ostream_iterator<double, char>(cout, "\n"));
reads a file containing floating-point numbers from cin, and prints the partial sums onto cout.
— end example
 ]

27.6.1 Class template istream_­iterator [istream.iterator]

1
#
The class template istream_­iterator is an input iterator ([input.iterators]) that reads (using operator>>) successive elements from the input stream for which it was constructed.
After it is constructed, and every time ++ is used, the iterator reads and stores a value of T.
If the iterator fails to read and store a value of T (fail() on the stream returns true), the iterator becomes equal to the end-of-stream iterator value.
The constructor with no arguments istream_­iterator() always constructs an end-of-stream input iterator object, which is the only legitimate iterator to be used for the end condition.
The result of operator* on an end-of-stream iterator is not defined.
For any other iterator value a const T& is returned.
The result of operator-> on an end-of-stream iterator is not defined.
For any other iterator value a const T* is returned.
The behavior of a program that applies operator++() to an end-of-stream iterator is undefined.
It is impossible to store things into istream iterators.
The type T shall meet the DefaultConstructible, CopyConstructible, and CopyAssignable requirements.
2
#
Two end-of-stream iterators are always equal.
An end-of-stream iterator is not equal to a non-end-of-stream iterator.
Two non-end-of-stream iterators are equal when they are constructed from the same stream.
namespace std {
  template <class T, class charT = char, class traits = char_traits<charT>,
      class Distance = ptrdiff_t>
  class istream_iterator {
  public:
    using iterator_category = input_iterator_tag;
    using value_type        = T;
    using difference_type   = Distance;
    using pointer           = const T*;
    using reference         = const T&;
    using char_type         = charT;
    using traits_type       = traits;
    using istream_type      = basic_istream<charT,traits>;

    constexpr istream_iterator();
    istream_iterator(istream_type& s);
    istream_iterator(const istream_iterator& x) = default;
    ~istream_iterator() = default;

    const T& operator*() const;
    const T* operator->() const;
    istream_iterator& operator++();
    istream_iterator  operator++(int);
  private:
    basic_istream<charT,traits>* in_stream; // exposition only
    T value;                                // exposition only
  };

  template <class T, class charT, class traits, class Distance>
    bool operator==(const istream_iterator<T,charT,traits,Distance>& x,
            const istream_iterator<T,charT,traits,Distance>& y);
  template <class T, class charT, class traits, class Distance>
    bool operator!=(const istream_iterator<T,charT,traits,Distance>& x,
            const istream_iterator<T,charT,traits,Distance>& y);
}

27.6.1.1 istream_­iterator constructors and destructor [istream.iterator.cons]

🔗
constexpr istream_iterator();
1
#
Effects: Constructs the end-of-stream iterator.
If is_­trivially_­default_­constructible_­v<T> is true, then this constructor is a constexpr constructor.
2
#
Postconditions: in_­stream == 0.
🔗
istream_iterator(istream_type& s);
3
#
Effects: Initializes in_­stream with addressof(s).
value may be initialized during construction or the first time it is referenced.
4
#
Postconditions: in_­stream == addressof(s).
🔗
istream_iterator(const istream_iterator& x) = default;
5
#
Effects: Constructs a copy of x.
If is_­trivially_­copy_­constructible_­v<T> is true, then this constructor is a trivial copy constructor.
6
#
Postconditions: in_­stream == x.in_­stream.
🔗
~istream_iterator() = default;
7
#
Effects: The iterator is destroyed.
If is_­trivially_­destructible_­v<T> is true, then this destructor is a trivial destructor.

27.6.1.2 istream_­iterator operations [istream.iterator.ops]

🔗
const T& operator*() const;
1
#
Returns: value.
🔗
const T* operator->() const;
2
#
Returns: addressof(operator*()).
🔗
istream_iterator& operator++();
3
#
Requires: in_­stream != 0.
4
#
Effects: As if by: *in_­stream >> value;
5
#
Returns: *this.
🔗
istream_iterator operator++(int);
6
#
Requires: in_­stream != 0.
7
#
Effects: As if by: 
istream_iterator tmp = *this;
*in_stream >> value;
return (tmp);
🔗
template <class T, class charT, class traits, class Distance> bool operator==(const istream_iterator<T,charT,traits,Distance>& x, const istream_iterator<T,charT,traits,Distance>& y);
8
#
Returns: x.in_­stream == y.in_­stream.
🔗
template <class T, class charT, class traits, class Distance> bool operator!=(const istream_iterator<T,charT,traits,Distance>& x, const istream_iterator<T,charT,traits,Distance>& y);
9
#
Returns: !(x == y)

27.6.2 Class template ostream_­iterator [ostream.iterator]

1
#
ostream_­iterator writes (using operator<<) successive elements onto the output stream from which it was constructed.
If it was constructed with charT* as a constructor argument, this string, called a delimiter string, is written to the stream after every T is written.
It is not possible to get a value out of the output iterator.
Its only use is as an output iterator in situations like
while (first != last)
  *result++ = *first++;
2
#
ostream_­iterator is defined as:
namespace std {
  template <class T, class charT = char, class traits = char_traits<charT>>
  class ostream_iterator {
  public:
    using iterator_category = output_iterator_tag;
    using value_type        = void;
    using difference_type   = void;
    using pointer           = void;
    using reference         = void;
    using char_type         = charT;
    using traits_type       = traits;
    using ostream_type      = basic_ostream<charT,traits>;

    ostream_iterator(ostream_type& s);
    ostream_iterator(ostream_type& s, const charT* delimiter);
    ostream_iterator(const ostream_iterator& x);
    ~ostream_iterator();
    ostream_iterator& operator=(const T& value);

    ostream_iterator& operator*();
    ostream_iterator& operator++();
    ostream_iterator& operator++(int);
  private:
    basic_ostream<charT,traits>* out_stream;  // exposition only
    const charT* delim;                       // exposition only
  };
}

27.6.2.1 ostream_­iterator constructors and destructor [ostream.iterator.cons.des]

🔗
ostream_iterator(ostream_type& s);
1
#
Effects: Initializes out_­stream with addressof(s) and delim with null.
🔗
ostream_iterator(ostream_type& s, const charT* delimiter);
2
#
Effects: Initializes out_­stream with addressof(s) and delim with delimiter.
🔗
ostream_iterator(const ostream_iterator& x);
3
#
Effects: Constructs a copy of x.
🔗
~ostream_iterator();
4
#
Effects: The iterator is destroyed.

27.6.2.2 ostream_­iterator operations [ostream.iterator.ops]

🔗
ostream_iterator& operator=(const T& value);
1
#
Effects: As if by: 
*out_stream << value;
if (delim != 0)
  *out_stream << delim;
return *this;
🔗
ostream_iterator& operator*();
2
#
Returns: *this.
🔗
ostream_iterator& operator++(); ostream_iterator& operator++(int);
3
#
Returns: *this.

27.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.
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).

27.6.4 Class template ostreambuf_­iterator [ostreambuf.iterator]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class ostreambuf_iterator {
  public:
    using iterator_category = output_iterator_tag;
    using value_type        = void;
    using difference_type   = void;
    using pointer           = void;
    using reference         = void;
    using char_type         = charT;
    using traits_type       = traits;
    using streambuf_type    = basic_streambuf<charT,traits>;
    using ostream_type      = basic_ostream<charT,traits>;

    ostreambuf_iterator(ostream_type& s) noexcept;
    ostreambuf_iterator(streambuf_type* s) noexcept;
    ostreambuf_iterator& operator=(charT c);

    ostreambuf_iterator& operator*();
    ostreambuf_iterator& operator++();
    ostreambuf_iterator& operator++(int);
    bool failed() const noexcept;

  private:
    streambuf_type* sbuf_;                // exposition only
  };
}
1
#
The class template ostreambuf_­iterator writes successive characters onto the output stream from which it was constructed.
It is not possible to get a character value out of the output iterator.

27.6.4.1 ostreambuf_­iterator constructors [ostreambuf.iter.cons]

🔗
ostreambuf_iterator(ostream_type& s) noexcept;
1
#
Requires: s.rdbuf() shall not be a null pointer.
2
#
Effects: Initializes sbuf_­ with s.rdbuf().
🔗
ostreambuf_iterator(streambuf_type* s) noexcept;
3
#
Requires: s shall not be a null pointer.
4
#
Effects: Initializes sbuf_­ with s.

27.6.4.2 ostreambuf_­iterator operations [ostreambuf.iter.ops]

🔗
ostreambuf_iterator& operator=(charT c);
1
#
Effects: If failed() yields false, calls sbuf_­->sputc(c); otherwise has no effect.
2
#
Returns: *this.
🔗
ostreambuf_iterator& operator*();
3
#
Returns: *this.
🔗
ostreambuf_iterator& operator++(); ostreambuf_iterator& operator++(int);
4
#
Returns: *this.
🔗
bool failed() const noexcept;
5
#
Returns: true if in any prior use of member operator=, the call to sbuf_­->sputc() returned traits​::​eof(); or false otherwise.