[stream.iterators] (original) (raw)

24 Iterators library [iterators]

24.6.1 General [stream.iterators.general]

24.6.2 Class template istream_iterator [istream.iterator]

24.6.2.1 General [istream.iterator.general]

24.6.2.2 Constructors and destructor [istream.iterator.cons]

24.6.2.3 Operations [istream.iterator.ops]

24.6.3 Class template ostream_iterator [ostream.iterator]

24.6.3.1 General [ostream.iterator.general]

24.6.3.2 Constructors and destructor [ostream.iterator.cons.des]

24.6.3.3 Operations [ostream.iterator.ops]

24.6.4 Class template istreambuf_iterator [istreambuf.iterator]

24.6.4.1 General [istreambuf.iterator.general]

24.6.4.2 Class istreambuf_iterator​::​proxy [istreambuf.iterator.proxy]

24.6.4.3 Constructors [istreambuf.iterator.cons]

24.6.4.4 Operations [istreambuf.iterator.ops]

24.6.5 Class template ostreambuf_iterator [ostreambuf.iterator]

24.6.5.1 General [ostreambuf.iterator.general]

24.6.5.2 Constructors [ostreambuf.iter.cons]

24.6.5.3 Operations [ostreambuf.iter.ops]

24.6.1 General [stream.iterators.general]

To make it possible for algorithmic templates to work directly with input/output streams, appropriate iterator-like class templates are provided.

[Example 1:

partial_sum(istream_iterator<double, char>(cin), istream_iterator<double, char>(), ostream_iterator<double, char>(cout, "\n"));reads a file containing floating-point numbers fromcin, and prints the partial sums ontocout.

— _end example_]

24.6.2 Class template istream_iterator [istream.iterator]

24.6.2.1 General [istream.iterator.general]

The class template istream_iteratoris an input iterator ([input.iterators]) that reads successive elements from the input stream for which it was constructed.

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();constexpr istream_iterator(default_sentinel_t); istream_iterator(istream_type& s);constexpr istream_iterator(const istream_iterator& x) noexcept(see below);~istream_iterator() = default; istream_iterator& operator=(const istream_iterator&) = default;const T& operator*() const;const T* operator->() const; istream_iterator& operator++(); istream_iterator operator++(int);friend bool operator==(const istream_iterator& i, default_sentinel_t);private: basic_istream<charT,traits>* in_stream; T value; };}

The type T shall meet the Cpp17DefaultConstructible,Cpp17CopyConstructible, and Cpp17CopyAssignable requirements.

24.6.2.2 Constructors and destructor [istream.iterator.cons]

constexpr istream_iterator();constexpr istream_iterator(default_sentinel_t);

Effects: Constructs the end-of-stream iterator, value-initializing value.

Postconditions: in_stream == nullptr is true.

Remarks: If the initializer T() in the declaration auto x = T();is a constant initializer ([expr.const]), then these constructors are constexpr constructors.

istream_iterator(istream_type& s);

Effects: Initializes in_stream with addressof(s), value-initializes value, and then calls operator++().

constexpr istream_iterator(const istream_iterator& x) noexcept(_see below_);

Effects: Initializes in_stream with x.in_stream and initializes value with x.value.

Remarks: An invocation of this constructor may be used in a core constant expression if and only if the initialization of value from x.valueis a constant subexpression ([defns.const.subexpr]).

The exception specification is equivalent tois_nothrow_copy_constructible_v<T>.

~istream_iterator() = default;

Remarks: If is_trivially_destructible_v<T> is true, then this destructor is trivial.

24.6.2.3 Operations [istream.iterator.ops]

const T& operator*() const;

Preconditions: in_stream != nullptr is true.

const T* operator->() const;

Preconditions: in_stream != nullptr is true.

Returns: addressof(value).

istream_iterator& operator++();

Preconditions: in_stream != nullptr is true.

Effects: Equivalent to:if (!(*in_stream >> value)) in_stream = nullptr;

istream_iterator operator++(int);

Preconditions: in_stream != nullptr is true.

Effects: Equivalent to:istream_iterator tmp = *this;++*this;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);

Returns: x.in_stream == y.in_stream.

friend bool operator==(const istream_iterator& i, default_sentinel_t);

24.6.3 Class template ostream_iterator [ostream.iterator]

24.6.3.1 General [ostream.iterator.general]

ostream_iteratorwrites (usingoperator<<) successive elements onto the output stream from which it was constructed.

If it was constructed withcharT*as a constructor argument, this string, called adelimiter string, is written to the stream after everyTis written.

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 = ptrdiff_t;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 ostream_iterator&) = default; ostream_iterator& operator=(const T& value); ostream_iterator& operator*(); ostream_iterator& operator++(); ostream_iterator& operator++(int);private: basic_ostream<charT,traits>* out_stream; const charT* delim; };}

