From Jason Turner

[iterators]

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpp1gp4c30/{from.md → to.md} +594 -498
tmp/tmpp1gp4c30/{from.md → to.md} RENAMED
@@ -27,16 +27,16 @@ summarized in Table  [[tab:iterators.lib.summary]].
27
  Iterators are a generalization of pointers that allow a C++program to
28
  work with different data structures (containers) in a uniform manner. To
29
  be able to construct template algorithms that work correctly and
30
  efficiently on different types of data structures, the library
31
  formalizes not just the interfaces but also the semantics and complexity
32
- assumptions of iterators. All input iterators `i` support the expression
33
  `*i`, resulting in a value of some object type `T`, called the *value
34
- type* of the iterator. All output iterators support the expression
35
- `*i = o` where `o` is a value of some type that is in the set of types
36
- that are *writable* to the particular iterator type of `i`. All
37
- iterators `i` for which the expression `(*i).m` is well-defined, support
38
  the expression `i->m` with the same semantics as `(*i).m`. For every
39
  iterator type `X` for which equality is defined, there is a
40
  corresponding signed integer type called the *difference type* of the
41
  iterator.
42
 
@@ -63,33 +63,58 @@ iterators also satisfy all the requirements of forward iterators and can
63
  be used whenever a forward iterator is specified; Random access
64
  iterators also satisfy all the requirements of bidirectional iterators
65
  and can be used whenever a bidirectional iterator is specified.
66
 
67
  Iterators that further satisfy the requirements of output iterators are
68
- called *mutable iterator*s. Nonmutable iterators are referred to as
69
- *constant iterator*s.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
70
 
71
  Just as a regular pointer to an array guarantees that there is a pointer
72
  value pointing past the last element of the array, so for any iterator
73
  type there is an iterator value that points past the last element of a
74
  corresponding sequence. These values are called *past-the-end* values.
75
  Values of an iterator `i` for which the expression `*i` is defined are
76
  called *dereferenceable*. The library never assumes that past-the-end
77
  values are dereferenceable. Iterators can also have singular values that
78
- are not associated with any sequence. After the declaration of an
79
- uninitialized pointer `x` (as with `int* x;`), `x` must always be
80
- assumed to have a singular value of a pointer. Results of most
81
- expressions are undefined for singular values; the only exceptions are
82
- destroying an iterator that holds a singular value, the assignment of a
83
- non-singular value to an iterator that holds a singular value, and, for
84
- iterators that satisfy the `DefaultConstructible` requirements, using a
85
- value-initialized iterator as the source of a copy or move operation.
86
- This guarantee is not offered for default initialization, although the
87
- distinction only matters for types with trivial default constructors
88
- such as pointers or aggregates holding pointers. In these cases the
89
- singular value is overwritten the same way as any other value.
90
- Dereferenceable values are always non-singular.
 
 
 
 
 
 
 
91
 
92
  An iterator `j` is called *reachable* from an iterator `i` if and only
93
  if there is a finite sequence of applications of the expression `++i`
94
  that makes `i == j`. If `j` is reachable from `i`, they refer to
95
  elements of the same sequence.
@@ -117,23 +142,24 @@ In the following sections, `a` and `b` denote values of type `X` or
117
  `const X`, `difference_type` and `reference` refer to the types
118
  `iterator_traits<X>::difference_type` and
119
  `iterator_traits<X>::reference`, respectively, `n` denotes a value of
