cppdraft_translate/cppdraft/stream/iterators.md

[stream.iterators]

24 Iterators library [iterators]

24.6 Stream iterators [stream.iterators]

24.6.1 General [stream.iterators.general]

1

#

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]

1

#

The class template istream_iterator is 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, 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; // exposition only T value; // exposition only};}

2

#

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);

1

#

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

2

#

Postconditions: in_stream == nullptr is true.

3

#

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);

4

#

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

🔗

constexpr istream_iterator(const istream_iterator& x) noexcept(see below);

5

#

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

6

#

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

The exception specification is equivalent tois_nothrow_copy_constructible_v.

🔗

~istream_iterator() = default;

7

#

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

24.6.2.3 Operations [istream.iterator.ops]

🔗

const T& operator*() const;

1

#

Preconditions: in_stream != nullptr is true.

2

#

Returns: value.

🔗

const T* operator->() const;

3

#

Preconditions: in_stream != nullptr is true.

4

#

Returns: addressof(value).

🔗

istream_iterator& operator++();

5

#

Preconditions: in_stream != nullptr is true.

6

#

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

7

#

Returns: *this.

🔗

istream_iterator operator++(int);

8

#

Preconditions: in_stream != nullptr is true.

9

#

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);

10

#

Returns: x.in_stream == y.in_stream.

🔗

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

11

#

Returns: !i.in_stream.

24.6.3 Class template ostream_iterator [ostream.iterator]

24.6.3.1 General [ostream.iterator.general]

1

#

ostream_iterator writes (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 everyT is written.

namespace std {template<class T, class charT = char, class traits = char_traits>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; // exposition onlyconst charT* delim; // exposition only};}

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

🔗

ostream_iterator(ostream_type& s);

1

#

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

🔗

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

2

#

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

24.6.3.3 Operations [ostream.iterator.ops]

🔗

ostream_iterator& operator=(const T& value);

1

#

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

🔗

ostream_iterator& operator*();

2

#

Returns: *this.

🔗

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

3

#

Returns: *this.

24.6.4 Class template istreambuf_iterator [istreambuf.iterator]

24.6.4.1 General [istreambuf.iterator.general]

1

#

The class templateistreambuf_iterator defines an input iterator that reads successivecharacters 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-stream iterator 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.

2

#

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

For any other iterator value achar_type value is returned.

It is impossible to assign a character via an input iterator.

🔗

namespace std {template<class charT, class traits = char_traits>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>; // [istreambuf.iterator.proxy], class istreambuf_iterator​::​proxyclass proxy; // exposition onlyconstexpr 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_; // exposition only};}

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

1

#

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 { // 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_; }};}

24.6.4.3 Constructors [istreambuf.iterator.cons]

1

#

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;

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

24.6.4.4 Operations [istreambuf.iterator.ops]

🔗

charT operator*() const;

1

#

Returns: The character obtained via thestreambuf membersbuf_->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 whatstreambuf 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).

🔗

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

7

#

Returns: i.equal(s).

24.6.5 Class template ostreambuf_iterator [ostreambuf.iterator]

24.6.5.1 General [ostreambuf.iterator.general]

1

#

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

🔗

namespace std {template<class charT, class traits = char_traits>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_; // exposition only};}

24.6.5.2 Constructors [ostreambuf.iter.cons]

🔗

ostreambuf_iterator(ostream_type& s) noexcept;

1

#

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

2

#

Effects: Initializes sbuf_ with s.rdbuf().

🔗

ostreambuf_iterator(streambuf_type* s) noexcept;

3

#

Preconditions: s is not a null pointer.

4

#

Effects: Initializes sbuf_ with s.

24.6.5.3 Operations [ostreambuf.iter.ops]

🔗

ostreambuf_iterator& operator=(charT c);

1

#

Effects: Iffailed() yieldsfalse, callssbuf_->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 memberoperator=, the call tosbuf_->sputc() returnedtraits​::​eof(); orfalse otherwise.