24.6.3.2 Constructors and destructor [ostream.iterator.cons.des]

ostream_iterator(ostream_type& s);

Effects: Initializes out_stream with addressof(s) anddelim with nullptr.

ostream_iterator(ostream_type& s, const charT* delimiter);

Effects: Initializes out_stream with addressof(s) anddelim with delimiter.

24.6.3.3 Operations [ostream.iterator.ops]

ostream_iterator& operator=(const T& value);

Effects: As if by:*out_stream << value;if (delim) *out_stream << delim;return *this;

ostream_iterator& operator*();

ostream_iterator& operator++(); ostream_iterator& operator++(int);

24.6.4 Class template istreambuf_iterator [istreambuf.iterator]

24.6.4.1 General [istreambuf.iterator.general]

The class templateistreambuf_iteratordefines 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 timeoperator++is evaluated, the iterator advances to the next input character.

If the end of stream is reached (streambuf_type​::​sgetc() returnstraits​::​eof()), the iterator becomes equal to theend-of-streamiterator value.

The default constructoristreambuf_iterator()and the constructoristreambuf_iterator(nullptr)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.

The result ofoperator*()on an end-of-stream iterator is undefined.

For any other iterator value achar_typevalue 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 = traits::off_type;using pointer = unspecified;using reference = charT;using char_type = charT;using traits_type = traits;using int_type = traits::int_type;using streambuf_type = basic_streambuf<charT,traits>;using istream_type = basic_istream<charT,traits>;class proxy; constexpr istreambuf_iterator() noexcept;constexpr istreambuf_iterator(default_sentinel_t) 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; istreambuf_iterator& operator=(const istreambuf_iterator&) noexcept = default; charT operator*() const; istreambuf_iterator& operator++();proxy operator++(int);bool equal(const istreambuf_iterator& b) const;friend bool operator==(const istreambuf_iterator& i, default_sentinel_t s);private: streambuf_type* sbuf_; };}

24.6.4.2 Class istreambuf_iterator​::​proxy [istreambuf.iterator.proxy]

Classistreambuf_iterator<charT,traits>​::​_proxy_is for exposition only.

An implementation is permitted to provide equivalent functionality without providing a class with this name.

Classistreambuf_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.

namespace std { template<class charT, class traits> 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_; } };}

24.6.4.3 Constructors [istreambuf.iterator.cons]

For each istreambuf_iterator constructor in this subclause, 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;constexpr istreambuf_iterator(default_sentinel_t) noexcept;

Effects: Initializes sbuf_ with nullptr.

istreambuf_iterator(istream_type& s) noexcept;

Effects: Initializes sbuf_ with s.rdbuf().

istreambuf_iterator(streambuf_type* s) noexcept;

Effects: Initializes sbuf_ with s.

istreambuf_iterator(const _proxy_& p) noexcept;

Effects: Initializes sbuf_ with p.sbuf_.

24.6.4.4 Operations [istreambuf.iterator.ops]

Returns: The character obtained via thestreambufmembersbuf_->sgetc().

istreambuf_iterator& operator++();

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

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

bool equal(const istreambuf_iterator& b) const;

Returns: trueif and only if both iterators are at end-of-stream, or neither is at end-of-stream, regardless of whatstreambufobject they use.

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

friend bool operator==(const istreambuf_iterator& i, default_sentinel_t s);

24.6.5 Class template ostreambuf_iterator [ostreambuf.iterator]

24.6.5.1 General [ostreambuf.iterator.general]

The class template ostreambuf_iteratorwrites successive characters onto the output stream from which it was constructed.

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 = ptrdiff_t;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_; };}

24.6.5.2 Constructors [ostreambuf.iter.cons]

ostreambuf_iterator(ostream_type& s) noexcept;

Preconditions: s.rdbuf()is not a null pointer.

Effects: Initializes sbuf_ with s.rdbuf().

ostreambuf_iterator(streambuf_type* s) noexcept;

Preconditions: sis not a null pointer.

Effects: Initializes sbuf_ with s.

24.6.5.3 Operations [ostreambuf.iter.ops]

ostreambuf_iterator& operator=(charT c);

Effects: Iffailed()yieldsfalse, callssbuf_->sputc(c); otherwise has no effect.

ostreambuf_iterator& operator*();

ostreambuf_iterator& operator++(); ostreambuf_iterator& operator++(int);

bool failed() const noexcept;

Returns: trueif in any prior use of memberoperator=, the call tosbuf_->sputc()returnedtraits​::​eof(); orfalseotherwise.