120
  `difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
121
  value of `X&`, `t` denotes a value of value type `T`, `o` denotes a
122
- value of some type that is writable to the output iterator. For an
123
- iterator type `X` there must be an instantiation of
124
- `iterator_traits<X>` ([[iterator.traits]]).
 
125
 
126
  ### Iterator <a id="iterator.iterators">[[iterator.iterators]]</a>
127
 
128
  The `Iterator` requirements form the basis of the iterator concept
129
  taxonomy; every iterator satisfies the `Iterator` requirements. This set
130
  of requirements specifies operations for dereferencing and incrementing
131
  an iterator. Most algorithms will require additional operations to
132
  read ([[input.iterators]]) or write ([[output.iterators]]) values, or
133
  to provide a richer set of iterator movements ([[forward.iterators]],
134
- [[bidirectional.iterators]], [[random.access.iterators]]).)
135
 
136
  A type `X` satisfies the `Iterator` requirements if:
137
 
138
  - `X` satisfies the `CopyConstructible`, `CopyAssignable`, and
139
  `Destructible` requirements ([[utility.arg.requirements]]) and
@@ -142,85 +168,89 @@ A type `X` satisfies the `Iterator` requirements if:
142
  have the indicated semantics.
143
 
144
  ### Input iterators <a id="input.iterators">[[input.iterators]]</a>
145
 
146
  A class or pointer type `X` satisfies the requirements of an input
147
- iterator for the value type `T` if X satisfies the `Iterator` (
148
  [[iterator.iterators]]) and `EqualityComparable` (Table 
149
- [[equalitycomparable]]) requirements and the expressions in Table 
150
  [[tab:iterator.input.requirements]] are valid and have the indicated
151
  semantics.
152
 
153
  In Table  [[tab:iterator.input.requirements]], the term *the domain of
154
  `==`* is used in the ordinary mathematical sense to denote the set of
155
  values over which `==` is (required to be) defined. This set can change
156
  over time. Each algorithm places additional requirements on the domain
157
  of `==` for the iterator values it uses. These requirements can be
158
- inferred from the uses that algorithm makes of `==` and `!=`. the call
159
- `find(a,b,x)` is defined only if the value of `a` has the property *p*
160
- defined as follows: `b` has property *p* and a value `i` has property
161
- *p* if `(*i==x)` or if `(*i!=x` and `++i` has property `p`).
162
 
163
- For input iterators, `a == b` does not imply `++a == ++b`. (Equality
164
- does not guarantee the substitution property or referential
 
 
 
 
 
165
  transparency.) Algorithms on input iterators should never attempt to
166
  pass through the same iterator twice. They should be *single pass*
167
- algorithms. Value type T is not required to be a `CopyAssignable` type
168
- (Table  [[copyassignable]]). These algorithms can be used with istreams
169
- as the source of the input data through the `istream_iterator` class
170
- template.
171
 
172
  ### Output iterators <a id="output.iterators">[[output.iterators]]</a>
173
 
174
  A class or pointer type `X` satisfies the requirements of an output
175
  iterator if `X` satisfies the `Iterator` requirements (
176
  [[iterator.iterators]]) and the expressions in Table 
177
  [[tab:iterator.output.requirements]] are valid and have the indicated
178
  semantics.
179
 
180
- The only valid use of an `operator*` is on the left side of the
181
- assignment statement. *Assignment through the same value of the iterator
182
- happens only once.* Algorithms on output iterators should never attempt
183
- to pass through the same iterator twice. They should be *single pass*
184
- algorithms. Equality and inequality might not be defined. Algorithms
185
- that take output iterators can be used with ostreams as the destination
186
- for placing data through the `ostream_iterator` class as well as with
187
- insert iterators and insert pointers.
188
 
189
  ### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
190
 
191
  A class or pointer type `X` satisfies the requirements of a forward
192
  iterator if
193
 
194
  - `X` satisfies the requirements of an input iterator (
195
  [[input.iterators]]),
196
- - X satisfies the `DefaultConstructible` requirements (
197
  [[utility.arg.requirements]]),
198
  - if `X` is a mutable iterator, `reference` is a reference to `T`; if
199
- `X` is a const iterator, `reference` is a reference to `const T`,
200
  - the expressions in Table  [[tab:iterator.forward.requirements]] are
201
  valid and have the indicated semantics, and
202
  - objects of type `X` offer the multi-pass guarantee, described below.
203
 
204
- The domain of == for forward iterators is that of iterators over the
205
  same underlying sequence. However, value-initialized iterators may be
206
  compared and shall compare equal to other value-initialized iterators of
207
- the same type. value initialized iterators behave as if they refer past
208
- the end of the same empty sequence
 
 
209
 
210
  Two dereferenceable iterators `a` and `b` of type `X` offer the
211
  *multi-pass guarantee* if:
212
 
213
  - `a == b` implies `++a == ++b` and
214
  - `X` is a pointer type or the expression `(void)++X(a), *a` is
215
  equivalent to the expression `*a`.
216
 
217
- The requirement that `a == b` implies `++a == ++b` (which is not true
218
- for input and output iterators) and the removal of the restrictions on
219
- the number of the assignments through a mutable iterator (which applies
220
- to output iterators) allows the use of multi-pass one-directional
221
- algorithms with forward iterators.
222
 
223
  If `a` and `b` are equal, then either `a` and `b` are both
224
  dereferenceable or else neither is dereferenceable.
225
 
226
  If `a` and `b` are both dereferenceable, then `a == b` if and only if
@@ -231,12 +261,12 @@ If `a` and `b` are both dereferenceable, then `a == b` if and only if
231
  A class or pointer type `X` satisfies the requirements of a
232
  bidirectional iterator if, in addition to satisfying the requirements
233
  for forward iterators, the following expressions are valid as shown in
234
  Table  [[tab:iterator.bidirectional.requirements]].
235
 
236
- Bidirectional iterators allow algorithms to move iterators backward as
237
- well as forward.
238
 
239
  ### Random access iterators <a id="random.access.iterators">[[random.access.iterators]]</a>
240
 
241
  A class or pointer type `X` satisfies the requirements of a random
242
  access iterator if, in addition to satisfying the requirements for
@@ -245,76 +275,74 @@ Table  [[tab:iterator.random.access.requirements]].
245
 
246
  ## Header `<iterator>` synopsis <a id="iterator.synopsis">[[iterator.synopsis]]</a>
247
 
248
  ``` cpp
249
  namespace std {
250
- // [iterator.primitives], primitives:
251
  template<class Iterator> struct iterator_traits;
252
  template<class T> struct iterator_traits<T*>;
253
-
254
- template<class Category, class T, class Distance = ptrdiff_t,
255
- class Pointer = T*, class Reference = T&> struct iterator;
256
 
257
  struct input_iterator_tag { };
258
  struct output_iterator_tag { };
259
  struct forward_iterator_tag: public input_iterator_tag { };
260
  struct bidirectional_iterator_tag: public forward_iterator_tag { };
261
  struct random_access_iterator_tag: public bidirectional_iterator_tag { };
262
 
263
- // [iterator.operations], iterator operations:
264
  template <class InputIterator, class Distance>
265
- void advance(InputIterator& i, Distance n);
266
  template <class InputIterator>
267
- typename iterator_traits<InputIterator>::difference_type
268
  distance(InputIterator first, InputIterator last);
269
- template <class ForwardIterator>
270
- ForwardIterator next(ForwardIterator x,
271
- typename std::iterator_traits<ForwardIterator>::difference_type n = 1);
272
  template <class BidirectionalIterator>
273
- BidirectionalIterator prev(BidirectionalIterator x,
274
- typename std::iterator_traits<BidirectionalIterator>::difference_type n = 1);
275
 
276
- // [predef.iterators], predefined iterators:
277
  template <class Iterator> class reverse_iterator;
278
 
279
  template <class Iterator1, class Iterator2>
280
- bool operator==(
281
  const reverse_iterator<Iterator1>& x,
282
  const reverse_iterator<Iterator2>& y);
283
  template <class Iterator1, class Iterator2>
284
- bool operator<(
285
  const reverse_iterator<Iterator1>& x,
286
  const reverse_iterator<Iterator2>& y);
287
  template <class Iterator1, class Iterator2>
288
- bool operator!=(
289
  const reverse_iterator<Iterator1>& x,
290
  const reverse_iterator<Iterator2>& y);
291
  template <class Iterator1, class Iterator2>
292
- bool operator>(
293
  const reverse_iterator<Iterator1>& x,
294
  const reverse_iterator<Iterator2>& y);
295
  template <class Iterator1, class Iterator2>
296
- bool operator>=(
297
  const reverse_iterator<Iterator1>& x,
298
  const reverse_iterator<Iterator2>& y);
299
  template <class Iterator1, class Iterator2>
300
- bool operator<=(
301
  const reverse_iterator<Iterator1>& x,
302
  const reverse_iterator<Iterator2>& y);
303
 
304
  template <class Iterator1, class Iterator2>
305
- auto operator-(
306
  const reverse_iterator<Iterator1>& x,
307
  const reverse_iterator<Iterator2>& y) ->decltype(y.base() - x.base());
308
  template <class Iterator>
309
- reverse_iterator<Iterator>
310
  operator+(
311
  typename reverse_iterator<Iterator>::difference_type n,
312
  const reverse_iterator<Iterator>& x);
313
 
314
  template <class Iterator>
315
- reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
316
 
317
  template <class Container> class back_insert_iterator;
318
  template <class Container>
319
  back_insert_iterator<Container> back_inserter(Container& x);
320
 
@@ -326,39 +354,39 @@ namespace std {
326
  template <class Container>
327
  insert_iterator<Container> inserter(Container& x, typename Container::iterator i);
328
 
329
  template <class Iterator> class move_iterator;
330
  template <class Iterator1, class Iterator2>
331
- bool operator==(
332
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
333
  template <class Iterator1, class Iterator2>
334
- bool operator!=(
335
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
336
  template <class Iterator1, class Iterator2>
337
- bool operator<(
338
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
339
  template <class Iterator1, class Iterator2>
340
- bool operator<=(
341
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
342
  template <class Iterator1, class Iterator2>
343
- bool operator>(
344
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
345
  template <class Iterator1, class Iterator2>
346
- bool operator>=(
347
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
348
 
349
  template <class Iterator1, class Iterator2>
350
- auto operator-(
351
  const move_iterator<Iterator1>& x,
352
  const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
353
  template <class Iterator>
354
- move_iterator<Iterator> operator+(
355
  typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
356
  template <class Iterator>
357
- move_iterator<Iterator> make_move_iterator(Iterator i);
358
 
359
- // [stream.iterators], stream iterators:
360
  template <class T, class charT = char, class traits = char_traits<charT>,
361
  class Distance = ptrdiff_t>
362
  class istream_iterator;
363
  template <class T, class charT, class traits, class Distance>
364
  bool operator==(const istream_iterator<T,charT,traits,Distance>& x,
@@ -380,31 +408,42 @@ namespace std {
380
  const istreambuf_iterator<charT,traits>& b);
381
 
382
  template <class charT, class traits = char_traits<charT>>
383
  class ostreambuf_iterator;
384
 
385
- // [iterator.range], range access:
386
- template <class C> auto begin(C& c) -> decltype(c.begin());
387
- template <class C> auto begin(const C& c) -> decltype(c.begin());
388
- template <class C> auto end(C& c) -> decltype(c.end());
389
- template <class C> auto end(const C& c) -> decltype(c.end());
390
  template <class T, size_t N> constexpr T* begin(T (&array)[N]) noexcept;
391
  template <class T, size_t N> constexpr T* end(T (&array)[N]) noexcept;
392
  template <class C> constexpr auto cbegin(const C& c) noexcept(noexcept(std::begin(c)))
393
  -> decltype(std::begin(c));
394
  template <class C> constexpr auto cend(const C& c) noexcept(noexcept(std::end(c)))
395
  -> decltype(std::end(c));
396
- template <class C> auto rbegin(C& c) -> decltype(c.rbegin());
397
- template <class C> auto rbegin(const C& c) -> decltype(c.rbegin());
398
- template <class C> auto rend(C& c) -> decltype(c.rend());
399
- template <class C> auto rend(const C& c) -> decltype(c.rend());
400
- template <class T, size_t N> reverse_iterator<T*> rbegin(T (&array)[N]);
401
- template <class T, size_t N> reverse_iterator<T*> rend(T (&array)[N]);
402
- template <class E> reverse_iterator<const E*> rbegin(initializer_list<E> il);
403
- template <class E> reverse_iterator<const E*> rend(initializer_list<E> il);
404
- template <class C> auto crbegin(const C& c) -> decltype(std::rbegin(c));
405
- template <class C> auto crend(const C& c) -> decltype(std::rend(c));
 
 
 
 
 
 
 
 
 
 
 
406
  }
407
  ```
408
 
409
  ## Iterator primitives <a id="iterator.primitives">[[iterator.primitives]]</a>
410
 
@@ -443,52 +482,56 @@ iterator_traits<Iterator>::reference
443
  iterator_traits<Iterator>::pointer
444
  ```
445
 
446
  may be defined as `void`.
447
 
448
- The template `iterator_traits<Iterator>` is defined as
 
 
 
449
 
450
  ``` cpp
451
- namespace std {
452
- template<class Iterator> struct iterator_traits {
453
- typedef typename Iterator::difference_type difference_type;
454
- typedef typename Iterator::value_type value_type;
455
- typedef typename Iterator::pointer pointer;
456
- typedef typename Iterator::reference reference;
457
- typedef typename Iterator::iterator_category iterator_category;
458
- };
459
- }
460
  ```
461
 
 
 
 
462
  It is specialized for pointers as
463
 
464
  ``` cpp
465
  namespace std {
466
  template<class T> struct iterator_traits<T*> {
467
- typedef ptrdiff_t difference_type;
468
- typedef T value_type;
469
- typedef T* pointer;
470
- typedef T& reference;
471
- typedef random_access_iterator_tag iterator_category;
472
  };
473
  }
474
  ```
475
 
476
  and for pointers to const as
477
 
478
  ``` cpp
479
  namespace std {
480
  template<class T> struct iterator_traits<const T*> {
481
- typedef ptrdiff_t difference_type;
482
- typedef T value_type;
483
- typedef const T* pointer;
484
- typedef const T& reference;
485
- typedef random_access_iterator_tag iterator_category;
486
  };
487
  }
488
  ```
489
 
 
 
490
  To implement a generic `reverse` function, a C++program can do the
491
  following:
492
 
493
  ``` cpp
494
  template <class BidirectionalIterator>
@@ -504,28 +547,11 @@ void reverse(BidirectionalIterator first, BidirectionalIterator last) {
504
  n -= 2;
505
  }
506
  }
507
  ```
508
 
509
- ### Basic iterator <a id="iterator.basic">[[iterator.basic]]</a>
510
-
511
- The `iterator` template may be used as a base class to ease the
512
- definition of required types for new iterators.
513
-
514
- ``` cpp
515
- namespace std {
516
- template<class Category, class T, class Distance = ptrdiff_t,
517
- class Pointer = T*, class Reference = T&>
518
- struct iterator {
519
- typedef T value_type;
520
- typedef Distance difference_type;
521
- typedef Pointer pointer;
522
- typedef Reference reference;
523
- typedef Category iterator_category;
524
- };
525
- }
526
- ```
527
 
528
  ### Standard iterator tags <a id="std.iterator.tags">[[std.iterator.tags]]</a>
529
 
530
  It is often desirable for a function template specialization to find out
531
  what is the most specific category of its iterator argument, so that the
@@ -546,26 +572,29 @@ namespace std {
546
  struct bidirectional_iterator_tag: public forward_iterator_tag { };
547
  struct random_access_iterator_tag: public bidirectional_iterator_tag { };
548
  }
549
  ```
550
 
 
 
551
  For a program-defined iterator `BinaryTreeIterator`, it could be
552
  included into the bidirectional iterator category by specializing the
553
  `iterator_traits` template:
554
 
555
  ``` cpp
556
  template<class T> struct iterator_traits<BinaryTreeIterator<T>> {
557
- typedef std::ptrdiff_t difference_type;
558
- typedef T value_type;
559
- typedef T* pointer;
560
- typedef T& reference;
561
- typedef bidirectional_iterator_tag iterator_category;
562
  };
563
  ```
564
 
565
- Typically, however, it would be easier to derive `BinaryTreeIterator<T>`
566
- from `iterator<bidirectional_iterator_tag,T,ptrdiff_t,T*,T&>`.
 
567
 
568
  If `evolve()` is well defined for bidirectional iterators, but can be
569
  implemented more efficiently for random access iterators, then the
570
  implementation is as follows:
571
 
@@ -588,22 +617,11 @@ void evolve(RandomAccessIterator first, RandomAccessIterator last,
588
  random_access_iterator_tag) {
589
  // more efficient, but less generic algorithm
590
  }
591
  ```
592
 
593
- If a C++program wants to define a bidirectional iterator for some data
594
- structure containing `double` and such that it works on a large memory
595
- model of the implementation, it can do so with:
596
-
597
- ``` cpp
598
- class MyIterator :
599
- public iterator<bidirectional_iterator_tag, double, long, T*, T&> {
600
- // code implementing ++, etc.
601
- };
602
- ```
603
-
604
- Then there is no need to specialize the `iterator_traits` template.
605
 
606
  ### Iterator operations <a id="iterator.operations">[[iterator.operations]]</a>
607
 
608
  Since only random access iterators provide `+` and `-` operators, the
609
  library provides two function templates `advance` and `distance`. These
@@ -611,22 +629,22 @@ function templates use `+` and `-` for random access iterators (and are,
611
  therefore, constant time for them); for input, forward and bidirectional
612
  iterators they use `++` to provide linear time implementations.
613
 
614
  ``` cpp
615
  template <class InputIterator, class Distance>
616
- void advance(InputIterator& i, Distance n);
617
  ```
618
 
619
  *Requires:* `n` shall be negative only for bidirectional and random
620
  access iterators.
621
 
622
  *Effects:* Increments (or decrements for negative `n`) iterator
623
  reference `i` by `n`.
624
 
625
  ``` cpp
626
  template <class InputIterator>
627
- typename iterator_traits<InputIterator>::difference_type
628
  distance(InputIterator first, InputIterator last);
629
  ```
630
 
631
  *Effects:* If `InputIterator` meets the requirements of random access
632
  iterator, returns `(last - first)`; otherwise, returns the number of
@@ -636,24 +654,24 @@ increments needed to get from `first` to `last`.
636
  iterator, `last` shall be reachable from `first` or `first` shall be
637
  reachable from `last`; otherwise, `last` shall be reachable from
638
  `first`.
639
 
640
  ``` cpp
641
- template <class ForwardIterator>
642
- ForwardIterator next(ForwardIterator x,
643
- typename std::iterator_traits<ForwardIterator>::difference_type n = 1);
644
  ```
645
 
646
- *Effects:* Equivalent to `advance(x, n); return x;`
647
 
648
  ``` cpp
649
  template <class BidirectionalIterator>
650
- BidirectionalIterator prev(BidirectionalIterator x,
651
- typename std::iterator_traits<BidirectionalIterator>::difference_type n = 1);
652
  ```
653
 
654
- *Effects:* Equivalent to `advance(x, -n); return x;`
655
 
656
  ## Iterator adaptors <a id="predef.iterators">[[predef.iterators]]</a>
657
 
658
  ### Reverse iterators <a id="reverse.iterators">[[reverse.iterators]]</a>
659
 
@@ -666,94 +684,91 @@ identity: `&*(reverse_iterator(i)) == &*(i - 1)`.
666
  #### Class template `reverse_iterator` <a id="reverse.iterator">[[reverse.iterator]]</a>
667
 
668
  ``` cpp
669
  namespace std {
670
  template <class Iterator>
671
- class reverse_iterator : public
672
- iterator<typename iterator_traits<Iterator>::iterator_category,
673
- typename iterator_traits<Iterator>::value_type,
674
- typename iterator_traits<Iterator>::difference_type,
675
- typename iterator_traits<Iterator>::pointer,
676
- typename iterator_traits<Iterator>::reference> {
677
  public:
678
- typedef Iterator iterator_type;
679
- typedef typename iterator_traits<Iterator>::difference_type difference_type;
680
- typedef typename iterator_traits<Iterator>::reference reference;
681
- typedef typename iterator_traits<Iterator>::pointer pointer;
 
 
682
 
683
- reverse_iterator();
684
- explicit reverse_iterator(Iterator x);
685
- template <class U> reverse_iterator(const reverse_iterator<U>& u);
686
- template <class U> reverse_iterator& operator=(const reverse_iterator<U>& u);
687
 
688
- Iterator base() const; // explicit
689
- reference operator*() const;
690
- pointer operator->() const;
691
 
692
- reverse_iterator& operator++();
693
- reverse_iterator operator++(int);
694
- reverse_iterator& operator--();
695
- reverse_iterator operator--(int);
696
 
697
- reverse_iterator operator+ (difference_type n) const;
698
- reverse_iterator& operator+=(difference_type n);
699
- reverse_iterator operator- (difference_type n) const;
700
- reverse_iterator& operator-=(difference_type n);
701
- unspecified operator[](difference_type n) const;
702
  protected:
703
  Iterator current;
704
  };
705
 
706
  template <class Iterator1, class Iterator2>
707
- bool operator==(
708
  const reverse_iterator<Iterator1>& x,
709
  const reverse_iterator<Iterator2>& y);
710
  template <class Iterator1, class Iterator2>
711
- bool operator<(
712
  const reverse_iterator<Iterator1>& x,
713
  const reverse_iterator<Iterator2>& y);
714
  template <class Iterator1, class Iterator2>
715
- bool operator!=(
716
  const reverse_iterator<Iterator1>& x,
717
  const reverse_iterator<Iterator2>& y);
718
  template <class Iterator1, class Iterator2>
719
- bool operator>(
720
  const reverse_iterator<Iterator1>& x,
721
  const reverse_iterator<Iterator2>& y);
722
  template <class Iterator1, class Iterator2>
723
- bool operator>=(
724
  const reverse_iterator<Iterator1>& x,
725
  const reverse_iterator<Iterator2>& y);
726
  template <class Iterator1, class Iterator2>
727
- bool operator<=(
728
  const reverse_iterator<Iterator1>& x,
729
  const reverse_iterator<Iterator2>& y);
730
  template <class Iterator1, class Iterator2>
731
- auto operator-(
732
  const reverse_iterator<Iterator1>& x,
733
  const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
734
  template <class Iterator>
735
- reverse_iterator<Iterator> operator+(
736
  typename reverse_iterator<Iterator>::difference_type n,
737
  const reverse_iterator<Iterator>& x);
738
 
739
  template <class Iterator>
740
- reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
741
  }
742
  ```
743
 
744
  #### `reverse_iterator` requirements <a id="reverse.iter.requirements">[[reverse.iter.requirements]]</a>
745
 
746
  The template parameter `Iterator` shall meet all the requirements of a
747
  Bidirectional Iterator ([[bidirectional.iterators]]).
748
 
749
- Additionally, `Iterator` shall meet the requirements of a Random Access
750
- Iterator ([[random.access.iterators]]) if any of the members
751
  `operator+` ([[reverse.iter.op+]]), `operator-` (
752
  [[reverse.iter.op-]]), `operator+=` ([[reverse.iter.op+=]]),
753
  `operator-=` ([[reverse.iter.op-=]]), `operator[]` (
754
- [[reverse.iter.opindex]]), or the global operators `operator<` (
755
  [[reverse.iter.op<]]), `operator>` ([[reverse.iter.op>]]),
756
  `operator<=` ([[reverse.iter.op<=]]), `operator>=` (
757
  [[reverse.iter.op>=]]), `operator-` ([[reverse.iter.opdiff]]) or
758
  `operator+` ([[reverse.iter.opsum]]) are referenced in a way that
759
  requires instantiation ([[temp.inst]]).
@@ -761,257 +776,252 @@ requires instantiation ([[temp.inst]]).
761
  #### `reverse_iterator` operations <a id="reverse.iter.ops">[[reverse.iter.ops]]</a>
762
 
763
  ##### `reverse_iterator` constructor <a id="reverse.iter.cons">[[reverse.iter.cons]]</a>
764
 
765
  ``` cpp
766
- reverse_iterator();
767
  ```
768
 
769
- *Effects:* Value initializes `current`. Iterator operations applied to
770
  the resulting iterator have defined behavior if and only if the
771
  corresponding operations are defined on a value-initialized iterator of
772
  type `Iterator`.
773
 
774
  ``` cpp
775
- explicit reverse_iterator(Iterator x);
776
  ```
777
 
778
  *Effects:* Initializes `current` with `x`.
779
 
780
  ``` cpp
781
- template <class U> reverse_iterator(const reverse_iterator<U> &u);
782
  ```
783
 
784
  *Effects:* Initializes `current` with `u.current`.
785
 
786
  ##### `reverse_iterator::operator=` <a id="reverse.iter.op=">[[reverse.iter.op=]]</a>
787
 
788
  ``` cpp
789
  template <class U>
790
- reverse_iterator&
791
  operator=(const reverse_iterator<U>& u);
792
  ```
793
 
794
  *Effects:* Assigns `u.base()` to current.
795
 
796
  *Returns:* `*this`.
797
 
798
  ##### Conversion <a id="reverse.iter.conv">[[reverse.iter.conv]]</a>
799
 
800
  ``` cpp
801
- Iterator base() const; // explicit
802
  ```
803
 
804
  *Returns:* `current`.
805
 
806
  ##### `operator*` <a id="reverse.iter.op.star">[[reverse.iter.op.star]]</a>
807
 
808
  ``` cpp
809
- reference operator*() const;
810
  ```
811
 
812
- *Effects:*
813
 
814
  ``` cpp
815
  Iterator tmp = current;
816
  return *--tmp;
817
  ```
818
 
819
  ##### `operator->` <a id="reverse.iter.opref">[[reverse.iter.opref]]</a>
820
 
821
  ``` cpp
822
- pointer operator->() const;
823
  ```
824
 
825
- *Returns:* `std::addressof(operator*())`.
826
 
827
  ##### `operator++` <a id="reverse.iter.op++">[[reverse.iter.op++]]</a>
828
 
829
  ``` cpp
830
- reverse_iterator& operator++();
831
  ```
832
 
833
- *Effects:* `current;`
834
 
835
  *Returns:* `*this`.
836
 
837
  ``` cpp
838
- reverse_iterator operator++(int);
839
  ```
840
 
841
- *Effects:*
842
 
843
  ``` cpp
844
  reverse_iterator tmp = *this;
845
  --current;
846
  return tmp;
847
  ```
848
 
849
  \[reverse.iter.op\]`operator\dcr`
850
 
851
  ``` cpp
852
- reverse_iterator& operator--();
853
  ```
854
 
855
- *Effects:* `++current`
856
 
857
  *Returns:* `*this`.
858
 
859
  ``` cpp
860
- reverse_iterator operator--(int);
861
  ```
862
 
863
- *Effects:*
864
 
865
  ``` cpp
866
  reverse_iterator tmp = *this;
867
  ++current;
868
  return tmp;
869
  ```
870
 
871
  ##### `operator+` <a id="reverse.iter.op+">[[reverse.iter.op+]]</a>
872
 
873
  ``` cpp
874
- reverse_iterator
875
- operator+(typename reverse_iterator<Iterator>::difference_type n) const;
876
  ```
877
 
878
  *Returns:* `reverse_iterator(current-n)`.
879
 
880
  ##### `operator+=` <a id="reverse.iter.op+=">[[reverse.iter.op+=]]</a>
881
 
882
  ``` cpp
883
- reverse_iterator&
884
- operator+=(typename reverse_iterator<Iterator>::difference_type n);
885
  ```
886
 
887
- *Effects:* `current -= n;`
888
 
889
  *Returns:* `*this`.
890
 
891
  ##### `operator-` <a id="reverse.iter.op-">[[reverse.iter.op-]]</a>
892
 
893
  ``` cpp
894
- reverse_iterator
895
- operator-(typename reverse_iterator<Iterator>::difference_type n) const;
896
  ```
897
 
898
  *Returns:* `reverse_iterator(current+n)`.
899
 
900
  ##### `operator-=` <a id="reverse.iter.op-=">[[reverse.iter.op-=]]</a>
901
 
902
  ``` cpp
903
- reverse_iterator&
904
- operator-=(typename reverse_iterator<Iterator>::difference_type n);
905
  ```
906
 
907
- *Effects:* `current += n;`
908
 
909
  *Returns:* `*this`.
910
 
911
  ##### `operator[]` <a id="reverse.iter.opindex">[[reverse.iter.opindex]]</a>
912
 
913
  ``` cpp
914
- unspecified operator[](
915
- typename reverse_iterator<Iterator>::difference_type n) const;
916
  ```
917
 
918
  *Returns:* `current[-n-1]`.
919
 
920
  ##### `operator==` <a id="reverse.iter.op==">[[reverse.iter.op==]]</a>
921
 
922
  ``` cpp
923
  template <class Iterator1, class Iterator2>
924
- bool operator==(
925
  const reverse_iterator<Iterator1>& x,
926
  const reverse_iterator<Iterator2>& y);
927
  ```
928
 
929
  *Returns:* `x.current == y.current`.
930
 
931
  ##### `operator<` <a id="reverse.iter.op<">[[reverse.iter.op<]]</a>
932
 
933
  ``` cpp
934
  template <class Iterator1, class Iterator2>
935
- bool operator<(
936
  const reverse_iterator<Iterator1>& x,
937
  const reverse_iterator<Iterator2>& y);
938
  ```
939
 
940
  *Returns:* `x.current > y.current`.
941
 
942
  ##### `operator!=` <a id="reverse.iter.op!=">[[reverse.iter.op!=]]</a>
943
 
944
  ``` cpp
945
  template <class Iterator1, class Iterator2>
946
- bool operator!=(
947
  const reverse_iterator<Iterator1>& x,
948
  const reverse_iterator<Iterator2>& y);
949
  ```
950
 
951
  *Returns:* `x.current != y.current`.
952
 
953
  ##### `operator>` <a id="reverse.iter.op>">[[reverse.iter.op>]]</a>
954
 
955
  ``` cpp
956
  template <class Iterator1, class Iterator2>
957
- bool operator>(
958
  const reverse_iterator<Iterator1>& x,
959
  const reverse_iterator<Iterator2>& y);
960
  ```
961
 
962
  *Returns:* `x.current < y.current`.
963
 
964
  ##### `operator>=` <a id="reverse.iter.op>=">[[reverse.iter.op>=]]</a>
965
 
966
  ``` cpp
967
  template <class Iterator1, class Iterator2>
968
- bool operator>=(
969
  const reverse_iterator<Iterator1>& x,
970
  const reverse_iterator<Iterator2>& y);
971
  ```
972
 
973
  *Returns:* `x.current <= y.current`.
974
 
975
  ##### `operator<=` <a id="reverse.iter.op<=">[[reverse.iter.op<=]]</a>
976
 
977
  ``` cpp
978
  template <class Iterator1, class Iterator2>
979
- bool operator<=(
980
  const reverse_iterator<Iterator1>& x,
981
  const reverse_iterator<Iterator2>& y);
982
  ```
983
 
984
  *Returns:* `x.current >= y.current`.
985
 
986
  ##### `operator-` <a id="reverse.iter.opdiff">[[reverse.iter.opdiff]]</a>
987
 
988
  ``` cpp
989
  template <class Iterator1, class Iterator2>
990
- auto operator-(
991
  const reverse_iterator<Iterator1>& x,
992
  const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
993
  ```
994
 
995
  *Returns:* `y.current - x.current`.
996
 
997
  ##### `operator+` <a id="reverse.iter.opsum">[[reverse.iter.opsum]]</a>
998
 
999
  ``` cpp
1000
  template <class Iterator>
1001
- reverse_iterator<Iterator> operator+(
1002
  typename reverse_iterator<Iterator>::difference_type n,
1003
  const reverse_iterator<Iterator>& x);
1004
  ```
1005
 
1006
  *Returns:* `reverse_iterator<Iterator> (x.current - n)`.
1007
 
1008
  ##### Non-member function `make_reverse_iterator()` <a id="reverse.iter.make">[[reverse.iter.make]]</a>
1009
 
1010
  ``` cpp
1011
  template <class Iterator>
1012
- reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
1013
  ```
1014
 
1015
  *Returns:* `reverse_iterator<Iterator>(i)`.
1016
 
1017
  ### Insert iterators <a id="insert.iterators">[[insert.iterators]]</a>
@@ -1048,26 +1058,29 @@ iterators out of a container.
1048
  #### Class template `back_insert_iterator` <a id="back.insert.iterator">[[back.insert.iterator]]</a>
1049
 
1050
  ``` cpp
1051
  namespace std {
1052
  template <class Container>
1053
- class back_insert_iterator :
1054
- public iterator<output_iterator_tag,void,void,void,void> {
1055
  protected:
1056
  Container* container;
1057
 
1058
  public:
1059
- typedef Container container_type;
 
 
 
 
 
 
1060
  explicit back_insert_iterator(Container& x);
1061
- back_insert_iterator<Container>&
1062
- operator=(const typename Container::value_type& value);
1063
- back_insert_iterator<Container>&
1064
- operator=(typename Container::value_type&& value);
1065
 
1066
- back_insert_iterator<Container>& operator*();
1067
- back_insert_iterator<Container>& operator++();
1068
- back_insert_iterator<Container> operator++(int);
1069
  };
1070
 
1071
  template <class Container>
1072
  back_insert_iterator<Container> back_inserter(Container& x);
1073
  }
@@ -1079,45 +1092,43 @@ namespace std {
1079
 
1080
  ``` cpp
1081
  explicit back_insert_iterator(Container& x);
1082
  ```
1083
 
1084
- *Effects:* Initializes `container` with `std::addressof(x)`.
1085
 
1086
  ##### `back_insert_iterator::operator=` <a id="back.insert.iter.op=">[[back.insert.iter.op=]]</a>
1087
 
1088
  ``` cpp
1089
- back_insert_iterator<Container>&
1090
- operator=(const typename Container::value_type& value);
1091
  ```
1092
 
1093
- *Effects:* `container->push_back(value);`
1094
 
1095
  *Returns:* `*this`.
1096
 
1097
  ``` cpp
1098
- back_insert_iterator<Container>&
1099
- operator=(typename Container::value_type&& value);
1100
  ```
1101
 
1102
- *Effects:* `container->push_back(std::move(value));`
1103
 
1104
  *Returns:* `*this`.
1105
 
1106
  ##### `back_insert_iterator::operator*` <a id="back.insert.iter.op*">[[back.insert.iter.op*]]</a>
1107
 
1108
  ``` cpp
1109
- back_insert_iterator<Container>& operator*();
1110
  ```
1111
 
1112
  *Returns:* `*this`.
1113
 
1114
  ##### `back_insert_iterator::operator++` <a id="back.insert.iter.op++">[[back.insert.iter.op++]]</a>
1115
 
1116
  ``` cpp
1117
- back_insert_iterator<Container>& operator++();
1118
- back_insert_iterator<Container> operator++(int);
1119
  ```
1120
 
1121
  *Returns:* `*this`.
1122
 
1123
  ##### `back_inserter` <a id="back.inserter">[[back.inserter]]</a>
@@ -1132,26 +1143,29 @@ template <class Container>
1132
  #### Class template `front_insert_iterator` <a id="front.insert.iterator">[[front.insert.iterator]]</a>
1133
 
1134
  ``` cpp
1135
  namespace std {
1136
  template <class Container>
1137
- class front_insert_iterator :
1138
- public iterator<output_iterator_tag,void,void,void,void> {
1139
  protected:
1140
  Container* container;
1141
 
1142
  public:
1143
- typedef Container container_type;
 
 
 
 
 
 
1144
  explicit front_insert_iterator(Container& x);
1145
- front_insert_iterator<Container>&
1146
- operator=(const typename Container::value_type& value);
1147
- front_insert_iterator<Container>&
1148
- operator=(typename Container::value_type&& value);
1149
 
1150
- front_insert_iterator<Container>& operator*();
1151
- front_insert_iterator<Container>& operator++();
1152
- front_insert_iterator<Container> operator++(int);
1153
  };
1154
 
1155
  template <class Container>
1156
  front_insert_iterator<Container> front_inserter(Container& x);
1157
  }
@@ -1163,45 +1177,43 @@ namespace std {
1163
 
1164
  ``` cpp
1165
  explicit front_insert_iterator(Container& x);
1166
  ```
1167
 
1168
- *Effects:* Initializes `container` with `std::addressof(x)`.
1169
 
1170
  ##### `front_insert_iterator::operator=` <a id="front.insert.iter.op=">[[front.insert.iter.op=]]</a>
1171
 
1172
  ``` cpp
1173
- front_insert_iterator<Container>&
1174
- operator=(const typename Container::value_type& value);
1175
  ```
1176
 
1177
- *Effects:* `container->push_front(value);`
1178
 
1179
  *Returns:* `*this`.
1180
 
1181
  ``` cpp
1182
- front_insert_iterator<Container>&
1183
- operator=(typename Container::value_type&& value);
1184
  ```
1185
 
1186
- *Effects:* `container->push_front(std::move(value));`
1187
 
1188
  *Returns:* `*this`.
1189
 
1190
  ##### `front_insert_iterator::operator*` <a id="front.insert.iter.op*">[[front.insert.iter.op*]]</a>
1191
 
1192
  ``` cpp
1193
- front_insert_iterator<Container>& operator*();
1194
  ```
1195
 
1196
  *Returns:* `*this`.
1197
 
1198
  ##### `front_insert_iterator::operator++` <a id="front.insert.iter.op++">[[front.insert.iter.op++]]</a>
1199
 
1200
  ``` cpp
1201
- front_insert_iterator<Container>& operator++();
1202
- front_insert_iterator<Container> operator++(int);
1203
  ```
1204
 
1205
  *Returns:* `*this`.
1206
 
1207
  ##### `front_inserter` <a id="front.inserter">[[front.inserter]]</a>
@@ -1216,27 +1228,30 @@ template <class Container>
1216
  #### Class template `insert_iterator` <a id="insert.iterator">[[insert.iterator]]</a>
1217
 
1218
  ``` cpp
1219
  namespace std {
1220
  template <class Container>
1221
- class insert_iterator :
1222
- public iterator<output_iterator_tag,void,void,void,void> {
1223
  protected:
1224
  Container* container;
1225
  typename Container::iterator iter;
1226
 
1227
  public:
1228
- typedef Container container_type;
 
 
 
 
 
 
1229
  insert_iterator(Container& x, typename Container::iterator i);
1230
- insert_iterator<Container>&
1231
- operator=(const typename Container::value_type& value);
1232
- insert_iterator<Container>&
1233
- operator=(typename Container::value_type&& value);
1234
 
1235
- insert_iterator<Container>& operator*();
1236
- insert_iterator<Container>& operator++();
1237
- insert_iterator<Container>& operator++(int);
1238
  };
1239
 
1240
  template <class Container>
1241
  insert_iterator<Container> inserter(Container& x, typename Container::iterator i);
1242
  }
@@ -1248,35 +1263,33 @@ namespace std {
1248
 
1249
  ``` cpp
1250
  insert_iterator(Container& x, typename Container::iterator i);
1251
  ```
1252
 
1253
- *Effects:* Initializes `container` with `std::addressof(x)` and `iter`
1254
- with `i`.
1255
 
1256
  ##### `insert_iterator::operator=` <a id="insert.iter.op=">[[insert.iter.op=]]</a>
1257
 
1258
  ``` cpp
1259
- insert_iterator<Container>&
1260
- operator=(const typename Container::value_type& value);
1261
  ```
1262
 
1263
- *Effects:*
1264
 
1265
  ``` cpp
1266
  iter = container->insert(iter, value);
1267
  ++iter;
1268
  ```
1269
 
1270
  *Returns:* `*this`.
1271
 
1272
  ``` cpp
1273
- insert_iterator<Container>&
1274
- operator=(typename Container::value_type&& value);
1275
  ```
1276
 
1277
- *Effects:*
1278
 
1279
  ``` cpp
1280
  iter = container->insert(iter, std::move(value));
1281
  ++iter;
1282
  ```
@@ -1284,20 +1297,20 @@ iter = container->insert(iter, std::move(value));
1284
  *Returns:* `*this`.
1285
 
1286
  ##### `insert_iterator::operator*` <a id="insert.iter.op*">[[insert.iter.op*]]</a>
1287
 
1288
  ``` cpp
1289
- insert_iterator<Container>& operator*();
1290
  ```
1291
 
1292
  *Returns:* `*this`.
1293
 
1294
  ##### `insert_iterator::operator++` <a id="insert.iter.op++">[[insert.iter.op++]]</a>
1295
 
1296
  ``` cpp
1297
- insert_iterator<Container>& operator++();
1298
- insert_iterator<Container>& operator++(int);
1299
  ```
1300
 
1301
  *Returns:* `*this`.
1302
 
1303
  ##### `inserter` <a id="inserter">[[inserter]]</a>
@@ -1312,335 +1325,349 @@ template <class Container>
1312
  ### Move iterators <a id="move.iterators">[[move.iterators]]</a>
1313
 
1314
  Class template `move_iterator` is an iterator adaptor with the same
1315
  behavior as the underlying iterator except that its indirection operator
1316
  implicitly converts the value returned by the underlying iterator’s
1317
- indirection operator to an rvalue reference. Some generic algorithms can
1318
- be called with move iterators to replace copying with moving.
 
 
1319
 
1320
  ``` cpp
1321
  list<string> s;
1322
  // populate the list s
1323
  vector<string> v1(s.begin(), s.end()); // copies strings into v1
1324
  vector<string> v2(make_move_iterator(s.begin()),
1325
  make_move_iterator(s.end())); // moves strings into v2
1326
  ```
1327
 
 
 
1328
  #### Class template `move_iterator` <a id="move.iterator">[[move.iterator]]</a>
1329
 
1330
  ``` cpp
1331
  namespace std {
1332
  template <class Iterator>
1333
  class move_iterator {
1334
  public:
1335
- typedef Iterator iterator_type;
1336
- typedef typename iterator_traits<Iterator>::difference_type difference_type;
1337
- typedef Iterator pointer;
1338
- typedef typename iterator_traits<Iterator>::value_type value_type;
1339
- typedef typename iterator_traits<Iterator>::iterator_category iterator_category;
1340
- typedef value_type&& reference;
1341
 
1342
- move_iterator();
1343
- explicit move_iterator(Iterator i);
1344
- template <class U> move_iterator(const move_iterator<U>& u);
1345
- template <class U> move_iterator& operator=(const move_iterator<U>& u);
1346
 
1347
- iterator_type base() const;
1348
- reference operator*() const;
1349
- pointer operator->() const;
1350
 
1351
- move_iterator& operator++();
1352
- move_iterator operator++(int);
1353
- move_iterator& operator--();
1354
- move_iterator operator--(int);
1355
 
1356
- move_iterator operator+(difference_type n) const;
1357
- move_iterator& operator+=(difference_type n);
1358
- move_iterator operator-(difference_type n) const;
1359
- move_iterator& operator-=(difference_type n);
1360
- unspecified operator[](difference_type n) const;
1361
 
1362
  private:
1363
  Iterator current; // exposition only
1364
  };
1365
 
1366
  template <class Iterator1, class Iterator2>
1367
- bool operator==(
1368
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1369
  template <class Iterator1, class Iterator2>
1370
- bool operator!=(
1371
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1372
  template <class Iterator1, class Iterator2>
1373
- bool operator<(
1374
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1375
  template <class Iterator1, class Iterator2>
1376
- bool operator<=(
1377
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1378
  template <class Iterator1, class Iterator2>
1379
- bool operator>(
1380
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1381
  template <class Iterator1, class Iterator2>
1382
- bool operator>=(
1383
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1384
 
1385
  template <class Iterator1, class Iterator2>
1386
- auto operator-(
1387
  const move_iterator<Iterator1>& x,
1388
  const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
1389
  template <class Iterator>
1390
- move_iterator<Iterator> operator+(
1391
  typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
1392
  template <class Iterator>
1393
- move_iterator<Iterator> make_move_iterator(Iterator i);
1394
  }
1395
  ```
1396
 
 
 
 
 
 
 
1397
  #### `move_iterator` requirements <a id="move.iter.requirements">[[move.iter.requirements]]</a>
1398
 
1399
- The template parameter `Iterator` shall meet the requirements for an
1400
- Input Iterator ([[input.iterators]]). Additionally, if any of the
1401
  bidirectional or random access traversal functions are instantiated, the
1402
  template parameter shall meet the requirements for a Bidirectional
1403
  Iterator ([[bidirectional.iterators]]) or a Random Access Iterator (
1404
  [[random.access.iterators]]), respectively.
1405
 
1406
  #### `move_iterator` operations <a id="move.iter.ops">[[move.iter.ops]]</a>
1407
 
1408
  ##### `move_iterator` constructors <a id="move.iter.op.const">[[move.iter.op.const]]</a>
1409
 
1410
  ``` cpp
1411
- move_iterator();
1412
  ```
1413
 
1414
- *Effects:* Constructs a `move_iterator`, value initializing `current`.
1415
  Iterator operations applied to the resulting iterator have defined
1416
  behavior if and only if the corresponding operations are defined on a
1417
  value-initialized iterator of type `Iterator`.
1418
 
1419
  ``` cpp
1420
- explicit move_iterator(Iterator i);
1421
  ```
1422
 
1423
  *Effects:* Constructs a `move_iterator`, initializing `current` with
1424
  `i`.
1425
 
1426
  ``` cpp
1427
- template <class U> move_iterator(const move_iterator<U>& u);
1428
  ```
1429
 
1430
  *Effects:* Constructs a `move_iterator`, initializing `current` with
1431
  `u.base()`.
1432
 
1433
  *Requires:* `U` shall be convertible to `Iterator`.
1434
 
1435
  ##### `move_iterator::operator=` <a id="move.iter.op=">[[move.iter.op=]]</a>
1436
 
1437
  ``` cpp
1438
- template <class U> move_iterator& operator=(const move_iterator<U>& u);
1439
  ```
1440
 
1441
  *Effects:* Assigns `u.base()` to `current`.
1442
 
1443
  *Requires:* `U` shall be convertible to `Iterator`.
1444
 
1445
  ##### `move_iterator` conversion <a id="move.iter.op.conv">[[move.iter.op.conv]]</a>
1446
 
1447
  ``` cpp
1448
- Iterator base() const;
1449
  ```
1450
 
1451
  *Returns:* `current`.
1452
 
1453
  ##### `move_iterator::operator*` <a id="move.iter.op.star">[[move.iter.op.star]]</a>
1454
 
1455
  ``` cpp
1456
- reference operator*() const;
1457
  ```
1458
 
1459
- *Returns:* `std::move(`\*current).
1460
 
1461
  ##### `move_iterator::operator->` <a id="move.iter.op.ref">[[move.iter.op.ref]]</a>
1462
 
1463
  ``` cpp
1464
- pointer operator->() const;
1465
  ```
1466
 
1467
  *Returns:* `current`.
1468
 
1469
  ##### `move_iterator::operator++` <a id="move.iter.op.incr">[[move.iter.op.incr]]</a>
1470
 
1471
  ``` cpp
1472
- move_iterator& operator++();
1473
  ```
1474
 
1475
- *Effects:* `++current`.
1476
 
1477
  *Returns:* `*this`.
1478
 
1479
  ``` cpp
1480
- move_iterator operator++(int);
1481
  ```
1482
 
1483
- *Effects:*
1484
 
1485
  ``` cpp
1486
  move_iterator tmp = *this;
1487
  ++current;
1488
  return tmp;
1489
  ```
1490
 
1491
  ##### `move_iterator::operator-{-}` <a id="move.iter.op.decr">[[move.iter.op.decr]]</a>
1492
 
1493
  ``` cpp
1494
- move_iterator& operator--();
1495
  ```
1496
 
1497
- *Effects:* \dcr`current`.
1498
 
1499
  *Returns:* `*this`.
1500
 
1501
  ``` cpp
1502
- move_iterator operator--(int);
1503
  ```
1504
 
1505
- *Effects:*
1506
 
1507
  ``` cpp
1508
  move_iterator tmp = *this;
1509
  --current;
1510
  return tmp;
1511
  ```
1512
 
1513
  ##### `move_iterator::operator+` <a id="move.iter.op.+">[[move.iter.op.+]]</a>
1514
 
1515
  ``` cpp
1516
- move_iterator operator+(difference_type n) const;
1517
  ```
1518
 
1519
  *Returns:* `move_iterator(current + n)`.
1520
 
1521
  ##### `move_iterator::operator+=` <a id="move.iter.op.+=">[[move.iter.op.+=]]</a>
1522
 
1523
  ``` cpp
1524
- move_iterator& operator+=(difference_type n);
1525
  ```
1526
 
1527
- *Effects:* `current += n`.
1528
 
1529
  *Returns:* `*this`.
1530
 
1531
  ##### `move_iterator::operator-` <a id="move.iter.op.-">[[move.iter.op.-]]</a>
1532
 
1533
  ``` cpp
1534
- move_iterator operator-(difference_type n) const;
1535
  ```
1536
 
1537
  *Returns:* `move_iterator(current - n)`.
1538
 
1539
  ##### `move_iterator::operator-=` <a id="move.iter.op.-=">[[move.iter.op.-=]]</a>
1540
 
1541
  ``` cpp
1542
- move_iterator& operator-=(difference_type n);
1543
  ```
1544
 
1545
- *Effects:* `current -= n`.
1546
 
1547
  *Returns:* `*this`.
1548
 
1549
  ##### `move_iterator::operator[]` <a id="move.iter.op.index">[[move.iter.op.index]]</a>
1550
 
1551
  ``` cpp
1552
- unspecified operator[](difference_type n) const;
1553
  ```
1554
 
1555
- *Returns:* `std::move(`current\[n\]).
1556
 
1557
  ##### `move_iterator` comparisons <a id="move.iter.op.comp">[[move.iter.op.comp]]</a>
1558
 
1559
  ``` cpp
1560
  template <class Iterator1, class Iterator2>
1561
- bool operator==(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1562
  ```
1563
 
1564
  *Returns:* `x.base() == y.base()`.
1565
 
1566
  ``` cpp
1567
  template <class Iterator1, class Iterator2>
1568
- bool operator!=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1569
  ```
1570
 
1571
  *Returns:* `!(x == y)`.
1572
 
1573
  ``` cpp
1574
  template <class Iterator1, class Iterator2>
1575
- bool operator<(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1576
  ```
1577
 
1578
  *Returns:* `x.base() < y.base()`.
1579
 
1580
  ``` cpp
1581
  template <class Iterator1, class Iterator2>
1582
- bool operator<=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1583
  ```
1584
 
1585
  *Returns:* `!(y < x)`.
1586
 
1587
  ``` cpp
1588
  template <class Iterator1, class Iterator2>
1589
- bool operator>(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1590
  ```
1591
 
1592
  *Returns:* `y < x`.
1593
 
1594
  ``` cpp
1595
  template <class Iterator1, class Iterator2>
1596
- bool operator>=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1597
  ```
1598
 
1599
  *Returns:* `!(x < y)`.
1600
 
1601
  ##### `move_iterator` non-member functions <a id="move.iter.nonmember">[[move.iter.nonmember]]</a>
1602
 
1603
  ``` cpp
1604
  template <class Iterator1, class Iterator2>
1605
- auto operator-(
1606
  const move_iterator<Iterator1>& x,
1607
  const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
1608
  ```
1609
 
1610
  *Returns:* `x.base() - y.base()`.
1611
 
1612
  ``` cpp
1613
  template <class Iterator>
1614
- move_iterator<Iterator> operator+(
1615
  typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
1616
  ```
1617
 
1618
  *Returns:* `x + n`.
1619
 
1620
  ``` cpp
1621
  template <class Iterator>
1622
- move_iterator<Iterator> make_move_iterator(Iterator i);
1623
  ```
1624
 
1625
  *Returns:* `move_iterator<Iterator>(i)`.
1626
 
1627
  ## Stream iterators <a id="stream.iterators">[[stream.iterators]]</a>
1628
 
1629
  To make it possible for algorithmic templates to work directly with
1630
  input/output streams, appropriate iterator-like class templates are
1631
  provided.
1632
 
 
 
1633
  ``` cpp
1634
  partial_sum(istream_iterator<double, char>(cin),
1635
  istream_iterator<double, char>(),
1636
  ostream_iterator<double, char>(cout, "\n"));
1637
  ```
1638
 
1639
- reads a file containing floating point numbers from `cin`, and prints
1640
  the partial sums onto `cout`.
1641
 
 
 
1642
  ### Class template `istream_iterator` <a id="istream.iterator">[[istream.iterator]]</a>
1643
 
1644
  The class template `istream_iterator` is an input iterator (
1645
  [[input.iterators]]) that reads (using `operator>>`) successive elements
1646
  from the input stream for which it was constructed. After it is
@@ -1653,35 +1680,42 @@ object, which is the only legitimate iterator to be used for the end
1653
  condition. The result of `operator*` on an end-of-stream iterator is not
1654
  defined. For any other iterator value a `const T&` is returned. The
1655
  result of `operator->` on an end-of-stream iterator is not defined. For
1656
  any other iterator value a `const T*` is returned. The behavior of a
1657
  program that applies `operator++()` to an end-of-stream iterator is
1658
- undefined. It is impossible to store things into istream iterators.
 
 
1659
 
1660
  Two end-of-stream iterators are always equal. An end-of-stream iterator
1661
  is not equal to a non-end-of-stream iterator. Two non-end-of-stream
1662
  iterators are equal when they are constructed from the same stream.
1663
 
1664
  ``` cpp
1665
  namespace std {
1666
  template <class T, class charT = char, class traits = char_traits<charT>,
1667
  class Distance = ptrdiff_t>
1668
- class istream_iterator:
1669
- public iterator<input_iterator_tag, T, Distance, const T*, const T&> {
1670
  public:
1671
- typedef charT char_type;
1672
- typedef traits traits_type;
1673
- typedef basic_istream<charT,traits> istream_type;
1674
- see below istream_iterator();
 
 
 
 
 
 
1675
  istream_iterator(istream_type& s);
1676
  istream_iterator(const istream_iterator& x) = default;
1677
  ~istream_iterator() = default;
1678
 
1679
  const T& operator*() const;
1680
  const T* operator->() const;
1681
- istream_iterator<T,charT,traits,Distance>& operator++();
1682
- istream_iterator<T,charT,traits,Distance> operator++(int);
1683
  private:
1684
  basic_istream<charT,traits>* in_stream; // exposition only
1685
  T value; // exposition only
1686
  };
1687
 
@@ -1695,77 +1729,80 @@ namespace std {
1695
  ```
1696
 
1697
  #### `istream_iterator` constructors and destructor <a id="istream.iterator.cons">[[istream.iterator.cons]]</a>
1698
 
1699
  ``` cpp
1700
- see below istream_iterator();
1701
  ```
1702
 
1703
- *Effects:* Constructs the end-of-stream iterator. If `T` is a literal
1704
- type, then this constructor shall be a `constexpr` constructor.
 
1705
 
1706
- `in_stream == 0`.
1707
 
1708
  ``` cpp
1709
  istream_iterator(istream_type& s);
1710
  ```
1711
 
1712
- *Effects:* Initializes *in_stream* with `&s`. *value* may be initialized
1713
- during construction or the first time it is referenced.
1714
 
1715
- `in_stream == &s`.
1716
 
1717
  ``` cpp
1718
  istream_iterator(const istream_iterator& x) = default;
1719
  ```
1720
 
1721
- *Effects:* Constructs a copy of `x`. If `T` is a literal type, then this
1722
- constructor shall be a trivial copy constructor.
 
1723
 
1724
- `in_stream == x.in_stream`.
1725
 
1726
  ``` cpp
1727
  ~istream_iterator() = default;
1728
  ```
1729
 
1730
- *Effects:* The iterator is destroyed. If `T` is a literal type, then
1731
- this destructor shall be a trivial destructor.
 
1732
 
1733
  #### `istream_iterator` operations <a id="istream.iterator.ops">[[istream.iterator.ops]]</a>
1734
 
1735
  ``` cpp
1736
  const T& operator*() const;
1737
  ```
1738
 
1739
- *Returns:* *value*.
1740
 
1741
  ``` cpp
1742
  const T* operator->() const;
1743
  ```
1744
 
1745
- *Returns:* `&(operator*())`.
1746
 
1747
  ``` cpp
1748
- istream_iterator<T,charT,traits,Distance>& operator++();
1749
  ```
1750
 
1751
  *Requires:* `in_stream != 0`.
1752
 
1753
- *Effects:* `*in_stream >>value`.
1754
 
1755
  *Returns:* `*this`.
1756
 
1757
  ``` cpp
1758
- istream_iterator<T,charT,traits,Distance> operator++(int);
1759
  ```
1760
 
1761
  *Requires:* `in_stream != 0`.
1762
 
1763
- *Effects:*
1764
 
1765
  ``` cpp
1766
- istream_iterator<T,charT,traits,Distance> tmp = *this;
1767
  *in_stream >> value;
1768
  return (tmp);
1769
  ```
1770
 
1771
  ``` cpp
@@ -1803,25 +1840,30 @@ while (first != last)
1803
  is defined as:
1804
 
1805
  ``` cpp
1806
  namespace std {
1807
  template <class T, class charT = char, class traits = char_traits<charT>>
1808
- class ostream_iterator:
1809
- public iterator<output_iterator_tag, void, void, void, void> {
1810
  public:
1811
- typedef charT char_type;
1812
- typedef traits traits_type;
1813
- typedef basic_ostream<charT,traits> ostream_type;
 
 
 
 
 
 
1814
  ostream_iterator(ostream_type& s);
1815
  ostream_iterator(ostream_type& s, const charT* delimiter);
1816
- ostream_iterator(const ostream_iterator<T,charT,traits>& x);
1817
  ~ostream_iterator();
1818
- ostream_iterator<T,charT,traits>& operator=(const T& value);
1819
 
1820
- ostream_iterator<T,charT,traits>& operator*();
1821
- ostream_iterator<T,charT,traits>& operator++();
1822
- ostream_iterator<T,charT,traits>& operator++(int);
1823
  private:
1824
  basic_ostream<charT,traits>* out_stream; // exposition only
1825
  const charT* delim; // exposition only
1826
  };
1827
  }
@@ -1831,17 +1873,18 @@ namespace std {
1831
 
1832
  ``` cpp
1833
  ostream_iterator(ostream_type& s);
1834
  ```
1835
 
1836
- *Effects:* Initializes *out_stream* with `&s` and *delim* with null.
 
1837
 
1838
  ``` cpp
1839
  ostream_iterator(ostream_type& s, const charT* delimiter);
1840
  ```
1841
 
1842
- *Effects:* Initializes *out_stream* with `&s` and *delim* with
1843
  `delimiter`.
1844
 
1845
  ``` cpp
1846
  ostream_iterator(const ostream_iterator& x);
1847
  ```
@@ -1858,11 +1901,11 @@ ostream_iterator(const ostream_iterator& x);
1858
 
1859
  ``` cpp
1860
  ostream_iterator& operator=(const T& value);
1861
  ```
1862
 
1863
- *Effects:*
1864
 
1865
  ``` cpp
1866
  *out_stream << value;
1867
  if (delim != 0)
1868
  *out_stream << delim;
@@ -1885,49 +1928,50 @@ ostream_iterator& operator++(int);
1885
  ### Class template `istreambuf_iterator` <a id="istreambuf.iterator">[[istreambuf.iterator]]</a>
1886
 
1887
  The class template `istreambuf_iterator` defines an input iterator (
1888
  [[input.iterators]]) that reads successive *characters* from the
1889
  streambuf for which it was constructed. `operator*` provides access to
1890
- the current input character, if any. `operator->` may return a proxy.
1891
- Each time `operator++` is evaluated, the iterator advances to the next
1892
- input character. If the end of stream is reached
1893
- (`streambuf_type::sgetc()` returns `traits::eof()`), the iterator
1894
- becomes equal to the *end-of-stream* iterator value. The default
1895
- constructor `istreambuf_iterator()` and the constructor
1896
- `istreambuf_iterator(0)` both construct an end-of-stream iterator object
1897
- suitable for use as an end-of-range. All specializations of
1898
- `istreambuf_iterator` shall have a trivial copy constructor, a
1899
  `constexpr` default constructor, and a trivial destructor.
1900
 
1901
  The result of `operator*()` on an end-of-stream iterator is undefined.
1902
  For any other iterator value a `char_type` value is returned. It is
1903
  impossible to assign a character via an input iterator.
1904
 
1905
  ``` cpp
1906
  namespace std {
1907
  template<class charT, class traits = char_traits<charT>>
1908
- class istreambuf_iterator
1909
- : public iterator<input_iterator_tag, charT,
1910
- typename traits::off_type, unspecified, charT> {
1911
  public:
1912
- typedef charT char_type;
1913
- typedef traits traits_type;
1914
- typedef typename traits::int_type int_type;
1915
- typedef basic_streambuf<charT,traits> streambuf_type;
1916
- typedef basic_istream<charT,traits> istream_type;
 
 
 
 
 
1917
 
1918
  class proxy; // exposition only
1919
 
1920
  constexpr istreambuf_iterator() noexcept;
1921
  istreambuf_iterator(const istreambuf_iterator&) noexcept = default;
1922
  ~istreambuf_iterator() = default;
1923
  istreambuf_iterator(istream_type& s) noexcept;
1924
  istreambuf_iterator(streambuf_type* s) noexcept;
1925
  istreambuf_iterator(const proxy& p) noexcept;
1926
  charT operator*() const;
1927
- pointer operator->() const;
1928
- istreambuf_iterator<charT,traits>& operator++();
1929
  proxy operator++(int);
1930
  bool equal(const istreambuf_iterator& b) const;
1931
  private:
1932
  streambuf_type* sbuf_; // exposition only
1933
  };
@@ -1939,11 +1983,11 @@ namespace std {
1939
  bool operator!=(const istreambuf_iterator<charT,traits>& a,
1940
  const istreambuf_iterator<charT,traits>& b);
1941
  }
1942
  ```
1943
 
1944
- #### Class template `istreambuf_iterator::proxy` <a id="istreambuf.iterator::proxy">[[istreambuf.iterator::proxy]]</a>
1945
 
1946
  ``` cpp
1947
  namespace std {
1948
  template <class charT, class traits = char_traits<charT>>
1949
  class istreambuf_iterator<charT, traits>::proxy { // exposition only
@@ -1965,81 +2009,77 @@ placeholder as the return value of the post-increment operator
1965
  (`operator++`). It keeps the character pointed to by the previous value
1966
  of the iterator for some possible future access to get the character.
1967
 
1968
  #### `istreambuf_iterator` constructors <a id="istreambuf.iterator.cons">[[istreambuf.iterator.cons]]</a>
1969
 
 
 
 
 
1970
  ``` cpp
1971
  constexpr istreambuf_iterator() noexcept;
1972
  ```
1973
 
1974
- *Effects:* Constructs the end-of-stream iterator.
1975
 
1976
  ``` cpp
1977
- istreambuf_iterator(basic_istream<charT,traits>& s) noexcept;
1978
- istreambuf_iterator(basic_streambuf<charT,traits>* s) noexcept;
1979
  ```
1980
 
1981
- *Effects:* Constructs an `istreambuf_iterator<>` that uses the
1982
- `basic_streambuf<>` object `*(s.rdbuf())`, or `*s`, respectively.
1983
- Constructs an end-of-stream iterator if `s.rdbuf()` is null.
 
 
 
 
1984
 
1985
  ``` cpp
1986
  istreambuf_iterator(const proxy& p) noexcept;
1987
  ```
1988
 
1989
- *Effects:* Constructs a `istreambuf_iterator<>` that uses the
1990
- `basic_streambuf<>` object pointed to by the `proxy` object’s
1991
- constructor argument `p`.
1992
 
1993
- #### `istreambuf_iterator::operator*` <a id="istreambuf.iterator::op*">[[istreambuf.iterator::op*]]</a>
1994
 
1995
  ``` cpp
1996
  charT operator*() const
1997
  ```
1998
 
1999
  *Returns:* The character obtained via the `streambuf` member
2000
  `sbuf_->sgetc()`.
2001
 
2002
- #### `istreambuf_iterator::operator++` <a id="istreambuf.iterator::op++">[[istreambuf.iterator::op++]]</a>
2003
-
2004
  ``` cpp
2005
- istreambuf_iterator<charT,traits>&
2006
- istreambuf_iterator<charT,traits>::operator++();
2007
  ```
2008
 
2009
- *Effects:* `sbuf_->sbumpc()`.
2010
 
2011
  *Returns:* `*this`.
2012
 
2013
  ``` cpp
2014
- proxy istreambuf_iterator<charT,traits>::operator++(int);
2015
  ```
2016
 
2017
  *Returns:* `proxy(sbuf_->sbumpc(), sbuf_)`.
2018
 
2019
- #### `istreambuf_iterator::equal` <a id="istreambuf.iterator::equal">[[istreambuf.iterator::equal]]</a>
2020
-
2021
  ``` cpp
2022
- bool equal(const istreambuf_iterator<charT,traits>& b) const;
2023
  ```
2024
 
2025
  *Returns:* `true` if and only if both iterators are at end-of-stream, or
2026
  neither is at end-of-stream, regardless of what `streambuf` object they
2027
  use.
2028
 
2029
- #### `operator==` <a id="istreambuf.iterator::op==">[[istreambuf.iterator::op==]]</a>
2030
-
2031
  ``` cpp
2032
  template <class charT, class traits>
2033
  bool operator==(const istreambuf_iterator<charT,traits>& a,
2034
  const istreambuf_iterator<charT,traits>& b);
2035
  ```
2036
 
2037
  *Returns:* `a.equal(b)`.
2038
 
2039
- #### `operator!=` <a id="istreambuf.iterator::op!=">[[istreambuf.iterator::op!=]]</a>
2040
-
2041
  ``` cpp
2042
  template <class charT, class traits>
2043
  bool operator!=(const istreambuf_iterator<charT,traits>& a,
2044
  const istreambuf_iterator<charT,traits>& b);
2045
  ```
@@ -2049,19 +2089,22 @@ template <class charT, class traits>
2049
  ### Class template `ostreambuf_iterator` <a id="ostreambuf.iterator">[[ostreambuf.iterator]]</a>
2050
 
2051
  ``` cpp
2052
  namespace std {
2053
  template <class charT, class traits = char_traits<charT>>
2054
- class ostreambuf_iterator :
2055
- public iterator<output_iterator_tag, void, void, void, void> {
2056
  public:
2057
- typedef charT char_type;
2058
- typedef traits traits_type;
2059
- typedef basic_streambuf<charT,traits> streambuf_type;
2060
- typedef basic_ostream<charT,traits> ostream_type;
 
 
 
 
 
2061
 
2062
- public:
2063
  ostreambuf_iterator(ostream_type& s) noexcept;
2064
  ostreambuf_iterator(streambuf_type* s) noexcept;
2065
  ostreambuf_iterator& operator=(charT c);
2066
 
2067
  ostreambuf_iterator& operator*();
@@ -2098,28 +2141,27 @@ ostreambuf_iterator(streambuf_type* s) noexcept;
2098
  *Effects:* Initializes `sbuf_` with `s`.
2099
 
2100
  #### `ostreambuf_iterator` operations <a id="ostreambuf.iter.ops">[[ostreambuf.iter.ops]]</a>
2101
 
2102
  ``` cpp
2103
- ostreambuf_iterator<charT,traits>&
2104
- operator=(charT c);
2105
  ```
2106
 
2107
  *Effects:* If `failed()` yields `false`, calls `sbuf_->sputc(c)`;
2108
  otherwise has no effect.
2109
 
2110
  *Returns:* `*this`.
2111
 
2112
  ``` cpp
2113
- ostreambuf_iterator<charT,traits>& operator*();
2114
  ```
2115
 
2116
  *Returns:* `*this`.
2117
 
2118
  ``` cpp
2119
- ostreambuf_iterator<charT,traits>& operator++();
2120
- ostreambuf_iterator<charT,traits>& operator++(int);
2121
  ```
2122
 
2123
  *Returns:* `*this`.
2124
 
2125
  ``` cpp
@@ -2127,28 +2169,28 @@ bool failed() const noexcept;
2127
  ```
2128
 
2129
  *Returns:* `true` if in any prior use of member `operator=`, the call to
2130
  `sbuf_->sputc()` returned `traits::eof()`; or `false` otherwise.
2131
 
2132
- ## range access <a id="iterator.range">[[iterator.range]]</a>
2133
 
2134
  In addition to being available via inclusion of the `<iterator>` header,
2135
  the function templates in [[iterator.range]] are available when any of
2136
  the following headers are included: `<array>`, `<deque>`,
2137
  `<forward_list>`, `<list>`, `<map>`, `<regex>`, `<set>`, `<string>`,
2138
- `<unordered_map>`, `<unordered_set>`, and `<vector>`.
2139
 
2140
  ``` cpp
2141
- template <class C> auto begin(C& c) -> decltype(c.begin());
2142
- template <class C> auto begin(const C& c) -> decltype(c.begin());
2143
  ```
2144
 
2145
  *Returns:* `c.begin()`.
2146
 
2147
  ``` cpp
2148
- template <class C> auto end(C& c) -> decltype(c.end());
2149
- template <class C> auto end(const C& c) -> decltype(c.end());
2150
  ```
2151
 
2152
  *Returns:* `c.end()`.
2153
 
2154
  ``` cpp
@@ -2176,71 +2218,126 @@ template <class C> constexpr auto cend(const C& c) noexcept(noexcept(std::end(c)
2176
  ```
2177
 
2178
  *Returns:* `std::end(c)`.
2179
 
2180
  ``` cpp
2181
- template <class C> auto rbegin(C& c) -> decltype(c.rbegin());
2182
- template <class C> auto rbegin(const C& c) -> decltype(c.rbegin());
2183
  ```
2184
 
2185
  *Returns:* `c.rbegin()`.
2186
 
2187
  ``` cpp
2188
- template <class C> auto rend(C& c) -> decltype(c.rend());
2189
- template <class C> auto rend(const C& c) -> decltype(c.rend());
2190
  ```
2191
 
2192
  *Returns:* `c.rend()`.
2193
 
2194
  ``` cpp
2195
- template <class T, size_t N> reverse_iterator<T*> rbegin(T (&array)[N]);
2196
  ```
2197
 
2198
  *Returns:* `reverse_iterator<T*>(array + N)`.
2199
 
2200
  ``` cpp
2201
- template <class T, size_t N> reverse_iterator<T*> rend(T (&array)[N]);
2202
  ```
2203
 
2204
  *Returns:* `reverse_iterator<T*>(array)`.
2205
 
2206
  ``` cpp
2207
- template <class E> reverse_iterator<const E*> rbegin(initializer_list<E> il);
2208
  ```
2209
 
2210
  *Returns:* `reverse_iterator<const E*>(il.end())`.
2211
 
2212
  ``` cpp
2213
- template <class E> reverse_iterator<const E*> rend(initializer_list<E> il);
2214
  ```
2215
 
2216
  *Returns:* `reverse_iterator<const E*>(il.begin())`.
2217
 
2218
  ``` cpp
2219
- template <class C> auto crbegin(const C& c) -> decltype(std::rbegin(c));
2220
  ```
2221
 
2222
  *Returns:* `std::rbegin(c)`.
2223
 
2224
  ``` cpp
2225
- template <class C> auto crend(const C& c) -> decltype(std::rend(c));
2226
  ```
2227
 
2228
  *Returns:* `std::rend(c)`.
2229
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2230
  <!-- Link reference definitions -->
2231
  [back.insert.iter.cons]: #back.insert.iter.cons
2232
  [back.insert.iter.op*]: #back.insert.iter.op*
2233
  [back.insert.iter.op++]: #back.insert.iter.op++
2234
  [back.insert.iter.op=]: #back.insert.iter.op=
2235
  [back.insert.iter.ops]: #back.insert.iter.ops
2236
  [back.insert.iterator]: #back.insert.iterator
2237
  [back.inserter]: #back.inserter
2238
  [bidirectional.iterators]: #bidirectional.iterators
2239
  [containers]: containers.md#containers
2240
- [copyassignable]: #copyassignable
2241
- [equalitycomparable]: #equalitycomparable
2242
  [forward.iterators]: #forward.iterators
2243
  [front.insert.iter.cons]: #front.insert.iter.cons
2244
  [front.insert.iter.op*]: #front.insert.iter.op*
2245
  [front.insert.iter.op++]: #front.insert.iter.op++
2246
  [front.insert.iter.op=]: #front.insert.iter.op=
@@ -2260,17 +2357,13 @@ template <class C> auto crend(const C& c) -> decltype(std::rend(c));
2260
  [istream.iterator]: #istream.iterator
2261
  [istream.iterator.cons]: #istream.iterator.cons
2262
  [istream.iterator.ops]: #istream.iterator.ops
2263
  [istreambuf.iterator]: #istreambuf.iterator
2264
  [istreambuf.iterator.cons]: #istreambuf.iterator.cons
2265
- [istreambuf.iterator::equal]: #istreambuf.iterator::equal
2266
- [istreambuf.iterator::op!=]: #istreambuf.iterator::op!=
2267
- [istreambuf.iterator::op*]: #istreambuf.iterator::op*
2268
- [istreambuf.iterator::op++]: #istreambuf.iterator::op++
2269
- [istreambuf.iterator::op==]: #istreambuf.iterator::op==
2270
- [istreambuf.iterator::proxy]: #istreambuf.iterator::proxy
2271
- [iterator.basic]: #iterator.basic
2272
  [iterator.iterators]: #iterator.iterators
2273
  [iterator.operations]: #iterator.operations
2274
  [iterator.primitives]: #iterator.primitives
2275
  [iterator.range]: #iterator.range
2276
  [iterator.requirements]: #iterator.requirements
@@ -2332,18 +2425,21 @@ template <class C> auto crend(const C& c) -> decltype(std::rend(c));
2332
  [reverse.iterators]: #reverse.iterators
2333
  [std.iterator.tags]: #std.iterator.tags
2334
  [stream.buffers]: input.md#stream.buffers
2335
  [stream.iterators]: #stream.iterators
2336
  [swappable.requirements]: library.md#swappable.requirements
 
 
2337
  [tab:iterator.bidirectional.requirements]: #tab:iterator.bidirectional.requirements
2338
  [tab:iterator.forward.requirements]: #tab:iterator.forward.requirements
2339
  [tab:iterator.input.requirements]: #tab:iterator.input.requirements
2340
  [tab:iterator.output.requirements]: #tab:iterator.output.requirements
2341
  [tab:iterator.random.access.requirements]: #tab:iterator.random.access.requirements
2342
  [tab:iterator.requirements]: #tab:iterator.requirements
2343
  [tab:iterators.lib.summary]: #tab:iterators.lib.summary
2344
  [tab:iterators.relations]: #tab:iterators.relations
 
2345
  [temp.inst]: temp.md#temp.inst
2346
  [utility.arg.requirements]: library.md#utility.arg.requirements
2347
 
2348
  [^1]: This definition applies to pointers, since pointers are iterators.
2349
  The effect of dereferencing an iterator that has been invalidated is
 
27
  Iterators are a generalization of pointers that allow a C++program to
28
  work with different data structures (containers) in a uniform manner. To
29
  be able to construct template algorithms that work correctly and
30
  efficiently on different types of data structures, the library
31
  formalizes not just the interfaces but also the semantics and complexity
32
+ assumptions of iterators. An input iterator `i` supports the expression
33
  `*i`, resulting in a value of some object type `T`, called the *value
34
+ type* of the iterator. An output iterator `i` has a non-empty set of
35
+ types that are *writable* to the iterator; for each such type `T`, the
36
+ expression `*i = o` is valid where `o` is a value of type `T`. An
37
+ iterator `i` for which the expression `(*i).m` is well-defined supports
38
  the expression `i->m` with the same semantics as `(*i).m`. For every
39
  iterator type `X` for which equality is defined, there is a
40
  corresponding signed integer type called the *difference type* of the
41
  iterator.
42
 
 
63
  be used whenever a forward iterator is specified; Random access
64
  iterators also satisfy all the requirements of bidirectional iterators
65
  and can be used whenever a bidirectional iterator is specified.
66
 
67
  Iterators that further satisfy the requirements of output iterators are
68
+ called *mutable iterators*. Nonmutable iterators are referred to as
69
+ *constant iterators*.
70
+
71
+ In addition to the requirements in this subclause, the nested
72
+ *typedef-name*s specified in [[iterator.traits]] shall be provided for
73
+ the iterator type.
74
+
75
+ [*Note 1*: Either the iterator type must provide the *typedef-name*s
76
+ directly (in which case `iterator_traits` pick them up automatically),
77
+ or an `iterator_traits` specialization must provide them. — *end note*]
78
+
79
+ Iterators that further satisfy the requirement that, for integral values
80
+ `n` and dereferenceable iterator values `a` and `(a + n)`, `*(a + n)` is
81
+ equivalent to `*(addressof(*a) + n)`, are called *contiguous iterators*.
82
+
83
+ [*Note 2*: For example, the type “pointer to `int`” is a contiguous
84
+ iterator, but `reverse_iterator<int *>` is not. For a valid iterator
85
+ range [`a`,`b`) with dereferenceable `a`, the corresponding range
86
+ denoted by pointers is [`addressof(*a)`,`addressof(*a) + (b - a)`); `b`
87
+ might not be dereferenceable. — *end note*]
88
 
89
  Just as a regular pointer to an array guarantees that there is a pointer
90
  value pointing past the last element of the array, so for any iterator
91
  type there is an iterator value that points past the last element of a
92
  corresponding sequence. These values are called *past-the-end* values.
93
  Values of an iterator `i` for which the expression `*i` is defined are
94
  called *dereferenceable*. The library never assumes that past-the-end
95
  values are dereferenceable. Iterators can also have singular values that
96
+ are not associated with any sequence.
97
+
98
+ [*Example 1*: After the declaration of an uninitialized pointer `x` (as
99
+ with `int* x;`), `x` must always be assumed to have a singular value of
100
+ a pointer. *end example*]
101
+
102
+ Results of most expressions are undefined for singular values; the only
103
+ exceptions are destroying an iterator that holds a singular value, the
104
+ assignment of a non-singular value to an iterator that holds a singular
105
+ value, and, for iterators that satisfy the `DefaultConstructible`
106
+ requirements, using a value-initialized iterator as the source of a copy
107
+ or move operation.
108
+
109
+ [*Note 3*: This guarantee is not offered for default-initialization,
110
+ although the distinction only matters for types with trivial default
111
+ constructors such as pointers or aggregates holding
112
+ pointers. — *end note*]
113
+
114
+ In these cases the singular value is overwritten the same way as any
115
+ other value. Dereferenceable values are always non-singular.
116
 
117
  An iterator `j` is called *reachable* from an iterator `i` if and only
118
  if there is a finite sequence of applications of the expression `++i`
119
  that makes `i == j`. If `j` is reachable from `i`, they refer to
120
  elements of the same sequence.
 
142
  `const X`, `difference_type` and `reference` refer to the types
143
  `iterator_traits<X>::difference_type` and
144
  `iterator_traits<X>::reference`, respectively, `n` denotes a value of
145
  `difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
146
  value of `X&`, `t` denotes a value of value type `T`, `o` denotes a
147
+ value of some type that is writable to the output iterator.
148
+
149
+ [*Note 4*: For an iterator type `X` there must be an instantiation of
150
+ `iterator_traits<X>` ([[iterator.traits]]). — *end note*]
151
 
152
  ### Iterator <a id="iterator.iterators">[[iterator.iterators]]</a>
153
 
154
  The `Iterator` requirements form the basis of the iterator concept
155
  taxonomy; every iterator satisfies the `Iterator` requirements. This set
156
  of requirements specifies operations for dereferencing and incrementing
157
  an iterator. Most algorithms will require additional operations to
158
  read ([[input.iterators]]) or write ([[output.iterators]]) values, or
159
  to provide a richer set of iterator movements ([[forward.iterators]],
160
+ [[bidirectional.iterators]], [[random.access.iterators]]).
161
 
162
  A type `X` satisfies the `Iterator` requirements if:
163
 
164
  - `X` satisfies the `CopyConstructible`, `CopyAssignable`, and
165
  `Destructible` requirements ([[utility.arg.requirements]]) and
 
168
  have the indicated semantics.
169
 
170
  ### Input iterators <a id="input.iterators">[[input.iterators]]</a>
171
 
172
  A class or pointer type `X` satisfies the requirements of an input
173
+ iterator for the value type `T` if `X` satisfies the `Iterator` (
174
  [[iterator.iterators]]) and `EqualityComparable` (Table 
175
+ [[tab:equalitycomparable]]) requirements and the expressions in Table 
176
  [[tab:iterator.input.requirements]] are valid and have the indicated
177
  semantics.
178
 
179
  In Table  [[tab:iterator.input.requirements]], the term *the domain of
180
  `==`* is used in the ordinary mathematical sense to denote the set of
181
  values over which `==` is (required to be) defined. This set can change
182
  over time. Each algorithm places additional requirements on the domain
183
  of `==` for the iterator values it uses. These requirements can be
184
+ inferred from the uses that algorithm makes of `==` and `!=`.
 
 
 
185
 
186
+ [*Example 1*: The call `find(a,b,x)` is defined only if the value of
187
+ `a` has the property *p* defined as follows: `b` has property *p* and a
188
+ value `i` has property *p* if (`*i==x`) or if (`*i!=x` and `++i` has
189
+ property *p*). — *end example*]
190
+
191
+ [*Note 1*: For input iterators, `a == b` does not imply `++a == ++b`.
192
+ (Equality does not guarantee the substitution property or referential
193
  transparency.) Algorithms on input iterators should never attempt to
194
  pass through the same iterator twice. They should be *single pass*
195
+ algorithms. Value type `T` is not required to be a `CopyAssignable` type
196
+ (Table  [[tab:copyassignable]]). These algorithms can be used with
197
+ istreams as the source of the input data through the `istream_iterator`
198
+ class template. — *end note*]
199
 
200
  ### Output iterators <a id="output.iterators">[[output.iterators]]</a>
201
 
202
  A class or pointer type `X` satisfies the requirements of an output
203
  iterator if `X` satisfies the `Iterator` requirements (
204
  [[iterator.iterators]]) and the expressions in Table 
205
  [[tab:iterator.output.requirements]] are valid and have the indicated
206
  semantics.
207
 
208
+ [*Note 1*: The only valid use of an `operator*` is on the left side of
209
+ the assignment statement. *Assignment through the same value of the
210
+ iterator happens only once.* Algorithms on output iterators should never
211
+ attempt to pass through the same iterator twice. They should be *single
212
+ pass* algorithms. Equality and inequality might not be defined.
213
+ Algorithms that take output iterators can be used with ostreams as the
214
+ destination for placing data through the `ostream_iterator` class as
215
+ well as with insert iterators and insert pointers. — *end note*]
216
 
217
  ### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
218
 
219
  A class or pointer type `X` satisfies the requirements of a forward
220
  iterator if
221
 
222
  - `X` satisfies the requirements of an input iterator (
223
  [[input.iterators]]),
224
+ - `X` satisfies the `DefaultConstructible` requirements (
225
  [[utility.arg.requirements]]),
226
  - if `X` is a mutable iterator, `reference` is a reference to `T`; if
227
+ `X` is a constant iterator, `reference` is a reference to `const T`,
228
  - the expressions in Table  [[tab:iterator.forward.requirements]] are
229
  valid and have the indicated semantics, and
230
  - objects of type `X` offer the multi-pass guarantee, described below.
231
 
232
+ The domain of `==` for forward iterators is that of iterators over the
233
  same underlying sequence. However, value-initialized iterators may be
234
  compared and shall compare equal to other value-initialized iterators of
235
+ the same type.
236
+
237
+ [*Note 1*: Value-initialized iterators behave as if they refer past the
238
+ end of the same empty sequence. — *end note*]
239
 
240
  Two dereferenceable iterators `a` and `b` of type `X` offer the
241
  *multi-pass guarantee* if:
242
 
243
  - `a == b` implies `++a == ++b` and
244
  - `X` is a pointer type or the expression `(void)++X(a), *a` is
245
  equivalent to the expression `*a`.
246
 
247
+ [*Note 2*: The requirement that `a == b` implies `++a == ++b` (which is
248
+ not true for input and output iterators) and the removal of the
249
+ restrictions on the number of the assignments through a mutable iterator
250
+ (which applies to output iterators) allows the use of multi-pass
251
+ one-directional algorithms with forward iterators. — *end note*]
252
 
253
  If `a` and `b` are equal, then either `a` and `b` are both
254
  dereferenceable or else neither is dereferenceable.
255
 
256
  If `a` and `b` are both dereferenceable, then `a == b` if and only if
 
261
  A class or pointer type `X` satisfies the requirements of a
262
  bidirectional iterator if, in addition to satisfying the requirements
263
  for forward iterators, the following expressions are valid as shown in
264
  Table  [[tab:iterator.bidirectional.requirements]].
265
 
266
+ [*Note 1*: Bidirectional iterators allow algorithms to move iterators
267
+ backward as well as forward. — *end note*]
268
 
269
  ### Random access iterators <a id="random.access.iterators">[[random.access.iterators]]</a>
270
 
271
  A class or pointer type `X` satisfies the requirements of a random
272
  access iterator if, in addition to satisfying the requirements for
 
275
 
276
  ## Header `<iterator>` synopsis <a id="iterator.synopsis">[[iterator.synopsis]]</a>
277
 
278
  ``` cpp
279
  namespace std {
280
+ // [iterator.primitives], primitives
281
  template<class Iterator> struct iterator_traits;
282
  template<class T> struct iterator_traits<T*>;
283
+ template<class T> struct iterator_traits<const T*>;
 
 
284
 
285
  struct input_iterator_tag { };
286
  struct output_iterator_tag { };
287
  struct forward_iterator_tag: public input_iterator_tag { };
288
  struct bidirectional_iterator_tag: public forward_iterator_tag { };
289
  struct random_access_iterator_tag: public bidirectional_iterator_tag { };
290
 
291
+ // [iterator.operations], iterator operations
292
  template <class InputIterator, class Distance>
293
+ constexpr void advance(InputIterator& i, Distance n);
294
  template <class InputIterator>
295
+ constexpr typename iterator_traits<InputIterator>::difference_type
296
  distance(InputIterator first, InputIterator last);
297
+ template <class InputIterator>
298
+ constexpr InputIterator next(InputIterator x,
299
+ typename iterator_traits<InputIterator>::difference_type n = 1);
300
  template <class BidirectionalIterator>
301
+ constexpr BidirectionalIterator prev(BidirectionalIterator x,
302
+ typename iterator_traits<BidirectionalIterator>::difference_type n = 1);
303
 
304
+ // [predef.iterators], predefined iterators
305
  template <class Iterator> class reverse_iterator;
306
 
307
  template <class Iterator1, class Iterator2>
308
+ constexpr bool operator==(
309
  const reverse_iterator<Iterator1>& x,
310
  const reverse_iterator<Iterator2>& y);
311
  template <class Iterator1, class Iterator2>
312
+ constexpr bool operator<(
313
  const reverse_iterator<Iterator1>& x,
314
  const reverse_iterator<Iterator2>& y);
315
  template <class Iterator1, class Iterator2>
316
+ constexpr bool operator!=(
317
  const reverse_iterator<Iterator1>& x,
318
  const reverse_iterator<Iterator2>& y);
319
  template <class Iterator1, class Iterator2>
320
+ constexpr bool operator>(
321
  const reverse_iterator<Iterator1>& x,
322
  const reverse_iterator<Iterator2>& y);
323
  template <class Iterator1, class Iterator2>
324
+ constexpr bool operator>=(
325
  const reverse_iterator<Iterator1>& x,
326
  const reverse_iterator<Iterator2>& y);
327
  template <class Iterator1, class Iterator2>
328
+ constexpr bool operator<=(
329
  const reverse_iterator<Iterator1>& x,
330
  const reverse_iterator<Iterator2>& y);
331
 
332
  template <class Iterator1, class Iterator2>
333
+ constexpr auto operator-(
334
  const reverse_iterator<Iterator1>& x,
335
  const reverse_iterator<Iterator2>& y) ->decltype(y.base() - x.base());
336
  template <class Iterator>
337
+ constexpr reverse_iterator<Iterator>
338
  operator+(
339
  typename reverse_iterator<Iterator>::difference_type n,
340
  const reverse_iterator<Iterator>& x);
341
 
342
  template <class Iterator>
343
+ constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
344
 
345
  template <class Container> class back_insert_iterator;
346
  template <class Container>
347
  back_insert_iterator<Container> back_inserter(Container& x);
348
 
 
354
  template <class Container>
355
  insert_iterator<Container> inserter(Container& x, typename Container::iterator i);
356
 
357
  template <class Iterator> class move_iterator;
358
  template <class Iterator1, class Iterator2>
359
+ constexpr bool operator==(
360
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
361
  template <class Iterator1, class Iterator2>
362
+ constexpr bool operator!=(
363
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
364
  template <class Iterator1, class Iterator2>
365
+ constexpr bool operator<(
366
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
367
  template <class Iterator1, class Iterator2>
368
+ constexpr bool operator<=(
369
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
370
  template <class Iterator1, class Iterator2>
371
+ constexpr bool operator>(
372
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
373
  template <class Iterator1, class Iterator2>
374
+ constexpr bool operator>=(
375
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
376
 
377
  template <class Iterator1, class Iterator2>
378
+ constexpr auto operator-(
379
  const move_iterator<Iterator1>& x,
380
  const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
381
  template <class Iterator>
382
+ constexpr move_iterator<Iterator> operator+(
383
  typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
384
  template <class Iterator>
385
+ constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
386
 
387
+ // [stream.iterators], stream iterators
388
  template <class T, class charT = char, class traits = char_traits<charT>,
389
  class Distance = ptrdiff_t>
390
  class istream_iterator;
391
  template <class T, class charT, class traits, class Distance>
392
  bool operator==(const istream_iterator<T,charT,traits,Distance>& x,
 
408
  const istreambuf_iterator<charT,traits>& b);
409
 
410
  template <class charT, class traits = char_traits<charT>>
411
  class ostreambuf_iterator;
412
 
413
+ // [iterator.range], range access
414
+ template <class C> constexpr auto begin(C& c) -> decltype(c.begin());
415
+ template <class C> constexpr auto begin(const C& c) -> decltype(c.begin());
416
+ template <class C> constexpr auto end(C& c) -> decltype(c.end());
417
+ template <class C> constexpr auto end(const C& c) -> decltype(c.end());
418
  template <class T, size_t N> constexpr T* begin(T (&array)[N]) noexcept;
419
  template <class T, size_t N> constexpr T* end(T (&array)[N]) noexcept;
420
  template <class C> constexpr auto cbegin(const C& c) noexcept(noexcept(std::begin(c)))
421
  -> decltype(std::begin(c));
422
  template <class C> constexpr auto cend(const C& c) noexcept(noexcept(std::end(c)))
423
  -> decltype(std::end(c));
424
+ template <class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
425
+ template <class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());
426
+ template <class C> constexpr auto rend(C& c) -> decltype(c.rend());
427
+ template <class C> constexpr auto rend(const C& c) -> decltype(c.rend());
428
+ template <class T, size_t N> constexpr reverse_iterator<T*> rbegin(T (&array)[N]);
429
+ template <class T, size_t N> constexpr reverse_iterator<T*> rend(T (&array)[N]);
430
+ template <class E> constexpr reverse_iterator<const E*> rbegin(initializer_list<E> il);
431
+ template <class E> constexpr reverse_iterator<const E*> rend(initializer_list<E> il);
432
+ template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c));
433
+ template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c));
434
+
435
+ // [iterator.container], container access
436
+ template <class C> constexpr auto size(const C& c) -> decltype(c.size());
437
+ template <class T, size_t N> constexpr size_t size(const T (&array)[N]) noexcept;
438
+ template <class C> constexpr auto empty(const C& c) -> decltype(c.empty());
439
+ template <class T, size_t N> constexpr bool empty(const T (&array)[N]) noexcept;
440
+ template <class E> constexpr bool empty(initializer_list<E> il) noexcept;
441
+ template <class C> constexpr auto data(C& c) -> decltype(c.data());
442
+ template <class C> constexpr auto data(const C& c) -> decltype(c.data());
443
+ template <class T, size_t N> constexpr T* data(T (&array)[N]) noexcept;
444
+ template <class E> constexpr const E* data(initializer_list<E> il) noexcept;
445
  }
446
  ```
447
 
448
  ## Iterator primitives <a id="iterator.primitives">[[iterator.primitives]]</a>
449
 
 
482
  iterator_traits<Iterator>::pointer
483
  ```
484
 
485
  may be defined as `void`.
486
 
487
+ If `Iterator` has valid ([[temp.deduct]]) member types
488
+ `difference_type`, `value_type`, `pointer`, `reference`, and
489
+ `iterator_category`, `iterator_traits<Iterator>` shall have the
490
+ following as publicly accessible members:
491
 
492
  ``` cpp
493
+ using difference_type = typename Iterator::difference_type;
494
+ using value_type = typename Iterator::value_type;
495
+ using pointer = typename Iterator::pointer;
496
+ using reference = typename Iterator::reference;
497
+ using iterator_category = typename Iterator::iterator_category;
 
 
 
 
498
  ```
499
 
500
+ Otherwise, `iterator_traits<Iterator>` shall have no members by any of
501
+ the above names.
502
+
503
  It is specialized for pointers as
504
 
505
  ``` cpp
506
  namespace std {
507
  template<class T> struct iterator_traits<T*> {
508
+ using difference_type = ptrdiff_t;
509
+ using value_type = T;
510
+ using pointer = T*;
511
+ using reference = T&;
512
+ using iterator_category = random_access_iterator_tag;
513
  };
514
  }
515
  ```
516
 
517
  and for pointers to const as
518
 
519
  ``` cpp
520
  namespace std {
521
  template<class T> struct iterator_traits<const T*> {
522
+ using difference_type = ptrdiff_t;
523
+ using value_type = T;
524
+ using pointer = const T*;
525
+ using reference = const T&;
526
+ using iterator_category = random_access_iterator_tag;
527
  };
528
  }
529
  ```
530
 
531
+ [*Example 1*:
532
+
533
  To implement a generic `reverse` function, a C++program can do the
534
  following:
535
 
536
  ``` cpp
537
  template <class BidirectionalIterator>
 
547
  n -= 2;
548
  }
549
  }
550
  ```
551
 
552
+ *end example*]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
553
 
554
  ### Standard iterator tags <a id="std.iterator.tags">[[std.iterator.tags]]</a>
555
 
556
  It is often desirable for a function template specialization to find out
557
  what is the most specific category of its iterator argument, so that the
 
572
  struct bidirectional_iterator_tag: public forward_iterator_tag { };
573
  struct random_access_iterator_tag: public bidirectional_iterator_tag { };
574
  }
575
  ```
576
 
577
+ [*Example 1*:
578
+
579
  For a program-defined iterator `BinaryTreeIterator`, it could be
580
  included into the bidirectional iterator category by specializing the
581
  `iterator_traits` template:
582
 
583
  ``` cpp
584
  template<class T> struct iterator_traits<BinaryTreeIterator<T>> {
585
+ using iterator_category = bidirectional_iterator_tag;
586
+ using difference_type = ptrdiff_t;
587
+ using value_type = T;
588
+ using pointer = T*;
589
+ using reference = T&;
590
  };
591
  ```
592
 
593
+ *end example*]
594
+
595
+ [*Example 2*:
596
 
597
  If `evolve()` is well defined for bidirectional iterators, but can be
598
  implemented more efficiently for random access iterators, then the
599
  implementation is as follows:
600
 
 
617
  random_access_iterator_tag) {
618
  // more efficient, but less generic algorithm
619
  }
620
  ```
621
 
622
+ *end example*]
 
 
 
 
 
 
 
 
 
 
 
623
 
624
  ### Iterator operations <a id="iterator.operations">[[iterator.operations]]</a>
625
 
626
  Since only random access iterators provide `+` and `-` operators, the
627
  library provides two function templates `advance` and `distance`. These
 
629
  therefore, constant time for them); for input, forward and bidirectional
630
  iterators they use `++` to provide linear time implementations.
631
 
632
  ``` cpp
633
  template <class InputIterator, class Distance>
634
+ constexpr void advance(InputIterator& i, Distance n);
635
  ```
636
 
637
  *Requires:* `n` shall be negative only for bidirectional and random
638
  access iterators.
639
 
640
  *Effects:* Increments (or decrements for negative `n`) iterator
641
  reference `i` by `n`.
642
 
643
  ``` cpp
644
  template <class InputIterator>
645
+ constexpr typename iterator_traits<InputIterator>::difference_type
646
  distance(InputIterator first, InputIterator last);
647
  ```
648
 
649
  *Effects:* If `InputIterator` meets the requirements of random access
650
  iterator, returns `(last - first)`; otherwise, returns the number of
 
654
  iterator, `last` shall be reachable from `first` or `first` shall be
655
  reachable from `last`; otherwise, `last` shall be reachable from
656
  `first`.
657
 
658
  ``` cpp
659
+ template <class InputIterator>
660
+ constexpr InputIterator next(InputIterator x,
661
+ typename iterator_traits<InputIterator>::difference_type n = 1);
662
  ```
663
 
664
+ *Effects:* Equivalent to: `advance(x, n); return x;`
665
 
666
  ``` cpp
667
  template <class BidirectionalIterator>
668
+ constexpr BidirectionalIterator prev(BidirectionalIterator x,
669
+ typename iterator_traits<BidirectionalIterator>::difference_type n = 1);
670
  ```
671
 
672
+ *Effects:* Equivalent to: `advance(x, -n); return x;`
673
 
674
  ## Iterator adaptors <a id="predef.iterators">[[predef.iterators]]</a>
675
 
676
  ### Reverse iterators <a id="reverse.iterators">[[reverse.iterators]]</a>
677
 
 
684
  #### Class template `reverse_iterator` <a id="reverse.iterator">[[reverse.iterator]]</a>
685
 
686
  ``` cpp
687
  namespace std {
688
  template <class Iterator>
689
+ class reverse_iterator {
 
 
 
 
 
690
  public:
691
+ using iterator_type = Iterator;
692
+ using iterator_category = typename iterator_traits<Iterator>::iterator_category;
693
+ using value_type = typename iterator_traits<Iterator>::value_type;
694
+ using difference_type = typename iterator_traits<Iterator>::difference_type;
695
+ using pointer = typename iterator_traits<Iterator>::pointer;
696
+ using reference = typename iterator_traits<Iterator>::reference;
697
 
698
+ constexpr reverse_iterator();
699
+ constexpr explicit reverse_iterator(Iterator x);
700
+ template <class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
701
+ template <class U> constexpr reverse_iterator& operator=(const reverse_iterator<U>& u);
702
 
703
+ constexpr Iterator base() const; // explicit
704
+ constexpr reference operator*() const;
705
+ constexpr pointer operator->() const;
706
 
707
+ constexpr reverse_iterator& operator++();
708
+ constexpr reverse_iterator operator++(int);
709
+ constexpr reverse_iterator& operator--();
710
+ constexpr reverse_iterator operator--(int);
711
 
712
+ constexpr reverse_iterator operator+ (difference_type n) const;
713
+ constexpr reverse_iterator& operator+=(difference_type n);
714
+ constexpr reverse_iterator operator- (difference_type n) const;
715
+ constexpr reverse_iterator& operator-=(difference_type n);
716
+ constexpr unspecified operator[](difference_type n) const;
717
  protected:
718
  Iterator current;
719
  };
720
 
721
  template <class Iterator1, class Iterator2>
722
+ constexpr bool operator==(
723
  const reverse_iterator<Iterator1>& x,
724
  const reverse_iterator<Iterator2>& y);
725
  template <class Iterator1, class Iterator2>
726
+ constexpr bool operator<(
727
  const reverse_iterator<Iterator1>& x,
728
  const reverse_iterator<Iterator2>& y);
729
  template <class Iterator1, class Iterator2>
730
+ constexpr bool operator!=(
731
  const reverse_iterator<Iterator1>& x,
732
  const reverse_iterator<Iterator2>& y);
733
  template <class Iterator1, class Iterator2>
734
+ constexpr bool operator>(
735
  const reverse_iterator<Iterator1>& x,
736
  const reverse_iterator<Iterator2>& y);
737
  template <class Iterator1, class Iterator2>
738
+ constexpr bool operator>=(
739
  const reverse_iterator<Iterator1>& x,
740
  const reverse_iterator<Iterator2>& y);
741
  template <class Iterator1, class Iterator2>
742
+ constexpr bool operator<=(
743
  const reverse_iterator<Iterator1>& x,
744
  const reverse_iterator<Iterator2>& y);
745
  template <class Iterator1, class Iterator2>
746
+ constexpr auto operator-(
747
  const reverse_iterator<Iterator1>& x,
748
  const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
749
  template <class Iterator>
750
+ constexpr reverse_iterator<Iterator> operator+(
751
  typename reverse_iterator<Iterator>::difference_type n,
752
  const reverse_iterator<Iterator>& x);
753
 
754
  template <class Iterator>
755
+ constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
756
  }
757
  ```
758
 
759
  #### `reverse_iterator` requirements <a id="reverse.iter.requirements">[[reverse.iter.requirements]]</a>
760
 
761
  The template parameter `Iterator` shall meet all the requirements of a
762
  Bidirectional Iterator ([[bidirectional.iterators]]).
763
 
764
+ Additionally, `Iterator` shall meet the requirements of a random access
765
+ iterator ([[random.access.iterators]]) if any of the members
766
  `operator+` ([[reverse.iter.op+]]), `operator-` (
767
  [[reverse.iter.op-]]), `operator+=` ([[reverse.iter.op+=]]),
768
  `operator-=` ([[reverse.iter.op-=]]), `operator[]` (
769
+ [[reverse.iter.opindex]]), or the non-member operators `operator<` (
770
  [[reverse.iter.op<]]), `operator>` ([[reverse.iter.op>]]),
771
  `operator<=` ([[reverse.iter.op<=]]), `operator>=` (
772
  [[reverse.iter.op>=]]), `operator-` ([[reverse.iter.opdiff]]) or
773
  `operator+` ([[reverse.iter.opsum]]) are referenced in a way that
774
  requires instantiation ([[temp.inst]]).
 
776
  #### `reverse_iterator` operations <a id="reverse.iter.ops">[[reverse.iter.ops]]</a>
777
 
778
  ##### `reverse_iterator` constructor <a id="reverse.iter.cons">[[reverse.iter.cons]]</a>
779
 
780
  ``` cpp
781
+ constexpr reverse_iterator();
782
  ```
783
 
784
+ *Effects:* Value-initializes `current`. Iterator operations applied to
785
  the resulting iterator have defined behavior if and only if the
786
  corresponding operations are defined on a value-initialized iterator of
787
  type `Iterator`.
788
 
789
  ``` cpp
790
+ constexpr explicit reverse_iterator(Iterator x);
791
  ```
792
 
793
  *Effects:* Initializes `current` with `x`.
794
 
795
  ``` cpp
796
+ template <class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
797
  ```
798
 
799
  *Effects:* Initializes `current` with `u.current`.
800
 
801
  ##### `reverse_iterator::operator=` <a id="reverse.iter.op=">[[reverse.iter.op=]]</a>
802
 
803
  ``` cpp
804
  template <class U>
805
+ constexpr reverse_iterator&
806
  operator=(const reverse_iterator<U>& u);
807
  ```
808
 
809
  *Effects:* Assigns `u.base()` to current.
810
 
811
  *Returns:* `*this`.
812
 
813
  ##### Conversion <a id="reverse.iter.conv">[[reverse.iter.conv]]</a>
814
 
815
  ``` cpp
816
+ constexpr Iterator base() const; // explicit
817
  ```
818
 
819
  *Returns:* `current`.
820
 
821
  ##### `operator*` <a id="reverse.iter.op.star">[[reverse.iter.op.star]]</a>
822
 
823
  ``` cpp
824
+ constexpr reference operator*() const;
825
  ```
826
 
827
+ *Effects:* As if by:
828
 
829
  ``` cpp
830
  Iterator tmp = current;
831
  return *--tmp;
832
  ```
833
 
834
  ##### `operator->` <a id="reverse.iter.opref">[[reverse.iter.opref]]</a>
835
 
836
  ``` cpp
837
+ constexpr pointer operator->() const;
838
  ```
839
 
840
+ *Returns:* `addressof(operator*())`.
841
 
842
  ##### `operator++` <a id="reverse.iter.op++">[[reverse.iter.op++]]</a>
843
 
844
  ``` cpp
845
+ constexpr reverse_iterator& operator++();
846
  ```
847
 
848
+ *Effects:* As if by: `current;`
849
 
850
  *Returns:* `*this`.
851
 
852
  ``` cpp
853
+ constexpr reverse_iterator operator++(int);
854
  ```
855
 
856
+ *Effects:* As if by:
857
 
858
  ``` cpp
859
  reverse_iterator tmp = *this;
860
  --current;
861
  return tmp;
862
  ```
863
 
864
  \[reverse.iter.op\]`operator\dcr`
865
 
866
  ``` cpp
867
+ constexpr reverse_iterator& operator--();
868
  ```
869
 
870
+ *Effects:* As if by `++current`.
871
 
872
  *Returns:* `*this`.
873
 
874
  ``` cpp
875
+ constexpr reverse_iterator operator--(int);
876
  ```
877
 
878
+ *Effects:* As if by:
879
 
880
  ``` cpp
881
  reverse_iterator tmp = *this;
882
  ++current;
883
  return tmp;
884
  ```
885
 
886
  ##### `operator+` <a id="reverse.iter.op+">[[reverse.iter.op+]]</a>
887
 
888
  ``` cpp
889
+ constexpr reverse_iterator operator+(difference_type n) const;
 
890
  ```
891
 
892
  *Returns:* `reverse_iterator(current-n)`.
893
 
894
  ##### `operator+=` <a id="reverse.iter.op+=">[[reverse.iter.op+=]]</a>
895
 
896
  ``` cpp
897
+ constexpr reverse_iterator& operator+=(difference_type n);
 
898
  ```
899
 
900
+ *Effects:* As if by: `current -= n;`
901
 
902
  *Returns:* `*this`.
903
 
904
  ##### `operator-` <a id="reverse.iter.op-">[[reverse.iter.op-]]</a>
905
 
906
  ``` cpp
907
+ constexpr reverse_iterator operator-(difference_type n) const;
 
908
  ```
909
 
910
  *Returns:* `reverse_iterator(current+n)`.
911
 
912
  ##### `operator-=` <a id="reverse.iter.op-=">[[reverse.iter.op-=]]</a>
913
 
914
  ``` cpp
915
+ constexpr reverse_iterator& operator-=(difference_type n);
 
916
  ```
917
 
918
+ *Effects:* As if by: `current += n;`
919
 
920
  *Returns:* `*this`.
921
 
922
  ##### `operator[]` <a id="reverse.iter.opindex">[[reverse.iter.opindex]]</a>
923
 
924
  ``` cpp
925
+ constexpr unspecified operator[](difference_type n) const;
 
926
  ```
927
 
928
  *Returns:* `current[-n-1]`.
929
 
930
  ##### `operator==` <a id="reverse.iter.op==">[[reverse.iter.op==]]</a>
931
 
932
  ``` cpp
933
  template <class Iterator1, class Iterator2>
934
+ constexpr bool operator==(
935
  const reverse_iterator<Iterator1>& x,
936
  const reverse_iterator<Iterator2>& y);
937
  ```
938
 
939
  *Returns:* `x.current == y.current`.
940
 
941
  ##### `operator<` <a id="reverse.iter.op<">[[reverse.iter.op<]]</a>
942
 
943
  ``` cpp
944
  template <class Iterator1, class Iterator2>
945
+ constexpr bool operator<(
946
  const reverse_iterator<Iterator1>& x,
947
  const reverse_iterator<Iterator2>& y);
948
  ```
949
 
950
  *Returns:* `x.current > y.current`.
951
 
952
  ##### `operator!=` <a id="reverse.iter.op!=">[[reverse.iter.op!=]]</a>
953
 
954
  ``` cpp
955
  template <class Iterator1, class Iterator2>
956
+ constexpr bool operator!=(
957
  const reverse_iterator<Iterator1>& x,
958
  const reverse_iterator<Iterator2>& y);
959
  ```
960
 
961
  *Returns:* `x.current != y.current`.
962
 
963
  ##### `operator>` <a id="reverse.iter.op>">[[reverse.iter.op>]]</a>
964
 
965
  ``` cpp
966
  template <class Iterator1, class Iterator2>
967
+ constexpr bool operator>(
968
  const reverse_iterator<Iterator1>& x,
969
  const reverse_iterator<Iterator2>& y);
970
  ```
971
 
972
  *Returns:* `x.current < y.current`.
973
 
974
  ##### `operator>=` <a id="reverse.iter.op>=">[[reverse.iter.op>=]]</a>
975
 
976
  ``` cpp
977
  template <class Iterator1, class Iterator2>
978
+ constexpr bool operator>=(
979
  const reverse_iterator<Iterator1>& x,
980
  const reverse_iterator<Iterator2>& y);
981
  ```
982
 
983
  *Returns:* `x.current <= y.current`.
984
 
985
  ##### `operator<=` <a id="reverse.iter.op<=">[[reverse.iter.op<=]]</a>
986
 
987
  ``` cpp
988
  template <class Iterator1, class Iterator2>
989
+ constexpr bool operator<=(
990
  const reverse_iterator<Iterator1>& x,
991
  const reverse_iterator<Iterator2>& y);
992
  ```
993
 
994
  *Returns:* `x.current >= y.current`.
995
 
996
  ##### `operator-` <a id="reverse.iter.opdiff">[[reverse.iter.opdiff]]</a>
997
 
998
  ``` cpp
999
  template <class Iterator1, class Iterator2>
1000
+ constexpr auto operator-(
1001
  const reverse_iterator<Iterator1>& x,
1002
  const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
1003
  ```
1004
 
1005
  *Returns:* `y.current - x.current`.
1006
 
1007
  ##### `operator+` <a id="reverse.iter.opsum">[[reverse.iter.opsum]]</a>
1008
 
1009
  ``` cpp
1010
  template <class Iterator>
1011
+ constexpr reverse_iterator<Iterator> operator+(
1012
  typename reverse_iterator<Iterator>::difference_type n,
1013
  const reverse_iterator<Iterator>& x);
1014
  ```
1015
 
1016
  *Returns:* `reverse_iterator<Iterator> (x.current - n)`.
1017
 
1018
  ##### Non-member function `make_reverse_iterator()` <a id="reverse.iter.make">[[reverse.iter.make]]</a>
1019
 
1020
  ``` cpp
1021
  template <class Iterator>
1022
+ constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
1023
  ```
1024
 
1025
  *Returns:* `reverse_iterator<Iterator>(i)`.
1026
 
1027
  ### Insert iterators <a id="insert.iterators">[[insert.iterators]]</a>
 
1058
  #### Class template `back_insert_iterator` <a id="back.insert.iterator">[[back.insert.iterator]]</a>
1059
 
1060
  ``` cpp
1061
  namespace std {
1062
  template <class Container>
1063
+ class back_insert_iterator {
 
1064
  protected:
1065
  Container* container;
1066
 
1067
  public:
1068
+ using iterator_category = output_iterator_tag;
1069
+ using value_type = void;
1070
+ using difference_type = void;
1071
+ using pointer = void;
1072
+ using reference = void;
1073
+ using container_type = Container;
1074
+
1075
  explicit back_insert_iterator(Container& x);
1076
+ back_insert_iterator& operator=(const typename Container::value_type& value);
1077
+ back_insert_iterator& operator=(typename Container::value_type&& value);
 
 
1078
 
1079
+ back_insert_iterator& operator*();
1080
+ back_insert_iterator& operator++();
1081
+ back_insert_iterator operator++(int);
1082
  };
1083
 
1084
  template <class Container>
1085
  back_insert_iterator<Container> back_inserter(Container& x);
1086
  }
 
1092
 
1093
  ``` cpp
1094
  explicit back_insert_iterator(Container& x);
1095
  ```
1096
 
1097
+ *Effects:* Initializes `container` with `addressof(x)`.
1098
 
1099
  ##### `back_insert_iterator::operator=` <a id="back.insert.iter.op=">[[back.insert.iter.op=]]</a>
1100
 
1101
  ``` cpp
1102
+ back_insert_iterator& operator=(const typename Container::value_type& value);
 
1103
  ```
1104
 
1105
+ *Effects:* As if by: `container->push_back(value);`
1106
 
1107
  *Returns:* `*this`.
1108
 
1109
  ``` cpp
1110
+ back_insert_iterator& operator=(typename Container::value_type&& value);
 
1111
  ```
1112
 
1113
+ *Effects:* As if by: `container->push_back(std::move(value));`
1114
 
1115
  *Returns:* `*this`.
1116
 
1117
  ##### `back_insert_iterator::operator*` <a id="back.insert.iter.op*">[[back.insert.iter.op*]]</a>
1118
 
1119
  ``` cpp
1120
+ back_insert_iterator& operator*();
1121
  ```
1122
 
1123
  *Returns:* `*this`.
1124
 
1125
  ##### `back_insert_iterator::operator++` <a id="back.insert.iter.op++">[[back.insert.iter.op++]]</a>
1126
 
1127
  ``` cpp
1128
+ back_insert_iterator& operator++();
1129
+ back_insert_iterator operator++(int);
1130
  ```
1131
 
1132
  *Returns:* `*this`.
1133
 
1134
  ##### `back_inserter` <a id="back.inserter">[[back.inserter]]</a>
 
1143
  #### Class template `front_insert_iterator` <a id="front.insert.iterator">[[front.insert.iterator]]</a>
1144
 
1145
  ``` cpp
1146
  namespace std {
1147
  template <class Container>
1148
+ class front_insert_iterator {
 
1149
  protected:
1150
  Container* container;
1151
 
1152
  public:
1153
+ using iterator_category = output_iterator_tag;
1154
+ using value_type = void;
1155
+ using difference_type = void;
1156
+ using pointer = void;
1157
+ using reference = void;
1158
+ using container_type = Container;
1159
+
1160
  explicit front_insert_iterator(Container& x);
1161
+ front_insert_iterator& operator=(const typename Container::value_type& value);
1162
+ front_insert_iterator& operator=(typename Container::value_type&& value);
 
 
1163
 
1164
+ front_insert_iterator& operator*();
1165
+ front_insert_iterator& operator++();
1166
+ front_insert_iterator operator++(int);
1167
  };
1168
 
1169
  template <class Container>
1170
  front_insert_iterator<Container> front_inserter(Container& x);
1171
  }
 
1177
 
1178
  ``` cpp
1179
  explicit front_insert_iterator(Container& x);
1180
  ```
1181
 
1182
+ *Effects:* Initializes `container` with `addressof(x)`.
1183
 
1184
  ##### `front_insert_iterator::operator=` <a id="front.insert.iter.op=">[[front.insert.iter.op=]]</a>
1185
 
1186
  ``` cpp
1187
+ front_insert_iterator& operator=(const typename Container::value_type& value);
 
1188
  ```
1189
 
1190
+ *Effects:* As if by: `container->push_front(value);`
1191
 
1192
  *Returns:* `*this`.
1193
 
1194
  ``` cpp
1195
+ front_insert_iterator& operator=(typename Container::value_type&& value);
 
1196
  ```
1197
 
1198
+ *Effects:* As if by: `container->push_front(std::move(value));`
1199
 
1200
  *Returns:* `*this`.
1201
 
1202
  ##### `front_insert_iterator::operator*` <a id="front.insert.iter.op*">[[front.insert.iter.op*]]</a>
1203
 
1204
  ``` cpp
1205
+ front_insert_iterator& operator*();
1206
  ```
1207
 
1208
  *Returns:* `*this`.
1209
 
1210
  ##### `front_insert_iterator::operator++` <a id="front.insert.iter.op++">[[front.insert.iter.op++]]</a>
1211
 
1212
  ``` cpp
1213
+ front_insert_iterator& operator++();
1214
+ front_insert_iterator operator++(int);
1215
  ```
1216
 
1217
  *Returns:* `*this`.
1218
 
1219
  ##### `front_inserter` <a id="front.inserter">[[front.inserter]]</a>
 
1228
  #### Class template `insert_iterator` <a id="insert.iterator">[[insert.iterator]]</a>
1229
 
1230
  ``` cpp
1231
  namespace std {
1232
  template <class Container>
1233
+ class insert_iterator {
 
1234
  protected:
1235
  Container* container;
1236
  typename Container::iterator iter;
1237
 
1238
  public:
1239
+ using iterator_category = output_iterator_tag;
1240
+ using value_type = void;
1241
+ using difference_type = void;
1242
+ using pointer = void;
1243
+ using reference = void;
1244
+ using container_type = Container;
1245
+
1246
  insert_iterator(Container& x, typename Container::iterator i);
1247
+ insert_iterator& operator=(const typename Container::value_type& value);
1248
+ insert_iterator& operator=(typename Container::value_type&& value);
 
 
1249
 
1250
+ insert_iterator& operator*();
1251
+ insert_iterator& operator++();
1252
+ insert_iterator& operator++(int);
1253
  };
1254
 
1255
  template <class Container>
1256
  insert_iterator<Container> inserter(Container& x, typename Container::iterator i);
1257
  }
 
1263
 
1264
  ``` cpp
1265
  insert_iterator(Container& x, typename Container::iterator i);
1266
  ```
1267
 
1268
+ *Effects:* Initializes `container` with `addressof(x)` and `iter` with
1269
+ `i`.
1270
 
1271
  ##### `insert_iterator::operator=` <a id="insert.iter.op=">[[insert.iter.op=]]</a>
1272
 
1273
  ``` cpp
1274
+ insert_iterator& operator=(const typename Container::value_type& value);
 
1275
  ```
1276
 
1277
+ *Effects:* As if by:
1278
 
1279
  ``` cpp
1280
  iter = container->insert(iter, value);
1281
  ++iter;
1282
  ```
1283
 
1284
  *Returns:* `*this`.
1285
 
1286
  ``` cpp
1287
+ insert_iterator& operator=(typename Container::value_type&& value);
 
1288
  ```
1289
 
1290
+ *Effects:* As if by:
1291
 
1292
  ``` cpp
1293
  iter = container->insert(iter, std::move(value));
1294
  ++iter;
1295
  ```
 
1297
  *Returns:* `*this`.
1298
 
1299
  ##### `insert_iterator::operator*` <a id="insert.iter.op*">[[insert.iter.op*]]</a>
1300
 
1301
  ``` cpp
1302
+ insert_iterator& operator*();
1303
  ```
1304
 
1305
  *Returns:* `*this`.
1306
 
1307
  ##### `insert_iterator::operator++` <a id="insert.iter.op++">[[insert.iter.op++]]</a>
1308
 
1309
  ``` cpp
1310
+ insert_iterator& operator++();
1311
+ insert_iterator& operator++(int);
1312
  ```
1313
 
1314
  *Returns:* `*this`.
1315
 
1316
  ##### `inserter` <a id="inserter">[[inserter]]</a>
 
1325
  ### Move iterators <a id="move.iterators">[[move.iterators]]</a>
1326
 
1327
  Class template `move_iterator` is an iterator adaptor with the same
1328
  behavior as the underlying iterator except that its indirection operator
1329
  implicitly converts the value returned by the underlying iterator’s
1330
+ indirection operator to an rvalue. Some generic algorithms can be called
1331
+ with move iterators to replace copying with moving.
1332
+
1333
+ [*Example 1*:
1334
 
1335
  ``` cpp
1336
  list<string> s;
1337
  // populate the list s
1338
  vector<string> v1(s.begin(), s.end()); // copies strings into v1
1339
  vector<string> v2(make_move_iterator(s.begin()),
1340
  make_move_iterator(s.end())); // moves strings into v2
1341
  ```
1342
 
1343
+ — *end example*]
1344
+
1345
  #### Class template `move_iterator` <a id="move.iterator">[[move.iterator]]</a>
1346
 
1347
  ``` cpp
1348
  namespace std {
1349
  template <class Iterator>
1350
  class move_iterator {
1351
  public:
1352
+ using iterator_type = Iterator;
1353
+ using iterator_category = typename iterator_traits<Iterator>::iterator_category;
1354
+ using value_type = typename iterator_traits<Iterator>::value_type;
1355
+ using difference_type = typename iterator_traits<Iterator>::difference_type;
1356
+ using pointer = Iterator;
1357
+ using reference = see below;
1358
 
1359
+ constexpr move_iterator();
1360
+ constexpr explicit move_iterator(Iterator i);
1361
+ template <class U> constexpr move_iterator(const move_iterator<U>& u);
1362
+ template <class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
1363
 
1364
+ constexpr iterator_type base() const;
1365
+ constexpr reference operator*() const;
1366
+ constexpr pointer operator->() const;
1367
 
1368
+ constexpr move_iterator& operator++();
1369
+ constexpr move_iterator operator++(int);
1370
+ constexpr move_iterator& operator--();
1371
+ constexpr move_iterator operator--(int);
1372
 
1373
+ constexpr move_iterator operator+(difference_type n) const;
1374
+ constexpr move_iterator& operator+=(difference_type n);
1375
+ constexpr move_iterator operator-(difference_type n) const;
1376
+ constexpr move_iterator& operator-=(difference_type n);
1377
+ constexpr unspecified operator[](difference_type n) const;
1378
 
1379
  private:
1380
  Iterator current; // exposition only
1381
  };
1382
 
1383
  template <class Iterator1, class Iterator2>
1384
+ constexpr bool operator==(
1385
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1386
  template <class Iterator1, class Iterator2>
1387
+ constexpr bool operator!=(
1388
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1389
  template <class Iterator1, class Iterator2>
1390
+ constexpr bool operator<(
1391
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1392
  template <class Iterator1, class Iterator2>
1393
+ constexpr bool operator<=(
1394
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1395
  template <class Iterator1, class Iterator2>
1396
+ constexpr bool operator>(
1397
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1398
  template <class Iterator1, class Iterator2>
1399
+ constexpr bool operator>=(
1400
  const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1401
 
1402
  template <class Iterator1, class Iterator2>
1403
+ constexpr auto operator-(
1404
  const move_iterator<Iterator1>& x,
1405
  const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
1406
  template <class Iterator>
1407
+ constexpr move_iterator<Iterator> operator+(
1408
  typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
1409
  template <class Iterator>
1410
+ constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
1411
  }
1412
  ```
1413
 
1414
+ Let `R` denote `iterator_traits<Iterator>::reference`. If
1415
+ `is_reference_v<R>` is `true`, the template specialization
1416
+ `move_iterator<Iterator>` shall define the nested type named `reference`
1417
+ as a synonym for `remove_reference_t<R>&&`, otherwise as a synonym for
1418
+ `R`.
1419
+
1420
  #### `move_iterator` requirements <a id="move.iter.requirements">[[move.iter.requirements]]</a>
1421
 
1422
+ The template parameter `Iterator` shall meet the requirements of an
1423
+ input iterator ([[input.iterators]]). Additionally, if any of the
1424
  bidirectional or random access traversal functions are instantiated, the
1425
  template parameter shall meet the requirements for a Bidirectional
1426
  Iterator ([[bidirectional.iterators]]) or a Random Access Iterator (
1427
  [[random.access.iterators]]), respectively.
1428
 
1429
  #### `move_iterator` operations <a id="move.iter.ops">[[move.iter.ops]]</a>
1430
 
1431
  ##### `move_iterator` constructors <a id="move.iter.op.const">[[move.iter.op.const]]</a>
1432
 
1433
  ``` cpp
1434
+ constexpr move_iterator();
1435
  ```
1436
 
1437
+ *Effects:* Constructs a `move_iterator`, value-initializing `current`.
1438
  Iterator operations applied to the resulting iterator have defined
1439
  behavior if and only if the corresponding operations are defined on a
1440
  value-initialized iterator of type `Iterator`.
1441
 
1442
  ``` cpp
1443
+ constexpr explicit move_iterator(Iterator i);
1444
  ```
1445
 
1446
  *Effects:* Constructs a `move_iterator`, initializing `current` with
1447
  `i`.
1448
 
1449
  ``` cpp
1450
+ template <class U> constexpr move_iterator(const move_iterator<U>& u);
1451
  ```
1452
 
1453
  *Effects:* Constructs a `move_iterator`, initializing `current` with
1454
  `u.base()`.
1455
 
1456
  *Requires:* `U` shall be convertible to `Iterator`.
1457
 
1458
  ##### `move_iterator::operator=` <a id="move.iter.op=">[[move.iter.op=]]</a>
1459
 
1460
  ``` cpp
1461
+ template <class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
1462
  ```
1463
 
1464
  *Effects:* Assigns `u.base()` to `current`.
1465
 
1466
  *Requires:* `U` shall be convertible to `Iterator`.
1467
 
1468
  ##### `move_iterator` conversion <a id="move.iter.op.conv">[[move.iter.op.conv]]</a>
1469
 
1470
  ``` cpp
1471
+ constexpr Iterator base() const;
1472
  ```
1473
 
1474
  *Returns:* `current`.
1475
 
1476
  ##### `move_iterator::operator*` <a id="move.iter.op.star">[[move.iter.op.star]]</a>
1477
 
1478
  ``` cpp
1479
+ constexpr reference operator*() const;
1480
  ```
1481
 
1482
+ *Returns:* `static_cast<reference>(*current)`.
1483
 
1484
  ##### `move_iterator::operator->` <a id="move.iter.op.ref">[[move.iter.op.ref]]</a>
1485
 
1486
  ``` cpp
1487
+ constexpr pointer operator->() const;
1488
  ```
1489
 
1490
  *Returns:* `current`.
1491
 
1492
  ##### `move_iterator::operator++` <a id="move.iter.op.incr">[[move.iter.op.incr]]</a>
1493
 
1494
  ``` cpp
1495
+ constexpr move_iterator& operator++();
1496
  ```
1497
 
1498
+ *Effects:* As if by `++current`.
1499
 
1500
  *Returns:* `*this`.
1501
 
1502
  ``` cpp
1503
+ constexpr move_iterator operator++(int);
1504
  ```
1505
 
1506
+ *Effects:* As if by:
1507
 
1508
  ``` cpp
1509
  move_iterator tmp = *this;
1510
  ++current;
1511
  return tmp;
1512
  ```
1513
 
1514
  ##### `move_iterator::operator-{-}` <a id="move.iter.op.decr">[[move.iter.op.decr]]</a>
1515
 
1516
  ``` cpp
1517
+ constexpr move_iterator& operator--();
1518
  ```
1519
 
1520
+ *Effects:* As if by `current`.
1521
 
1522
  *Returns:* `*this`.
1523
 
1524
  ``` cpp
1525
+ constexpr move_iterator operator--(int);
1526
  ```
1527
 
1528
+ *Effects:* As if by:
1529
 
1530
  ``` cpp
1531
  move_iterator tmp = *this;
1532
  --current;
1533
  return tmp;
1534
  ```
1535
 
1536
  ##### `move_iterator::operator+` <a id="move.iter.op.+">[[move.iter.op.+]]</a>
1537
 
1538
  ``` cpp
1539
+ constexpr move_iterator operator+(difference_type n) const;
1540
  ```
1541
 
1542
  *Returns:* `move_iterator(current + n)`.
1543
 
1544
  ##### `move_iterator::operator+=` <a id="move.iter.op.+=">[[move.iter.op.+=]]</a>
1545
 
1546
  ``` cpp
1547
+ constexpr move_iterator& operator+=(difference_type n);
1548
  ```
1549
 
1550
+ *Effects:* As if by: `current += n;`
1551
 
1552
  *Returns:* `*this`.
1553
 
1554
  ##### `move_iterator::operator-` <a id="move.iter.op.-">[[move.iter.op.-]]</a>
1555
 
1556
  ``` cpp
1557
+ constexpr move_iterator operator-(difference_type n) const;
1558
  ```
1559
 
1560
  *Returns:* `move_iterator(current - n)`.
1561
 
1562
  ##### `move_iterator::operator-=` <a id="move.iter.op.-=">[[move.iter.op.-=]]</a>
1563
 
1564
  ``` cpp
1565
+ constexpr move_iterator& operator-=(difference_type n);
1566
  ```
1567
 
1568
+ *Effects:* As if by: `current -= n;`
1569
 
1570
  *Returns:* `*this`.
1571
 
1572
  ##### `move_iterator::operator[]` <a id="move.iter.op.index">[[move.iter.op.index]]</a>
1573
 
1574
  ``` cpp
1575
+ constexpr unspecified operator[](difference_type n) const;
1576
  ```
1577
 
1578
+ *Returns:* `std::move(current[n])`.
1579
 
1580
  ##### `move_iterator` comparisons <a id="move.iter.op.comp">[[move.iter.op.comp]]</a>
1581
 
1582
  ``` cpp
1583
  template <class Iterator1, class Iterator2>
1584
+ constexpr bool operator==(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1585
  ```
1586
 
1587
  *Returns:* `x.base() == y.base()`.
1588
 
1589
  ``` cpp
1590
  template <class Iterator1, class Iterator2>
1591
+ constexpr bool operator!=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1592
  ```
1593
 
1594
  *Returns:* `!(x == y)`.
1595
 
1596
  ``` cpp
1597
  template <class Iterator1, class Iterator2>
1598
+ constexpr bool operator<(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1599
  ```
1600
 
1601
  *Returns:* `x.base() < y.base()`.
1602
 
1603
  ``` cpp
1604
  template <class Iterator1, class Iterator2>
1605
+ constexpr bool operator<=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1606
  ```
1607
 
1608
  *Returns:* `!(y < x)`.
1609
 
1610
  ``` cpp
1611
  template <class Iterator1, class Iterator2>
1612
+ constexpr bool operator>(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1613
  ```
1614
 
1615
  *Returns:* `y < x`.
1616
 
1617
  ``` cpp
1618
  template <class Iterator1, class Iterator2>
1619
+ constexpr bool operator>=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1620
  ```
1621
 
1622
  *Returns:* `!(x < y)`.
1623
 
1624
  ##### `move_iterator` non-member functions <a id="move.iter.nonmember">[[move.iter.nonmember]]</a>
1625
 
1626
  ``` cpp
1627
  template <class Iterator1, class Iterator2>
1628
+ constexpr auto operator-(
1629
  const move_iterator<Iterator1>& x,
1630
  const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
1631
  ```
1632
 
1633
  *Returns:* `x.base() - y.base()`.
1634
 
1635
  ``` cpp
1636
  template <class Iterator>
1637
+ constexpr move_iterator<Iterator> operator+(
1638
  typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
1639
  ```
1640
 
1641
  *Returns:* `x + n`.
1642
 
1643
  ``` cpp
1644
  template <class Iterator>
1645
+ constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
1646
  ```
1647
 
1648
  *Returns:* `move_iterator<Iterator>(i)`.
1649
 
1650
  ## Stream iterators <a id="stream.iterators">[[stream.iterators]]</a>
1651
 
1652
  To make it possible for algorithmic templates to work directly with
1653
  input/output streams, appropriate iterator-like class templates are
1654
  provided.
1655
 
1656
+ [*Example 1*:
1657
+
1658
  ``` cpp
1659
  partial_sum(istream_iterator<double, char>(cin),
1660
  istream_iterator<double, char>(),
1661
  ostream_iterator<double, char>(cout, "\n"));
1662
  ```
1663
 
1664
+ reads a file containing floating-point numbers from `cin`, and prints
1665
  the partial sums onto `cout`.
1666
 
1667
+ — *end example*]
1668
+
1669
  ### Class template `istream_iterator` <a id="istream.iterator">[[istream.iterator]]</a>
1670
 
1671
  The class template `istream_iterator` is an input iterator (
1672
  [[input.iterators]]) that reads (using `operator>>`) successive elements
1673
  from the input stream for which it was constructed. After it is
 
1680
  condition. The result of `operator*` on an end-of-stream iterator is not
1681
  defined. For any other iterator value a `const T&` is returned. The
1682
  result of `operator->` on an end-of-stream iterator is not defined. For
1683
  any other iterator value a `const T*` is returned. The behavior of a
1684
  program that applies `operator++()` to an end-of-stream iterator is
1685
+ undefined. It is impossible to store things into istream iterators. The
1686
+ type `T` shall meet the `DefaultConstructible`, `CopyConstructible`, and
1687
+ `CopyAssignable` requirements.
1688
 
1689
  Two end-of-stream iterators are always equal. An end-of-stream iterator
1690
  is not equal to a non-end-of-stream iterator. Two non-end-of-stream
1691
  iterators are equal when they are constructed from the same stream.
1692
 
1693
  ``` cpp
1694
  namespace std {
1695
  template <class T, class charT = char, class traits = char_traits<charT>,
1696
  class Distance = ptrdiff_t>
1697
+ class istream_iterator {
 
1698
  public:
1699
+ using iterator_category = input_iterator_tag;
1700
+ using value_type = T;
1701
+ using difference_type = Distance;
1702
+ using pointer = const T*;
1703
+ using reference = const T&;
1704
+ using char_type = charT;
1705
+ using traits_type = traits;
1706
+ using istream_type = basic_istream<charT,traits>;
1707
+
1708
+ constexpr istream_iterator();
1709
  istream_iterator(istream_type& s);
1710
  istream_iterator(const istream_iterator& x) = default;
1711
  ~istream_iterator() = default;
1712
 
1713
  const T& operator*() const;
1714
  const T* operator->() const;
1715
+ istream_iterator& operator++();
1716
+ istream_iterator operator++(int);
1717
  private:
1718
  basic_istream<charT,traits>* in_stream; // exposition only
1719
  T value; // exposition only
1720
  };
1721
 
 
1729
  ```
1730
 
1731
  #### `istream_iterator` constructors and destructor <a id="istream.iterator.cons">[[istream.iterator.cons]]</a>
1732
 
1733
  ``` cpp
1734
+ constexpr istream_iterator();
1735
  ```
1736
 
1737
+ *Effects:* Constructs the end-of-stream iterator. If
1738
+ `is_trivially_default_constructible_v<T>` is `true`, then this
1739
+ constructor is a constexpr constructor.
1740
 
1741
+ *Postconditions:* `in_stream == 0`.
1742
 
1743
  ``` cpp
1744
  istream_iterator(istream_type& s);
1745
  ```
1746
 
1747
+ *Effects:* Initializes `in_stream` with `addressof(s)`. `value` may be
1748
+ initialized during construction or the first time it is referenced.
1749
 
1750
+ *Postconditions:* `in_stream == addressof(s)`.
1751
 
1752
  ``` cpp
1753
  istream_iterator(const istream_iterator& x) = default;
1754
  ```
1755
 
1756
+ *Effects:* Constructs a copy of `x`. If
1757
+ `is_trivially_copy_constructible_v<T>` is `true`, then this constructor
1758
+ is a trivial copy constructor.
1759
 
1760
+ *Postconditions:* `in_stream == x.in_stream`.
1761
 
1762
  ``` cpp
1763
  ~istream_iterator() = default;
1764
  ```
1765
 
1766
+ *Effects:* The iterator is destroyed. If
1767
+ `is_trivially_destructible_v<T>` is `true`, then this destructor is a
1768
+ trivial destructor.
1769
 
1770
  #### `istream_iterator` operations <a id="istream.iterator.ops">[[istream.iterator.ops]]</a>
1771
 
1772
  ``` cpp
1773
  const T& operator*() const;
1774
  ```
1775
 
1776
+ *Returns:* `value`.
1777
 
1778
  ``` cpp
1779
  const T* operator->() const;
1780
  ```
1781
 
1782
+ *Returns:* `addressof(operator*())`.
1783
 
1784
  ``` cpp
1785
+ istream_iterator& operator++();
1786
  ```
1787
 
1788
  *Requires:* `in_stream != 0`.
1789
 
1790
+ *Effects:* As if by: `*in_stream >> value;`
1791
 
1792
  *Returns:* `*this`.
1793
 
1794
  ``` cpp
1795
+ istream_iterator operator++(int);
1796
  ```
1797
 
1798
  *Requires:* `in_stream != 0`.
1799
 
1800
+ *Effects:* As if by:
1801
 
1802
  ``` cpp
1803
+ istream_iterator tmp = *this;
1804
  *in_stream >> value;
1805
  return (tmp);
1806
  ```
1807
 
1808
  ``` cpp
 
1840
  is defined as:
1841
 
1842
  ``` cpp
1843
  namespace std {
1844
  template <class T, class charT = char, class traits = char_traits<charT>>
1845
+ class ostream_iterator {
 
1846
  public:
1847
+ using iterator_category = output_iterator_tag;
1848
+ using value_type = void;
1849
+ using difference_type = void;
1850
+ using pointer = void;
1851
+ using reference = void;
1852
+ using char_type = charT;
1853
+ using traits_type = traits;
1854
+ using ostream_type = basic_ostream<charT,traits>;
1855
+
1856
  ostream_iterator(ostream_type& s);
1857
  ostream_iterator(ostream_type& s, const charT* delimiter);
1858
+ ostream_iterator(const ostream_iterator& x);
1859
  ~ostream_iterator();
1860
+ ostream_iterator& operator=(const T& value);
1861
 
1862
+ ostream_iterator& operator*();
1863
+ ostream_iterator& operator++();
1864
+ ostream_iterator& operator++(int);
1865
  private:
1866
  basic_ostream<charT,traits>* out_stream; // exposition only
1867
  const charT* delim; // exposition only
1868
  };
1869
  }
 
1873
 
1874
  ``` cpp
1875
  ostream_iterator(ostream_type& s);
1876
  ```
1877
 
1878
+ *Effects:* Initializes `out_stream` with `addressof(s)` and `delim` with
1879
+ null.
1880
 
1881
  ``` cpp
1882
  ostream_iterator(ostream_type& s, const charT* delimiter);
1883
  ```
1884
 
1885
+ *Effects:* Initializes `out_stream` with `addressof(s)` and `delim` with
1886
  `delimiter`.
1887
 
1888
  ``` cpp
1889
  ostream_iterator(const ostream_iterator& x);
1890
  ```
 
1901
 
1902
  ``` cpp
1903
  ostream_iterator& operator=(const T& value);
1904
  ```
1905
 
1906
+ *Effects:* As if by:
1907
 
1908
  ``` cpp
1909
  *out_stream << value;
1910
  if (delim != 0)
1911
  *out_stream << delim;
 
1928
  ### Class template `istreambuf_iterator` <a id="istreambuf.iterator">[[istreambuf.iterator]]</a>
1929
 
1930
  The class template `istreambuf_iterator` defines an input iterator (
1931
  [[input.iterators]]) that reads successive *characters* from the
1932
  streambuf for which it was constructed. `operator*` provides access to
1933
+ the current input character, if any. Each time `operator++` is
1934
+ evaluated, the iterator advances to the next input character. If the end
1935
+ of stream is reached (`streambuf_type::sgetc()` returns
1936
+ `traits::eof()`), the iterator becomes equal to the *end-of-stream*
1937
+ iterator value. The default constructor `istreambuf_iterator()` and the
1938
+ constructor `istreambuf_iterator(0)` both construct an end-of-stream
1939
+ iterator object suitable for use as an end-of-range. All specializations
1940
+ of `istreambuf_iterator` shall have a trivial copy constructor, a
 
1941
  `constexpr` default constructor, and a trivial destructor.
1942
 
1943
  The result of `operator*()` on an end-of-stream iterator is undefined.
1944
  For any other iterator value a `char_type` value is returned. It is
1945
  impossible to assign a character via an input iterator.
1946
 
1947
  ``` cpp
1948
  namespace std {
1949
  template<class charT, class traits = char_traits<charT>>
1950
+ class istreambuf_iterator {
 
 
1951
  public:
1952
+ using iterator_category = input_iterator_tag;
1953
+ using value_type = charT;
1954
+ using difference_type = typename traits::off_type;
1955
+ using pointer = unspecified;
1956
+ using reference = charT;
1957
+ using char_type = charT;
1958
+ using traits_type = traits;
1959
+ using int_type = typename traits::int_type;
1960
+ using streambuf_type = basic_streambuf<charT,traits>;
1961
+ using istream_type = basic_istream<charT,traits>;
1962
 
1963
  class proxy; // exposition only
1964
 
1965
  constexpr istreambuf_iterator() noexcept;
1966
  istreambuf_iterator(const istreambuf_iterator&) noexcept = default;
1967
  ~istreambuf_iterator() = default;
1968
  istreambuf_iterator(istream_type& s) noexcept;
1969
  istreambuf_iterator(streambuf_type* s) noexcept;
1970
  istreambuf_iterator(const proxy& p) noexcept;
1971
  charT operator*() const;
1972
+ istreambuf_iterator& operator++();
 
1973
  proxy operator++(int);
1974
  bool equal(const istreambuf_iterator& b) const;
1975
  private:
1976
  streambuf_type* sbuf_; // exposition only
1977
  };
 
1983
  bool operator!=(const istreambuf_iterator<charT,traits>& a,
1984
  const istreambuf_iterator<charT,traits>& b);
1985
  }
1986
  ```
1987
 
1988
+ #### Class template `istreambuf_iterator::proxy` <a id="istreambuf.iterator.proxy">[[istreambuf.iterator.proxy]]</a>
1989
 
1990
  ``` cpp
1991
  namespace std {
1992
  template <class charT, class traits = char_traits<charT>>
1993
  class istreambuf_iterator<charT, traits>::proxy { // exposition only
 
2009
  (`operator++`). It keeps the character pointed to by the previous value
2010
  of the iterator for some possible future access to get the character.
2011
 
2012
  #### `istreambuf_iterator` constructors <a id="istreambuf.iterator.cons">[[istreambuf.iterator.cons]]</a>
2013
 
2014
+ For each `istreambuf_iterator` constructor in this section, an
2015
+ end-of-stream iterator is constructed if and only if the exposition-only
2016
+ member `sbuf_` is initialized with a null pointer value.
2017
+
2018
  ``` cpp
2019
  constexpr istreambuf_iterator() noexcept;
2020
  ```
2021
 
2022
+ *Effects:* Initializes `sbuf_` with `nullptr`.
2023
 
2024
  ``` cpp
2025
+ istreambuf_iterator(istream_type& s) noexcept;
 
2026
  ```
2027
 
2028
+ *Effects:* Initializes `sbuf_` with `s.rdbuf()`.
2029
+
2030
+ ``` cpp
2031
+ istreambuf_iterator(streambuf_type* s) noexcept;
2032
+ ```
2033
+
2034
+ *Effects:* Initializes `sbuf_` with `s`.
2035
 
2036
  ``` cpp
2037
  istreambuf_iterator(const proxy& p) noexcept;
2038
  ```
2039
 
2040
+ *Effects:* Initializes `sbuf_` with `p.sbuf_`.
 
 
2041
 
2042
+ #### `istreambuf_iterator` operations <a id="istreambuf.iterator.ops">[[istreambuf.iterator.ops]]</a>
2043
 
2044
  ``` cpp
2045
  charT operator*() const
2046
  ```
2047
 
2048
  *Returns:* The character obtained via the `streambuf` member
2049
  `sbuf_->sgetc()`.
2050
 
 
 
2051
  ``` cpp
2052
+ istreambuf_iterator& operator++();
 
2053
  ```
2054
 
2055
+ *Effects:* As if by `sbuf_->sbumpc()`.
2056
 
2057
  *Returns:* `*this`.
2058
 
2059
  ``` cpp
2060
+ proxy operator++(int);
2061
  ```
2062
 
2063
  *Returns:* `proxy(sbuf_->sbumpc(), sbuf_)`.
2064
 
 
 
2065
  ``` cpp
2066
+ bool equal(const istreambuf_iterator& b) const;
2067
  ```
2068
 
2069
  *Returns:* `true` if and only if both iterators are at end-of-stream, or
2070
  neither is at end-of-stream, regardless of what `streambuf` object they
2071
  use.
2072
 
 
 
2073
  ``` cpp
2074
  template <class charT, class traits>
2075
  bool operator==(const istreambuf_iterator<charT,traits>& a,
2076
  const istreambuf_iterator<charT,traits>& b);
2077
  ```
2078
 
2079
  *Returns:* `a.equal(b)`.
2080
 
 
 
2081
  ``` cpp
2082
  template <class charT, class traits>
2083
  bool operator!=(const istreambuf_iterator<charT,traits>& a,
2084
  const istreambuf_iterator<charT,traits>& b);
2085
  ```
 
2089
  ### Class template `ostreambuf_iterator` <a id="ostreambuf.iterator">[[ostreambuf.iterator]]</a>
2090
 
2091
  ``` cpp
2092
  namespace std {
2093
  template <class charT, class traits = char_traits<charT>>
2094
+ class ostreambuf_iterator {
 
2095
  public:
2096
+ using iterator_category = output_iterator_tag;
2097
+ using value_type = void;
2098
+ using difference_type = void;
2099
+ using pointer = void;
2100
+ using reference = void;
2101
+ using char_type = charT;
2102
+ using traits_type = traits;
2103
+ using streambuf_type = basic_streambuf<charT,traits>;
2104
+ using ostream_type = basic_ostream<charT,traits>;
2105
 
 
2106
  ostreambuf_iterator(ostream_type& s) noexcept;
2107
  ostreambuf_iterator(streambuf_type* s) noexcept;
2108
  ostreambuf_iterator& operator=(charT c);
2109
 
2110
  ostreambuf_iterator& operator*();
 
2141
  *Effects:* Initializes `sbuf_` with `s`.
2142
 
2143
  #### `ostreambuf_iterator` operations <a id="ostreambuf.iter.ops">[[ostreambuf.iter.ops]]</a>
2144
 
2145
  ``` cpp
2146
+ ostreambuf_iterator& operator=(charT c);
 
2147
  ```
2148
 
2149
  *Effects:* If `failed()` yields `false`, calls `sbuf_->sputc(c)`;
2150
  otherwise has no effect.
2151
 
2152
  *Returns:* `*this`.
2153
 
2154
  ``` cpp
2155
+ ostreambuf_iterator& operator*();
2156
  ```
2157
 
2158
  *Returns:* `*this`.
2159
 
2160
  ``` cpp
2161
+ ostreambuf_iterator& operator++();
2162
+ ostreambuf_iterator& operator++(int);
2163
  ```
2164
 
2165
  *Returns:* `*this`.
2166
 
2167
  ``` cpp
 
2169
  ```
2170
 
2171
  *Returns:* `true` if in any prior use of member `operator=`, the call to
2172
  `sbuf_->sputc()` returned `traits::eof()`; or `false` otherwise.
2173
 
2174
+ ## Range access <a id="iterator.range">[[iterator.range]]</a>
2175
 
2176
  In addition to being available via inclusion of the `<iterator>` header,
2177
  the function templates in [[iterator.range]] are available when any of
2178
  the following headers are included: `<array>`, `<deque>`,
2179
  `<forward_list>`, `<list>`, `<map>`, `<regex>`, `<set>`, `<string>`,
2180
+ `<string_view>`, `<unordered_map>`, `<unordered_set>`, and `<vector>`.
2181
 
2182
  ``` cpp
2183
+ template <class C> constexpr auto begin(C& c) -> decltype(c.begin());
2184
+ template <class C> constexpr auto begin(const C& c) -> decltype(c.begin());
2185
  ```
2186
 
2187
  *Returns:* `c.begin()`.
2188
 
2189
  ``` cpp
2190
+ template <class C> constexpr auto end(C& c) -> decltype(c.end());
2191
+ template <class C> constexpr auto end(const C& c) -> decltype(c.end());
2192
  ```
2193
 
2194
  *Returns:* `c.end()`.
2195
 
2196
  ``` cpp
 
2218
  ```
2219
 
2220
  *Returns:* `std::end(c)`.
2221
 
2222
  ``` cpp
2223
+ template <class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
2224
+ template <class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());
2225
  ```
2226
 
2227
  *Returns:* `c.rbegin()`.
2228
 
2229
  ``` cpp
2230
+ template <class C> constexpr auto rend(C& c) -> decltype(c.rend());
2231
+ template <class C> constexpr auto rend(const C& c) -> decltype(c.rend());
2232
  ```
2233
 
2234
  *Returns:* `c.rend()`.
2235
 
2236
  ``` cpp
2237
+ template <class T, size_t N> constexpr reverse_iterator<T*> rbegin(T (&array)[N]);
2238
  ```
2239
 
2240
  *Returns:* `reverse_iterator<T*>(array + N)`.
2241
 
2242
  ``` cpp
2243
+ template <class T, size_t N> constexpr reverse_iterator<T*> rend(T (&array)[N]);
2244
  ```
2245
 
2246
  *Returns:* `reverse_iterator<T*>(array)`.
2247
 
2248
  ``` cpp
2249
+ template <class E> constexpr reverse_iterator<const E*> rbegin(initializer_list<E> il);
2250
  ```
2251
 
2252
  *Returns:* `reverse_iterator<const E*>(il.end())`.
2253
 
2254
  ``` cpp
2255
+ template <class E> constexpr reverse_iterator<const E*> rend(initializer_list<E> il);
2256
  ```
2257
 
2258
  *Returns:* `reverse_iterator<const E*>(il.begin())`.
2259
 
2260
  ``` cpp
2261
+ template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c));
2262
  ```
2263
 
2264
  *Returns:* `std::rbegin(c)`.
2265
 
2266
  ``` cpp
2267
+ template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c));
2268
  ```
2269
 
2270
  *Returns:* `std::rend(c)`.
2271
 
2272
+ ## Container access <a id="iterator.container">[[iterator.container]]</a>
2273
+
2274
+ In addition to being available via inclusion of the `<iterator>` header,
2275
+ the function templates in [[iterator.container]] are available when any
2276
+ of the following headers are included: `<array>`, `<deque>`,
2277
+ `<forward_list>`, `<list>`, `<map>`, `<regex>`, `<set>`, `<string>`,
2278
+ `<unordered_map>`, `<unordered_set>`, and `<vector>`.
2279
+
2280
+ ``` cpp
2281
+ template <class C> constexpr auto size(const C& c) -> decltype(c.size());
2282
+ ```
2283
+
2284
+ *Returns:* `c.size()`.
2285
+
2286
+ ``` cpp
2287
+ template <class T, size_t N> constexpr size_t size(const T (&array)[N]) noexcept;
2288
+ ```
2289
+
2290
+ *Returns:* `N`.
2291
+
2292
+ ``` cpp
2293
+ template <class C> constexpr auto empty(const C& c) -> decltype(c.empty());
2294
+ ```
2295
+
2296
+ *Returns:* `c.empty()`.
2297
+
2298
+ ``` cpp
2299
+ template <class T, size_t N> constexpr bool empty(const T (&array)[N]) noexcept;
2300
+ ```
2301
+
2302
+ *Returns:* `false`.
2303
+
2304
+ ``` cpp
2305
+ template <class E> constexpr bool empty(initializer_list<E> il) noexcept;
2306
+ ```
2307
+
2308
+ *Returns:* `il.size() == 0`.
2309
+
2310
+ ``` cpp
2311
+ template <class C> constexpr auto data(C& c) -> decltype(c.data());
2312
+ template <class C> constexpr auto data(const C& c) -> decltype(c.data());
2313
+ ```
2314
+
2315
+ *Returns:* `c.data()`.
2316
+
2317
+ ``` cpp
2318
+ template <class T, size_t N> constexpr T* data(T (&array)[N]) noexcept;
2319
+ ```
2320
+
2321
+ *Returns:* `array`.
2322
+
2323
+ ``` cpp
2324
+ template <class E> constexpr const E* data(initializer_list<E> il) noexcept;
2325
+ ```
2326
+
2327
+ *Returns:* `il.begin()`.
2328
+
2329
  <!-- Link reference definitions -->
2330
  [back.insert.iter.cons]: #back.insert.iter.cons
2331
  [back.insert.iter.op*]: #back.insert.iter.op*
2332
  [back.insert.iter.op++]: #back.insert.iter.op++
2333
  [back.insert.iter.op=]: #back.insert.iter.op=
2334
  [back.insert.iter.ops]: #back.insert.iter.ops
2335
  [back.insert.iterator]: #back.insert.iterator
2336
  [back.inserter]: #back.inserter
2337
  [bidirectional.iterators]: #bidirectional.iterators
2338
  [containers]: containers.md#containers
 
 
2339
  [forward.iterators]: #forward.iterators
2340
  [front.insert.iter.cons]: #front.insert.iter.cons
2341
  [front.insert.iter.op*]: #front.insert.iter.op*
2342
  [front.insert.iter.op++]: #front.insert.iter.op++
2343
  [front.insert.iter.op=]: #front.insert.iter.op=
 
2357
  [istream.iterator]: #istream.iterator
2358
  [istream.iterator.cons]: #istream.iterator.cons
2359
  [istream.iterator.ops]: #istream.iterator.ops
2360
  [istreambuf.iterator]: #istreambuf.iterator
2361
  [istreambuf.iterator.cons]: #istreambuf.iterator.cons
2362
+ [istreambuf.iterator.ops]: #istreambuf.iterator.ops
2363
+ [istreambuf.iterator.proxy]: #istreambuf.iterator.proxy
2364
+ [iterator.container]: #iterator.container
 
 
 
 
2365
  [iterator.iterators]: #iterator.iterators
2366
  [iterator.operations]: #iterator.operations
2367
  [iterator.primitives]: #iterator.primitives
2368
  [iterator.range]: #iterator.range
2369
  [iterator.requirements]: #iterator.requirements
 
2425
  [reverse.iterators]: #reverse.iterators
2426
  [std.iterator.tags]: #std.iterator.tags
2427
  [stream.buffers]: input.md#stream.buffers
2428
  [stream.iterators]: #stream.iterators
2429
  [swappable.requirements]: library.md#swappable.requirements
2430
+ [tab:copyassignable]: #tab:copyassignable
2431
+ [tab:equalitycomparable]: #tab:equalitycomparable
2432
  [tab:iterator.bidirectional.requirements]: #tab:iterator.bidirectional.requirements
2433
  [tab:iterator.forward.requirements]: #tab:iterator.forward.requirements
2434
  [tab:iterator.input.requirements]: #tab:iterator.input.requirements
2435
  [tab:iterator.output.requirements]: #tab:iterator.output.requirements
2436
  [tab:iterator.random.access.requirements]: #tab:iterator.random.access.requirements
2437
  [tab:iterator.requirements]: #tab:iterator.requirements
2438
  [tab:iterators.lib.summary]: #tab:iterators.lib.summary
2439
  [tab:iterators.relations]: #tab:iterators.relations
2440
+ [temp.deduct]: temp.md#temp.deduct
2441
  [temp.inst]: temp.md#temp.inst
2442
  [utility.arg.requirements]: library.md#utility.arg.requirements
2443
 
2444
  [^1]: This definition applies to pointers, since pointers are iterators.
2445
  The effect of dereferencing an iterator that has been invalidated is