From Jason Turner

[algorithms]

Large diff (117.5 KB) - rendering may be slow on some devices

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpdrs0e8n1/{from.md → to.md} +899 -329
tmp/tmpdrs0e8n1/{from.md → to.md} RENAMED
@@ -14,11 +14,12 @@ operations, and algorithms from the ISO C library, as summarized in
14
 
15
  | Subclause | | Header |
16
  | ---------------------------- | --------------------------------- | ------------- |
17
  | [[algorithms.requirements]] | Algorithms requirements | |
18
  | [[algorithms.parallel]] | Parallel algorithms | |
19
- | [[alg.nonmodifying]] | Non-modifying sequence operations | `<algorithm>` |
 
20
  | [[alg.modifying.operations]] | Mutating sequence operations | |
21
  | [[alg.sorting]] | Sorting and related operations | |
22
  | [[numeric.ops]] | Generalized numeric operations | `<numeric>` |
23
  | [[specialized.algorithms]] | Specialized `<memory>` algorithms | `<memory>` |
24
  | [[alg.c.library]] | C library algorithms | `<cstdlib>` |
@@ -63,94 +64,98 @@ the specification requires such modification.
63
 
64
  Throughout this Clause, where the template parameters are not
65
  constrained, the names of template parameters are used to express type
66
  requirements.
67
 
 
 
 
 
68
  - If an algorithm’s template parameter is named `InputIterator`,
69
  `InputIterator1`, or `InputIterator2`, the template argument shall
70
  meet the *Cpp17InputIterator* requirements [[input.iterators]].
71
  - If an algorithm’s template parameter is named `OutputIterator`,
72
  `OutputIterator1`, or `OutputIterator2`, the template argument shall
73
  meet the *Cpp17OutputIterator* requirements [[output.iterators]].
74
  - If an algorithm’s template parameter is named `ForwardIterator`,
75
- `ForwardIterator1`, or `ForwardIterator2`, the template argument shall
76
- meet the *Cpp17ForwardIterator* requirements [[forward.iterators]].
 
 
 
77
  - If an algorithm’s template parameter is named
78
- `NoThrowForwardIterator`, the template argument shall meet the
79
- *Cpp17ForwardIterator* requirements [[forward.iterators]], and is
80
- required to have the property that no exceptions are thrown from
81
- increment, assignment, or comparison of, or indirection through, valid
82
- iterators.
83
  - If an algorithm’s template parameter is named `BidirectionalIterator`,
84
  `BidirectionalIterator1`, or `BidirectionalIterator2`, the template
85
  argument shall meet the *Cpp17BidirectionalIterator* requirements
86
- [[bidirectional.iterators]].
 
 
87
  - If an algorithm’s template parameter is named `RandomAccessIterator`,
88
  `RandomAccessIterator1`, or `RandomAccessIterator2`, the template
89
  argument shall meet the *Cpp17RandomAccessIterator* requirements
90
- [[random.access.iterators]].
 
 
91
 
92
- If an algorithm’s *Effects:* element specifies that a value pointed to
93
- by any iterator passed as an argument is modified, then that algorithm
94
- has an additional type requirement: The type of that argument shall meet
95
- the requirements of a mutable iterator [[iterator.requirements]].
96
 
97
- [*Note 1*: This requirement does not affect arguments that are named
98
- `OutputIterator`, `OutputIterator1`, or `OutputIterator2`, because
99
- output iterators must always be mutable, nor does it affect arguments
100
- that are constrained, for which mutability requirements are expressed
101
- explicitly. — *end note*]
102
 
103
- Both in-place and copying versions are provided for certain algorithms.
104
- [^1] When such a version is provided for *algorithm* it is called
105
  *algorithm`_copy`*. Algorithms that take predicates end with the suffix
106
  `_if` (which follows the suffix `_copy`).
107
 
108
  When not otherwise constrained, the `Predicate` parameter is used
109
  whenever an algorithm expects a function object [[function.objects]]
110
  that, when applied to the result of dereferencing the corresponding
111
- iterator, returns a value testable as `true`. In other words, if an
112
- algorithm takes `Predicate pred` as its argument and `first` as its
113
- iterator argument with value type `T`, it should work correctly in the
114
- construct `pred(*first)` contextually converted to `bool` [[conv]]. The
115
- function object `pred` shall not apply any non-constant function through
116
- the dereferenced iterator. Given a glvalue `u` of type (possibly
117
- `const`) `T` that designates the same object as `*first`, `pred(u)`
118
- shall be a valid expression that is equal to `pred(*first)`.
119
 
120
  When not otherwise constrained, the `BinaryPredicate` parameter is used
121
- whenever an algorithm expects a function object that when applied to the
122
- result of dereferencing two corresponding iterators or to dereferencing
123
- an iterator and type `T` when `T` is part of the signature returns a
124
- value testable as `true`. In other words, if an algorithm takes
125
  `BinaryPredicate binary_pred` as its argument and `first1` and `first2`
126
- as its iterator arguments with respective value types `T1` and `T2`, it
127
- should work correctly in the construct `binary_pred(*first1, *first2)`
128
- contextually converted to `bool` [[conv]]. Unless otherwise specified,
129
- `BinaryPredicate` always takes the first iterator’s `value_type` as its
130
- first argument, that is, in those cases when `T value` is part of the
131
- signature, it should work correctly in the construct
132
- `binary_pred(*first1, value)` contextually converted to `bool` [[conv]].
133
- `binary_pred` shall not apply any non-constant function through the
134
- dereferenced iterators. Given a glvalue `u` of type (possibly `const`)
135
- `T1` that designates the same object as `*first1`, and a glvalue `v` of
136
- type (possibly `const`) `T2` that designates the same object as
137
- `*first2`, `binary_pred(u, *first2)`, `binary_pred(*first1, v)`, and
 
138
  `binary_pred(u, v)` shall each be a valid expression that is equal to
139
  `binary_pred(*first1, *first2)`, and `binary_pred(u, value)` shall be a
140
  valid expression that is equal to `binary_pred(*first1, value)`.
141
 
142
  The parameters `UnaryOperation`, `BinaryOperation`, `BinaryOperation1`,
143
  and `BinaryOperation2` are used whenever an algorithm expects a function
144
  object [[function.objects]].
145
 
146
  [*Note 2*: Unless otherwise specified, algorithms that take function
147
- objects as arguments are permitted to copy those function objects
148
- freely. Programmers for whom object identity is important should
149
- consider using a wrapper class that points to a noncopied implementation
150
- object such as `reference_wrapper<T>` [[refwrap]], or some equivalent
151
- solution. — *end note*]
152
 
153
  When the description of an algorithm gives an expression such as
154
  `*first == value` for a condition, the expression shall evaluate to
155
  either `true` or `false` in boolean contexts.
156
 
@@ -182,25 +187,31 @@ and if \[`b`, `a`) denotes a range, the same as those of
182
  iter_difference_t<decltype(b)> n = 0;
183
  for (auto tmp = b; tmp != a; ++tmp) --n;
184
  return n;
185
  ```
186
 
 
 
 
 
 
187
  In the description of algorithm return values, a sentinel value `s`
188
  denoting the end of a range \[`i`, `s`) is sometimes returned where an
189
  iterator is expected. In these cases, the semantics are as if the
190
  sentinel is converted into an iterator using `ranges::next(i, s)`.
191
 
192
  Overloads of algorithms that take `range` arguments [[range.range]]
193
  behave as if they are implemented by calling `ranges::begin` and
194
  `ranges::end` on the `range`(s) and dispatching to the overload in
195
  namespace `ranges` that takes separate iterator and sentinel arguments.
196
 
197
- The number and order of deducible template parameters for algorithm
198
- declarations are unspecified, except where explicitly stated otherwise.
 
199
 
200
- [*Note 3*: Consequently, the algorithms may not be called with
201
- explicitly-specified template argument lists. — *end note*]
202
 
203
  ## Parallel algorithms <a id="algorithms.parallel">[[algorithms.parallel]]</a>
204
 
205
  ### Preamble <a id="algorithms.parallel.defns">[[algorithms.parallel.defns]]</a>
206
 
@@ -273,13 +284,13 @@ different threads of execution.
273
 
274
  Unless otherwise specified, function objects passed into parallel
275
  algorithms as objects of type `Predicate`, `BinaryPredicate`, `Compare`,
276
  `UnaryOperation`, `BinaryOperation`, `BinaryOperation1`,
277
  `BinaryOperation2`, and the operators used by the analogous overloads to
278
- these parallel algorithms that could be formed by the invocation with
279
- the specified default predicate or operation (where applicable) shall
280
- not directly or indirectly modify objects via their arguments, nor shall
281
  they rely on the identity of the provided objects.
282
 
283
  ### Effect of execution policies on algorithm execution <a id="algorithms.parallel.exec">[[algorithms.parallel.exec]]</a>
284
 
285
  Parallel algorithms have template parameters named `ExecutionPolicy`
@@ -299,16 +310,16 @@ argument is modified. — *end note*]
299
  Unless otherwise stated, implementations may make arbitrary copies of
300
  elements (with type `T`) from sequences where
301
  `is_trivially_copy_constructible_v<T>` and
302
  `is_trivially_destructible_v<T>` are `true`.
303
 
304
- [*Note 2*: This implies that user-supplied function objects should not
305
- rely on object identity of arguments for such input sequences. Users for
306
- whom the object identity of the arguments to these function objects is
307
- important should consider using a wrapping iterator that returns a
308
- non-copied implementation object such as `reference_wrapper<T>`
309
- [[refwrap]] or some equivalent solution. — *end note*]
310
 
311
  The invocations of element access functions in parallel algorithms
312
  invoked with an execution policy object of type
313
  `execution::sequenced_policy` all occur in the calling thread of
314
  execution.
@@ -320,18 +331,18 @@ The invocations of element access functions in parallel algorithms
320
  invoked with an execution policy object of type
321
  `execution::unsequenced_policy` are permitted to execute in an unordered
322
  fashion in the calling thread of execution, unsequenced with respect to
323
  one another in the calling thread of execution.
324
 
325
- [*Note 4*: This means that multiple function object invocations may be
326
  interleaved on a single thread of execution, which overrides the usual
327
  guarantee from [[intro.execution]] that function executions do not
328
  overlap with one another. — *end note*]
329
 
330
  The behavior of a program is undefined if it invokes a
331
  vectorization-unsafe standard library function from user code called
332
- from a `execution::unsequenced_policy` algorithm.
333
 
334
  [*Note 5*: Because `execution::unsequenced_policy` allows the execution
335
  of element access functions to be interleaved on a single thread of
336
  execution, blocking synchronization, including the use of mutexes, risks
337
  deadlock. — *end note*]
@@ -410,18 +421,18 @@ unordered fashion in unspecified threads of execution, and unsequenced
410
  with respect to one another within each thread of execution. These
411
  threads of execution are either the invoking thread of execution or
412
  threads of execution implicitly created by the library; the latter will
413
  provide weakly parallel forward progress guarantees.
414
 
415
- [*Note 7*: This means that multiple function object invocations may be
416
  interleaved on a single thread of execution, which overrides the usual
417
  guarantee from [[intro.execution]] that function executions do not
418
  overlap with one another. — *end note*]
419
 
420
  The behavior of a program is undefined if it invokes a
421
  vectorization-unsafe standard library function from user code called
422
- from a `execution::parallel_unsequenced_policy` algorithm.
423
 
424
  [*Note 8*: Because `execution::parallel_unsequenced_policy` allows the
425
  execution of element access functions to be interleaved on a single
426
  thread of execution, blocking synchronization, including the use of
427
  mutexes, risks deadlock. — *end note*]
@@ -489,11 +500,11 @@ Parallel algorithms shall not participate in overload resolution unless
489
  `is_execution_policy_v<remove_cvref_t<ExecutionPolicy>>` is `true`.
490
 
491
  ## Header `<algorithm>` synopsis <a id="algorithm.syn">[[algorithm.syn]]</a>
492
 
493
  ``` cpp
494
- #include <initializer_list>
495
 
496
  namespace std {
497
  namespace ranges {
498
  // [algorithms.results], algorithm result types
499
  template<class I, class F>
@@ -514,10 +525,16 @@ namespace std {
514
  template<class T>
515
  struct min_max_result;
516
 
517
  template<class I>
518
  struct in_found_result;
 
 
 
 
 
 
519
  }
520
 
521
  // [alg.nonmodifying], non-modifying sequence operations
522
  // [alg.all.of], all of
523
  template<class InputIterator, class Predicate>
@@ -565,10 +582,33 @@ namespace std {
565
  template<input_range R, class Proj = identity,
566
  indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
567
  constexpr bool none_of(R&& r, Pred pred, Proj proj = {});
568
  }
569
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
570
  // [alg.foreach], for each
571
  template<class InputIterator, class Function>
572
  constexpr Function for_each(InputIterator first, InputIterator last, Function f);
573
  template<class ExecutionPolicy, class ForwardIterator, class Function>
574
  void for_each(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
@@ -650,10 +690,33 @@ namespace std {
650
  indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
651
  constexpr borrowed_iterator_t<R>
652
  find_if_not(R&& r, Pred pred, Proj proj = {});
653
  }
654
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
655
  // [alg.find.end], find end
656
  template<class ForwardIterator1, class ForwardIterator2>
657
  constexpr ForwardIterator1
658
  find_end(ForwardIterator1 first1, ForwardIterator1 last1,
659
  ForwardIterator2 first2, ForwardIterator2 last2);
@@ -715,19 +778,17 @@ namespace std {
715
 
716
  namespace ranges {
717
  template<input_iterator I1, sentinel_for<I1> S1, forward_iterator I2, sentinel_for<I2> S2,
718
  class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
719
  requires indirectly_comparable<I1, I2, Pred, Proj1, Proj2>
720
- constexpr I1 find_first_of(I1 first1, S1 last1, I2 first2, S2 last2,
721
- Pred pred = {},
722
  Proj1 proj1 = {}, Proj2 proj2 = {});
723
  template<input_range R1, forward_range R2,
724
  class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
725
  requires indirectly_comparable<iterator_t<R1>, iterator_t<R2>, Pred, Proj1, Proj2>
726
  constexpr borrowed_iterator_t<R1>
727
- find_first_of(R1&& r1, R2&& r2,
728
- Pred pred = {},
729
  Proj1 proj1 = {}, Proj2 proj2 = {});
730
  }
731
 
732
  // [alg.adjacent.find], adjacent find
733
  template<class ForwardIterator>
@@ -980,12 +1041,11 @@ namespace std {
980
  search_n(ForwardIterator first, ForwardIterator last,
981
  Size count, const T& value);
982
  template<class ForwardIterator, class Size, class T, class BinaryPredicate>
983
  constexpr ForwardIterator
984
  search_n(ForwardIterator first, ForwardIterator last,
985
- Size count, const T& value,
986
- BinaryPredicate pred);
987
  template<class ExecutionPolicy, class ForwardIterator, class Size, class T>
988
  ForwardIterator
989
  search_n(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
990
  ForwardIterator first, ForwardIterator last,
991
  Size count, const T& value);
@@ -1014,10 +1074,125 @@ namespace std {
1014
 
1015
  template<class ForwardIterator, class Searcher>
1016
  constexpr ForwardIterator
1017
  search(ForwardIterator first, ForwardIterator last, const Searcher& searcher);
1018
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1019
  // [alg.modifying.operations], mutating sequence operations
1020
  // [alg.copy], copy
1021
  template<class InputIterator, class OutputIterator>
1022
  constexpr OutputIterator copy(InputIterator first, InputIterator last,
1023
  OutputIterator result);
@@ -1661,20 +1836,37 @@ namespace std {
1661
  template<class ExecutionPolicy, class ForwardIterator>
1662
  ForwardIterator
1663
  shift_left(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
1664
  ForwardIterator first, ForwardIterator last,
1665
  typename iterator_traits<ForwardIterator>::difference_type n);
 
 
 
 
 
 
 
 
 
1666
  template<class ForwardIterator>
1667
  constexpr ForwardIterator
1668
  shift_right(ForwardIterator first, ForwardIterator last,
1669
  typename iterator_traits<ForwardIterator>::difference_type n);
1670
  template<class ExecutionPolicy, class ForwardIterator>
1671
  ForwardIterator
1672
  shift_right(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
1673
  ForwardIterator first, ForwardIterator last,
1674
  typename iterator_traits<ForwardIterator>::difference_type n);
1675
 
 
 
 
 
 
 
 
 
1676
  // [alg.sorting], sorting and related operations
1677
  // [alg.sort], sorting
1678
  template<class RandomAccessIterator>
1679
  constexpr void sort(RandomAccessIterator first, RandomAccessIterator last);
1680
  template<class RandomAccessIterator, class Compare>
@@ -1723,26 +1915,22 @@ namespace std {
1723
  borrowed_iterator_t<R>
1724
  stable_sort(R&& r, Comp comp = {}, Proj proj = {});
1725
  }
1726
 
1727
  template<class RandomAccessIterator>
1728
- constexpr void partial_sort(RandomAccessIterator first,
1729
- RandomAccessIterator middle,
1730
  RandomAccessIterator last);
1731
  template<class RandomAccessIterator, class Compare>
1732
- constexpr void partial_sort(RandomAccessIterator first,
1733
- RandomAccessIterator middle,
1734
  RandomAccessIterator last, Compare comp);
1735
  template<class ExecutionPolicy, class RandomAccessIterator>
1736
  void partial_sort(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
1737
- RandomAccessIterator first,
1738
- RandomAccessIterator middle,
1739
  RandomAccessIterator last);
1740
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
1741
  void partial_sort(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
1742
- RandomAccessIterator first,
1743
- RandomAccessIterator middle,
1744
  RandomAccessIterator last, Compare comp);
1745
 
1746
  namespace ranges {
1747
  template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
1748
  class Proj = identity>
@@ -2886,10 +3074,46 @@ namespace std::ranges {
2886
  requires convertible_to<I, I2>
2887
  constexpr operator in_found_result<I2>() && {
2888
  return {std::move(in), found};
2889
  }
2890
  };
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2891
  }
2892
  ```
2893
 
2894
  ## Non-modifying sequence operations <a id="alg.nonmodifying">[[alg.nonmodifying]]</a>
2895
 
@@ -2978,10 +3202,40 @@ Let E be:
2978
  \[`first`, `last`), and `true` otherwise.
2979
 
2980
  *Complexity:* At most `last - first` applications of the predicate and
2981
  any projection.
2982
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2983
  ### For each <a id="alg.foreach">[[alg.foreach]]</a>
2984
 
2985
  ``` cpp
2986
  template<class InputIterator, class Function>
2987
  constexpr Function for_each(InputIterator first, InputIterator last, Function f);
@@ -2996,11 +3250,11 @@ requirements ([[cpp17.moveconstructible]]).
2996
  *Effects:* Applies `f` to the result of dereferencing every iterator in
2997
  the range \[`first`, `last`), starting from `first` and proceeding to
2998
  `last - 1`.
2999
 
3000
  [*Note 2*: If the type of `first` meets the requirements of a mutable
3001
- iterator, `f` may apply non-constant functions through the dereferenced
3002
  iterator. — *end note*]
3003
 
3004
  *Returns:* `f`.
3005
 
3006
  *Complexity:* Applies `f` exactly `last - first` times.
@@ -3019,22 +3273,22 @@ requirements.
3019
 
3020
  *Effects:* Applies `f` to the result of dereferencing every iterator in
3021
  the range \[`first`, `last`).
3022
 
3023
  [*Note 3*: If the type of `first` meets the requirements of a mutable
3024
- iterator, `f` may apply non-constant functions through the dereferenced
3025
  iterator. — *end note*]
3026
 
3027
  *Complexity:* Applies `f` exactly `last - first` times.
3028
 
3029
  *Remarks:* If `f` returns a result, the result is ignored.
3030
  Implementations do not have the freedom granted under
3031
  [[algorithms.parallel.exec]] to make arbitrary copies of elements from
3032
  the input sequence.
3033
 
3034
  [*Note 4*: Does not return a copy of its `Function` parameter, since
3035
- parallelization may not permit efficient state
3036
  accumulation. — *end note*]
3037
 
3038
  ``` cpp
3039
  template<input_iterator I, sentinel_for<I> S, class Proj = identity,
3040
  indirectly_unary_invocable<projected<I, Proj>> Fun>
@@ -3049,11 +3303,11 @@ template<input_range R, class Proj = identity,
3049
  *Effects:* Calls `invoke(f, invoke(proj, *i))` for every iterator `i` in
3050
  the range \[`first`, `last`), starting from `first` and proceeding to
3051
  `last - 1`.
3052
 
3053
  [*Note 5*: If the result of `invoke(proj, *i)` is a mutable reference,
3054
- `f` may apply non-constant functions. — *end note*]
3055
 
3056
  *Returns:* `{last, std::move(f)}`.
3057
 
3058
  *Complexity:* Applies `f` and `proj` exactly `last - first` times.
3059
 
@@ -3066,25 +3320,23 @@ the range \[`first`, `last`), starting from `first` and proceeding to
3066
  template<class InputIterator, class Size, class Function>
3067
  constexpr InputIterator for_each_n(InputIterator first, Size n, Function f);
3068
  ```
3069
 
3070
  *Mandates:* The type `Size` is convertible to an integral
3071
- type ([[conv.integral]], [[class.conv]]).
3072
 
3073
- *Preconditions:* `Function` meets the *Cpp17MoveConstructible*
3074
- requirements.
3075
 
3076
  [*Note 7*: `Function` need not meet the requirements of
3077
  *Cpp17CopyConstructible*. — *end note*]
3078
 
3079
- *Preconditions:* `n >= 0` is `true`.
3080
-
3081
  *Effects:* Applies `f` to the result of dereferencing every iterator in
3082
  the range \[`first`, `first + n`) in order.
3083
 
3084
  [*Note 8*: If the type of `first` meets the requirements of a mutable
3085
- iterator, `f` may apply non-constant functions through the dereferenced
3086
  iterator. — *end note*]
3087
 
3088
  *Returns:* `first + n`.
3089
 
3090
  *Remarks:* If `f` returns a result, the result is ignored.
@@ -3094,22 +3346,20 @@ template<class ExecutionPolicy, class ForwardIterator, class Size, class Functio
3094
  ForwardIterator for_each_n(ExecutionPolicy&& exec, ForwardIterator first, Size n,
3095
  Function f);
3096
  ```
3097
 
3098
  *Mandates:* The type `Size` is convertible to an integral
3099
- type ([[conv.integral]], [[class.conv]]).
3100
 
3101
- *Preconditions:* `Function` meets the *Cpp17CopyConstructible*
3102
- requirements.
3103
-
3104
- *Preconditions:* `n >= 0` is `true`.
3105
 
3106
  *Effects:* Applies `f` to the result of dereferencing every iterator in
3107
  the range \[`first`, `first + n`).
3108
 
3109
  [*Note 9*: If the type of `first` meets the requirements of a mutable
3110
- iterator, `f` may apply non-constant functions through the dereferenced
3111
  iterator. — *end note*]
3112
 
3113
  *Returns:* `first + n`.
3114
 
3115
  *Remarks:* If `f` returns a result, the result is ignored.
@@ -3128,11 +3378,11 @@ template<input_iterator I, class Proj = identity,
3128
 
3129
  *Effects:* Calls `invoke(f, invoke(proj, *i))` for every iterator `i` in
3130
  the range \[`first`, `first + n`) in order.
3131
 
3132
  [*Note 10*: If the result of `invoke(proj, *i)` is a mutable reference,
3133
- `f` may apply non-constant functions. — *end note*]
3134
 
3135
  *Returns:* `{first + n, std::move(f)}`.
3136
 
3137
  *Remarks:* If `f` returns a result, the result is ignored.
3138
 
@@ -3200,10 +3450,47 @@ Let E be:
3200
  which E is `true`. Returns `last` if no such iterator is found.
3201
 
3202
  *Complexity:* At most `last - first` applications of the corresponding
3203
  predicate and any projection.
3204
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3205
  ### Find end <a id="alg.find.end">[[alg.find.end]]</a>
3206
 
3207
  ``` cpp
3208
  template<class ForwardIterator1, class ForwardIterator2>
3209
  constexpr ForwardIterator1
@@ -3580,22 +3867,28 @@ Let:
3580
  - `invoke(pred, invoke(proj1, *i), invoke(proj2, *(first2 + (i - first1))))`
3581
  for the overloads with parameter `proj1`.
3582
 
3583
  *Returns:* If `last1 - first1 != last2 - first2`, return `false`.
3584
  Otherwise return `true` if E holds for every iterator `i` in the range
3585
- \[`first1`, `last1`) Otherwise, returns `false`.
3586
 
3587
- *Complexity:* If the types of `first1`, `last1`, `first2`, and `last2`:
3588
 
3589
- - meet the *Cpp17RandomAccessIterator*
3590
- requirements [[random.access.iterators]] for the overloads in
3591
- namespace `std`;
3592
- - pairwise model `sized_sentinel_for` [[iterator.concept.sizedsentinel]]
3593
- for the overloads in namespace `ranges`,
 
 
 
 
 
 
3594
 
3595
- and `last1 - first1 != last2 - first2`, then no applications of the
3596
- corresponding predicate and each projection; otherwise,
3597
 
3598
  - For the overloads with no `ExecutionPolicy`, at most
3599
  min(`last1 - first1`, `last2 - first2`) applications of the
3600
  corresponding predicate and any projections.
3601
  - For the overloads with an `ExecutionPolicy`, 𝑂(min(`last1 - first1`,
@@ -3619,34 +3912,32 @@ template<class ForwardIterator1, class ForwardIterator2,
3619
  constexpr bool is_permutation(ForwardIterator1 first1, ForwardIterator1 last1,
3620
  ForwardIterator2 first2, ForwardIterator2 last2,
3621
  BinaryPredicate pred);
3622
  ```
3623
 
 
 
 
 
3624
  *Mandates:* `ForwardIterator1` and `ForwardIterator2` have the same
3625
  value type.
3626
 
3627
  *Preconditions:* The comparison function is an equivalence relation.
3628
 
3629
- *Remarks:* If `last2` was not given in the argument list, it denotes
3630
- `first2 + (last1 - first1)` below.
3631
-
3632
  *Returns:* If `last1 - first1 != last2 - first2`, return `false`.
3633
  Otherwise return `true` if there exists a permutation of the elements in
3634
- the range \[`first2`, `first2 + (last1 - first1)`), beginning with
3635
- `ForwardIterator2 begin`, such that `equal(first1, last1, begin)`
3636
- returns `true` or `equal(first1, last1, begin, pred)` returns `true`;
3637
- otherwise, returns `false`.
3638
 
3639
  *Complexity:* No applications of the corresponding predicate if
3640
  `ForwardIterator1` and `ForwardIterator2` meet the requirements of
3641
  random access iterators and `last1 - first1 != last2 - first2`.
3642
  Otherwise, exactly `last1 - first1` applications of the corresponding
3643
- predicate if `equal(first1, last1, first2, last2)` would return `true`
3644
- if `pred` was not given in the argument list or
3645
- `equal(first1, last1, first2, last2, pred)` would return `true` if
3646
- `pred` was given in the argument list; otherwise, at worst 𝑂(N^2), where
3647
- N has the value `last1 - first1`.
3648
 
3649
  ``` cpp
3650
  template<forward_iterator I1, sentinel_for<I1> S1, forward_iterator I2,
3651
  sentinel_for<I2> S2, class Proj1 = identity, class Proj2 = identity,
3652
  indirect_equivalence_relation<projected<I1, Proj1>,
@@ -3669,13 +3960,16 @@ that `ranges::equal(first1, last1, pfirst, plast, pred, proj1, proj2)`
3669
  returns `true`; otherwise, returns `false`.
3670
 
3671
  *Complexity:* No applications of the corresponding predicate and
3672
  projections if:
3673
 
 
3674
  - `S1` and `I1` model `sized_sentinel_for<S1, I1>`,
3675
  - `S2` and `I2` model `sized_sentinel_for<S2, I2>`, and
3676
- - `last1 - first1 != last2 - first2`.
 
 
3677
 
3678
  Otherwise, exactly `last1 - first1` applications of the corresponding
3679
  predicate and projections if
3680
  `ranges::equal(first1, last1, first2, last2, pred, proj1, proj2)` would
3681
  return `true`; otherwise, at worst 𝑂(N^2), where N has the value
@@ -3775,17 +4069,17 @@ template<class ExecutionPolicy, class ForwardIterator, class Size, class T,
3775
  Size count, const T& value,
3776
  BinaryPredicate pred);
3777
  ```
3778
 
3779
  *Mandates:* The type `Size` is convertible to an integral
3780
- type ([[conv.integral]], [[class.conv]]).
3781
 
3782
  *Returns:* The first iterator `i` in the range \[`first`, `last-count`)
3783
  such that for every non-negative integer `n` less than `count` the
3784
  following corresponding conditions hold:
3785
- `*(i + n) == value, pred(*(i + n),value) != false`. Returns `last` if no
3786
- such iterator is found.
3787
 
3788
  *Complexity:* At most `last - first` applications of the corresponding
3789
  predicate.
3790
 
3791
  ``` cpp
@@ -3821,10 +4115,207 @@ template<class ForwardIterator, class Searcher>
3821
  *Effects:* Equivalent to: `return searcher(first, last).first;`
3822
 
3823
  *Remarks:* `Searcher` need not meet the *Cpp17CopyConstructible*
3824
  requirements.
3825
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3826
  ## Mutating sequence operations <a id="alg.modifying.operations">[[alg.modifying.operations]]</a>
3827
 
3828
  ### Copy <a id="alg.copy">[[alg.copy]]</a>
3829
 
3830
  ``` cpp
@@ -3890,14 +4381,14 @@ template<input_iterator I, weakly_incrementable O>
3890
  ```
3891
 
3892
  Let N be max(0, `n`).
3893
 
3894
  *Mandates:* The type `Size` is convertible to an integral
3895
- type ([[conv.integral]], [[class.conv]]).
3896
 
3897
  *Effects:* For each non-negative integer i < N, performs
3898
- `*(result + i) = *(first + i)`.
3899
 
3900
  *Returns:*
3901
 
3902
  - `result + `N for the overloads in namespace `std`.
3903
  - `{first + `N`, result + `N`}` for the overload in namespace `ranges`.
@@ -3936,11 +4427,11 @@ and N be the number of iterators `i` in the range \[`first`, `last`) for
3936
  which the condition E holds.
3937
 
3938
  *Preconditions:* The ranges \[`first`, `last`) and \[`result`,
3939
  `result + (last - first)`) do not overlap.
3940
 
3941
- [*Note 1*: For the overload with an `ExecutionPolicy`, there may be a
3942
  performance cost if `iterator_traits<ForwardIterator1>::value_type` is
3943
  not *Cpp17MoveConstructible*
3944
  ([[cpp17.moveconstructible]]). — *end note*]
3945
 
3946
  *Effects:* Copies all of the elements referred to by the iterator `i` in
@@ -3977,11 +4468,13 @@ Let N be `last - first`.
3977
 
3978
  *Preconditions:* `result` is not in the range (`first`, `last`).
3979
 
3980
  *Effects:* Copies elements in the range \[`first`, `last`) into the
3981
  range \[`result - `N, `result`) starting from `last - 1` and proceeding
3982
- to `first`. [^2] For each positive integer n ≤ N, performs
 
 
3983
  `*(result - `n`) = *(last - `n`)`.
3984
 
3985
  *Returns:*
3986
 
3987
  - `result - `N for the overload in namespace `std`.
@@ -4074,12 +4567,13 @@ Let N be `last - first`.
4074
 
4075
  *Preconditions:* `result` is not in the range (`first`, `last`).
4076
 
4077
  *Effects:* Moves elements in the range \[`first`, `last`) into the range
4078
  \[`result - `N, `result`) starting from `last - 1` and proceeding to
4079
- `first`. [^3] For each positive integer n ≤ N, performs
4080
- `*(result - `n`) = `E.
 
4081
 
4082
  *Returns:*
4083
 
4084
  - `result - `N for the overload in namespace `std`.
4085
  - `{last, result - `N`}` for the overloads in namespace `ranges`.
@@ -4397,11 +4891,10 @@ template<class OutputIterator, class Size, class T>
4397
  constexpr OutputIterator fill_n(OutputIterator first, Size n, const T& value);
4398
  template<class ExecutionPolicy, class ForwardIterator, class Size, class T>
4399
  ForwardIterator fill_n(ExecutionPolicy&& exec,
4400
  ForwardIterator first, Size n, const T& value);
4401
 
4402
-
4403
  template<class T, output_iterator<const T&> O, sentinel_for<O> S>
4404
  constexpr O ranges::fill(O first, S last, const T& value);
4405
  template<class T, output_range<const T&> R>
4406
  constexpr borrowed_iterator_t<R> ranges::fill(R&& r, const T& value);
4407
  template<class T, output_iterator<const T&> O>
@@ -4411,12 +4904,12 @@ template<class T, output_iterator<const T&> O>
4411
  Let N be max(0, `n`) for the `fill_n` algorithms, and `last - first` for
4412
  the `fill` algorithms.
4413
 
4414
  *Mandates:* The expression `value` is
4415
  writable [[iterator.requirements.general]] to the output iterator. The
4416
- type `Size` is convertible to an integral type ([[conv.integral]],
4417
- [[class.conv]]).
4418
 
4419
  *Effects:* Assigns `value` through all the iterators in the range
4420
  \[`first`, `first + `N).
4421
 
4422
  *Returns:* `first + `N.
@@ -4453,11 +4946,11 @@ template<input_or_output_iterator O, copy_constructible F>
4453
 
4454
  Let N be max(0, `n`) for the `generate_n` algorithms, and `last - first`
4455
  for the `generate` algorithms.
4456
 
4457
  *Mandates:* `Size` is convertible to an integral
4458
- type ([[conv.integral]], [[class.conv]]).
4459
 
4460
  *Effects:* Assigns the result of successive evaluations of `gen()`
4461
  through each iterator in the range \[`first`, `first + `N).
4462
 
4463
  *Returns:* `first + `N.
@@ -4518,15 +5011,15 @@ the range \[`first`, `last`) for which E holds.
4518
  *Returns:* Let j be the end of the resulting range. Returns:
4519
 
4520
  - j for the overloads in namespace `std`.
4521
  - `{`j`, last}` for the overloads in namespace `ranges`.
4522
 
4523
- *Remarks:* Stable [[algorithm.stable]].
4524
-
4525
  *Complexity:* Exactly `last - first` applications of the corresponding
4526
  predicate and any projection.
4527
 
 
 
4528
  [*Note 1*: Each element in the range \[`ret`, `last`), where `ret` is
4529
  the returned value, has a valid but unspecified state, because the
4530
  algorithms can eliminate elements by moving from elements that were
4531
  originally in that range. — *end note*]
4532
 
@@ -4590,14 +5083,14 @@ Let N be the number of elements in \[`first`, `last`) for which E is
4590
  `result`.
4591
 
4592
  *Preconditions:* The ranges \[`first`, `last`) and \[`result`,
4593
  `result + (last - first)`) do not overlap.
4594
 
4595
- [*Note 2*: For the overloads with an `ExecutionPolicy`, there may be a
4596
- performance cost if `iterator_traits<ForwardIterator1>::value_type` does
4597
- not meet the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]])
4598
- requirements. — *end note*]
4599
 
4600
  *Effects:* Copies all the elements referred to by the iterator `i` in
4601
  the range \[`first`, `last`) for which E is `false`.
4602
 
4603
  *Returns:*
@@ -4642,11 +5135,11 @@ and let E be
4642
 
4643
  - `bool(pred(*(i - 1), *i))` for the overloads in namespace `std`;
4644
  - `bool(invoke(comp, invoke(proj, *(i - 1)), invoke(proj, *i)))` for the
4645
  overloads in namespace `ranges`.
4646
 
4647
- *Preconditions:* For the overloads in namepace `std`, `pred` is an
4648
  equivalence relation and the type of `*first` meets the
4649
  *Cpp17MoveAssignable* requirements ([[cpp17.moveassignable]]).
4650
 
4651
  *Effects:* For a nonempty range, eliminates all but the first element
4652
  from every consecutive group of equivalent elements referred to by the
@@ -4717,19 +5210,19 @@ parameter `pred`, and let E be
4717
  - The ranges \[`first`, `last`) and \[`result`, `result+(last-first)`)
4718
  do not overlap.
4719
  - For the overloads in namespace `std`:
4720
  - The comparison function is an equivalence relation.
4721
  - For the overloads with no `ExecutionPolicy`, let `T` be the value
4722
- type of `InputIterator`. If `InputIterator` meets the
4723
- *Cpp17ForwardIterator* requirements, then there are no additional
4724
- requirements for `T`. Otherwise, if `OutputIterator` meets the
4725
- *Cpp17ForwardIterator* requirements and its value type is the same
4726
- as `T`, then `T` meets the *Cpp17CopyAssignable*
4727
  ([[cpp17.copyassignable]]) requirements. Otherwise, `T` meets both
4728
  the *Cpp17CopyConstructible* ([[cpp17.copyconstructible]]) and
4729
  *Cpp17CopyAssignable* requirements. \[*Note 1*: For the overloads
4730
- with an `ExecutionPolicy`, there may be a performance cost if the
4731
  value type of `ForwardIterator1` does not meet both the
4732
  *Cpp17CopyConstructible* and *Cpp17CopyAssignable*
4733
  requirements. — *end note*]
4734
 
4735
  *Effects:* Copies only the first element from every consecutive group of
@@ -4901,11 +5394,11 @@ template<forward_range R, weakly_incrementable O>
4901
  ```
4902
 
4903
  *Effects:* Equivalent to:
4904
 
4905
  ``` cpp
4906
- return ranges::rotate_copy(ranges::begin(r), middle, ranges::end(r), result);
4907
  ```
4908
 
4909
  ### Sample <a id="alg.random.sample">[[alg.random.sample]]</a>
4910
 
4911
  ``` cpp
@@ -4938,11 +5431,11 @@ overload in namespace `std`:
4938
  requirements [[input.iterators]].
4939
  - `SampleIterator` meets the *Cpp17OutputIterator*
4940
  requirements [[output.iterators]].
4941
  - `SampleIterator` meets the *Cpp17RandomAccessIterator*
4942
  requirements [[random.access.iterators]] unless `PopulationIterator`
4943
- meets the *Cpp17ForwardIterator* requirements [[forward.iterators]].
4944
  - `remove_reference_t<UniformRandomBitGenerator>` meets the requirements
4945
  of a uniform random bit generator type [[rand.req.urng]].
4946
 
4947
  *Effects:* Copies min(`last - first`, `n`) elements (the *sample*) from
4948
  \[`first`, `last`) (the *population*) to `out` such that each possible
@@ -4956,13 +5449,13 @@ sampling* and *reservoir sampling*. — *end note*]
4956
  *Complexity:* 𝑂(`last - first`).
4957
 
4958
  *Remarks:*
4959
 
4960
  - For the overload in namespace `std`, stable if and only if
4961
- `PopulationIterator` meets the *Cpp17ForwardIterator* requirements.
4962
- For the first overload in namespace `ranges`, stable if and only if
4963
- `I` models `forward_iterator`.
4964
  - To the extent that the implementation of this function makes use of
4965
  random numbers, the object `g` serves as the implementation’s source
4966
  of randomness.
4967
 
4968
  ### Shuffle <a id="alg.random.shuffle">[[alg.random.shuffle]]</a>
@@ -5011,23 +5504,34 @@ template<class ForwardIterator>
5011
  typename iterator_traits<ForwardIterator>::difference_type n);
5012
  template<class ExecutionPolicy, class ForwardIterator>
5013
  ForwardIterator
5014
  shift_left(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last,
5015
  typename iterator_traits<ForwardIterator>::difference_type n);
 
 
 
 
 
 
5016
  ```
5017
 
5018
- *Preconditions:* `n >= 0` is `true`. The type of `*first` meets the
5019
- *Cpp17MoveAssignable* requirements.
 
5020
 
5021
  *Effects:* If `n == 0` or `n >= last - first`, does nothing. Otherwise,
5022
  moves the element from position `first + n + i` into position
5023
- `first + i` for each non-negative integer `i < (last - first) - n`. In
5024
- the first overload case, does so in order starting from `i = 0` and
5025
- proceeding to `i = (last - first) - n - 1`.
 
5026
 
5027
- *Returns:* `first + (last - first - n)` if `n < last - first`, otherwise
5028
- `first`.
 
 
 
5029
 
5030
  *Complexity:* At most `(last - first) - n` assignments.
5031
 
5032
  ``` cpp
5033
  template<class ForwardIterator>
@@ -5036,41 +5540,59 @@ template<class ForwardIterator>
5036
  typename iterator_traits<ForwardIterator>::difference_type n);
5037
  template<class ExecutionPolicy, class ForwardIterator>
5038
  ForwardIterator
5039
  shift_right(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last,
5040
  typename iterator_traits<ForwardIterator>::difference_type n);
 
 
 
 
 
 
5041
  ```
5042
 
5043
- *Preconditions:* `n >= 0` is `true`. The type of `*first` meets the
5044
- *Cpp17MoveAssignable* requirements. `ForwardIterator` meets the
 
5045
  *Cpp17BidirectionalIterator* requirements [[bidirectional.iterators]] or
5046
  the *Cpp17ValueSwappable* requirements.
5047
 
5048
  *Effects:* If `n == 0` or `n >= last - first`, does nothing. Otherwise,
5049
  moves the element from position `first + i` into position
5050
  `first + n + i` for each non-negative integer `i < (last - first) - n`.
5051
- In the first overload case, if `ForwardIterator` meets the
5052
- *Cpp17BidirectionalIterator* requirements, does so in order starting
5053
- from `i = (last - first) - n - 1` and proceeding to `i = 0`.
5054
 
5055
- *Returns:* `first + n` if `n < last - first`, otherwise `last`.
 
 
 
 
 
 
 
 
 
 
5056
 
5057
  *Complexity:* At most `(last - first) - n` assignments or swaps.
5058
 
5059
  ## Sorting and related operations <a id="alg.sorting">[[alg.sorting]]</a>
5060
 
 
 
5061
  The operations in  [[alg.sorting]] defined directly in namespace `std`
5062
  have two versions: one that takes a function object of type `Compare`
5063
  and one that uses an `operator<`.
5064
 
5065
  `Compare` is a function object type [[function.objects]] that meets the
5066
  requirements for a template parameter named `BinaryPredicate` 
5067
  [[algorithms.requirements]]. The return value of the function call
5068
- operation applied to an object of type `Compare`, when contextually
5069
- converted to `bool` [[conv]], yields `true` if the first argument of the
5070
- call is less than the second, and `false` otherwise. `Compare comp` is
5071
- used throughout for algorithms assuming an ordering relation.
5072
 
5073
  For all algorithms that take `Compare`, there is a version that uses
5074
  `operator<` instead. That is, `comp(*i, *j) != false` defaults to
5075
  `*i < *j != false`. For algorithms other than those described in 
5076
  [[alg.binary.search]], `comp` shall induce a strict weak ordering on the
@@ -5106,10 +5628,14 @@ pointing to the sequence and every non-negative integer `n` such that
5106
  bool(invoke(comp, invoke(proj, *(i + n)), invoke(proj, *i)))
5107
  ```
5108
 
5109
  is `false`.
5110
 
 
 
 
 
5111
  A sequence \[`start`, `finish`) is *partitioned with respect to an
5112
  expression* `f(e)` if there exists an integer `n` such that for all
5113
  `0 <= i < (finish - start)`, `f(*(start + i))` is `true` if and only if
5114
  `i < n`.
5115
 
@@ -5341,13 +5867,13 @@ with no parameters by those names.
5341
  `RandomAccessIterator` meets the *Cpp17ValueSwappable*
5342
  requirements [[swappable.requirements]], the type of `*result_first`
5343
  meets the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
5344
  *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
5345
 
5346
- *Preconditions:* For iterators `a1` and `b1` in \[`first`, `last`), and
5347
- iterators `x2` and `y2` in \[`result_first`, `result_last`), after
5348
- evaluating the assignment `*y2 = *b1`, let E be the value of
5349
 
5350
  ``` cpp
5351
  bool(invoke(comp, invoke(proj1, *a1), invoke(proj2, *y2))).
5352
  ```
5353
 
@@ -5525,19 +6051,21 @@ template<random_access_range R, class Comp = ranges::less, class Proj = identity
5525
  return ranges::nth_element(ranges::begin(r), nth, ranges::end(r), comp, proj);
5526
  ```
5527
 
5528
  ### Binary search <a id="alg.binary.search">[[alg.binary.search]]</a>
5529
 
5530
- All of the algorithms in this subclause are versions of binary search
5531
- and assume that the sequence being searched is partitioned with respect
5532
- to an expression formed by binding the search key to an argument of the
5533
- comparison function. They work on non-random access iterators minimizing
5534
- the number of comparisons, which will be logarithmic for all types of
5535
- iterators. They are especially appropriate for random access iterators,
5536
- because these algorithms do a logarithmic number of steps through the
5537
- data structure. For non-random access iterators they execute a linear
5538
- number of steps.
 
 
5539
 
5540
  #### `lower_bound` <a id="lower.bound">[[lower.bound]]</a>
5541
 
5542
  ``` cpp
5543
  template<class ForwardIterator, class T>
@@ -5817,19 +6345,18 @@ range \[`i`, `last`), E(`*j`) is `false`. Returns:
5817
  - `i` for the overloads in namespace `std`.
5818
  - `{i, last}` for the overloads in namespace `ranges`.
5819
 
5820
  *Complexity:* Let N = `last - first`:
5821
 
5822
- - For the overloads with no `ExecutionPolicy`, at most N log N swaps,
5823
  but only 𝑂(N) swaps if there is enough extra memory. Exactly N
5824
  applications of the predicate and projection.
5825
  - For the overload with an `ExecutionPolicy`, 𝑂(N log N) swaps and 𝑂(N)
5826
  applications of the predicate.
5827
 
5828
  ``` cpp
5829
- template<class InputIterator, class OutputIterator1,
5830
- class OutputIterator2, class Predicate>
5831
  constexpr pair<OutputIterator1, OutputIterator2>
5832
  partition_copy(InputIterator first, InputIterator last,
5833
  OutputIterator1 out_true, OutputIterator2 out_false, Predicate pred);
5834
  template<class ExecutionPolicy, class ForwardIterator, class ForwardIterator1,
5835
  class ForwardIterator2, class Predicate>
@@ -5860,11 +6387,11 @@ Let `proj` be `identity{}` for the overloads with no parameter named
5860
  `*first` is writable [[iterator.requirements.general]] to `out_true` and
5861
  `out_false`.
5862
 
5863
  *Preconditions:* The input range and output ranges do not overlap.
5864
 
5865
- [*Note 1*: For the overload with an `ExecutionPolicy`, there may be a
5866
  performance cost if `first`’s value type does not meet the
5867
  *Cpp17CopyConstructible* requirements. — *end note*]
5868
 
5869
  *Effects:* For each iterator `i` in \[`first`, `last`), copies `*i` to
5870
  the output range beginning with `out_true` if E(`*i`) is `true`, or to
@@ -6049,16 +6576,18 @@ template<bidirectional_range R, class Comp = ranges::less, class Proj = identity
6049
  return ranges::inplace_merge(ranges::begin(r), middle, ranges::end(r), comp, proj);
6050
  ```
6051
 
6052
  ### Set operations on sorted structures <a id="alg.set.operations">[[alg.set.operations]]</a>
6053
 
6054
- This subclause defines all the basic set operations on sorted
6055
- structures. They also work with `multiset`s [[multiset]] containing
6056
- multiple copies of equivalent elements. The semantics of the set
6057
- operations are generalized to `multiset`s in a standard way by defining
6058
- `set_union` to contain the maximum number of occurrences of every
6059
- element, `set_intersection` to contain the minimum, and so on.
 
 
6060
 
6061
  #### `includes` <a id="includes">[[includes]]</a>
6062
 
6063
  ``` cpp
6064
  template<class InputIterator1, class InputIterator2>
@@ -6111,12 +6640,11 @@ keeping the remaining elements in the same order. — *end note*]
6111
  comparisons and applications of each projection.
6112
 
6113
  #### `set_union` <a id="set.union">[[set.union]]</a>
6114
 
6115
  ``` cpp
6116
- template<class InputIterator1, class InputIterator2,
6117
- class OutputIterator>
6118
  constexpr OutputIterator
6119
  set_union(InputIterator1 first1, InputIterator1 last1,
6120
  InputIterator2 first2, InputIterator2 last2,
6121
  OutputIterator result);
6122
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
@@ -6125,12 +6653,11 @@ template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
6125
  set_union(ExecutionPolicy&& exec,
6126
  ForwardIterator1 first1, ForwardIterator1 last1,
6127
  ForwardIterator2 first2, ForwardIterator2 last2,
6128
  ForwardIterator result);
6129
 
6130
- template<class InputIterator1, class InputIterator2,
6131
- class OutputIterator, class Compare>
6132
  constexpr OutputIterator
6133
  set_union(InputIterator1 first1, InputIterator1 last1,
6134
  InputIterator2 first2, InputIterator2 last2,
6135
  OutputIterator result, Compare comp);
6136
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
@@ -6324,11 +6851,11 @@ Returns
6324
  comparisons and applications of each projection.
6325
 
6326
  *Remarks:* If \[`first1`, `last1`) contains m elements that are
6327
  equivalent to each other and \[`first2`, `last2`) contains n elements
6328
  that are equivalent to them, the last max(m - n, 0) elements from
6329
- \[`first1`, `last1`) is copied to the output range, in order.
6330
 
6331
  #### `set_symmetric_difference` <a id="set.symmetric.difference">[[set.symmetric.difference]]</a>
6332
 
6333
  ``` cpp
6334
  template<class InputIterator1, class InputIterator2,
@@ -6407,10 +6934,12 @@ elements from \[`first1`, `last1`) if m > n, and the last n - m of these
6407
  elements from \[`first2`, `last2`) if m < n. In either case, the
6408
  elements are copied in order.
6409
 
6410
  ### Heap operations <a id="alg.heap.operations">[[alg.heap.operations]]</a>
6411
 
 
 
6412
  A random access range \[`a`, `b`) is a *heap with respect to `comp` and
6413
  `proj`* for a comparator and projection `comp` and `proj` if its
6414
  elements are organized such that:
6415
 
6416
  - With `N = b - a`, for all i, 0 < i < N,
@@ -6447,14 +6976,15 @@ template<random_access_range R, class Comp = ranges::less, class Proj = identity
6447
 
6448
  Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
6449
  no parameters by those names.
6450
 
6451
  *Preconditions:* The range \[`first`, `last - 1`) is a valid heap with
6452
- respect to `comp` and `proj`. For the overloads in namespace `std`, the
6453
- type of `*first` meets the *Cpp17MoveConstructible* requirements
6454
- ([[cpp17.moveconstructible]]) and the *Cpp17MoveAssignable*
6455
- requirements ([[cpp17.moveassignable]]).
 
6456
 
6457
  *Effects:* Places the value in the location `last - 1` into the
6458
  resulting heap \[`first`, `last`).
6459
 
6460
  *Returns:* `last` for the overloads in namespace `ranges`.
@@ -6524,14 +7054,15 @@ template<random_access_range R, class Comp = ranges::less, class Proj = identity
6524
  ```
6525
 
6526
  Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
6527
  no parameters by those names.
6528
 
6529
- *Preconditions:* For the overloads in namespace `std`, the type of
6530
- `*first` meets the *Cpp17MoveConstructible*
6531
- ([[cpp17.moveconstructible]]) and *Cpp17MoveAssignable*
6532
- ([[cpp17.moveassignable]]) requirements.
 
6533
 
6534
  *Effects:* Constructs a heap with respect to `comp` and `proj` out of
6535
  the range \[`first`, `last`).
6536
 
6537
  *Returns:* `last` for the overloads in namespace `ranges`.
@@ -6683,19 +7214,19 @@ template<class T, class Proj = identity,
6683
  ```
6684
 
6685
  *Preconditions:* For the first form, `T` meets the
6686
  *Cpp17LessThanComparable* requirements ([[cpp17.lessthancomparable]]).
6687
 
6688
- *Returns:* The smaller value.
6689
-
6690
- *Remarks:* Returns the first argument when the arguments are equivalent.
6691
- An invocation may explicitly specify an argument for the template
6692
- parameter `T` of the overloads in namespace `std`.
6693
 
6694
  *Complexity:* Exactly one comparison and two applications of the
6695
  projection, if any.
6696
 
 
 
 
6697
  ``` cpp
6698
  template<class T>
6699
  constexpr T min(initializer_list<T> r);
6700
  template<class T, class Compare>
6701
  constexpr T min(initializer_list<T> r, Compare comp);
@@ -6713,20 +7244,19 @@ template<input_range R, class Proj = identity,
6713
  *Preconditions:* `ranges::distance(r) > 0`. For the overloads in
6714
  namespace `std`, `T` meets the *Cpp17CopyConstructible* requirements.
6715
  For the first form, `T` meets the *Cpp17LessThanComparable* requirements
6716
  ([[cpp17.lessthancomparable]]).
6717
 
6718
- *Returns:* The smallest value in the input range.
6719
-
6720
- *Remarks:* Returns a copy of the leftmost element when several elements
6721
- are equivalent to the smallest. An invocation may explicitly specify an
6722
- argument for the template parameter `T` of the overloads in namespace
6723
- `std`.
6724
 
6725
  *Complexity:* Exactly `ranges::distance(r) - 1` comparisons and twice as
6726
  many applications of the projection, if any.
6727
 
 
 
 
6728
  ``` cpp
6729
  template<class T>
6730
  constexpr const T& max(const T& a, const T& b);
6731
  template<class T, class Compare>
6732
  constexpr const T& max(const T& a, const T& b, Compare comp);
@@ -6737,19 +7267,19 @@ template<class T, class Proj = identity,
6737
  ```
6738
 
6739
  *Preconditions:* For the first form, `T` meets the
6740
  *Cpp17LessThanComparable* requirements ([[cpp17.lessthancomparable]]).
6741
 
6742
- *Returns:* The larger value.
6743
-
6744
- *Remarks:* Returns the first argument when the arguments are equivalent.
6745
- An invocation may explicitly specify an argument for the template
6746
- parameter `T` of the overloads in namespace `std`.
6747
 
6748
  *Complexity:* Exactly one comparison and two applications of the
6749
  projection, if any.
6750
 
 
 
 
6751
  ``` cpp
6752
  template<class T>
6753
  constexpr T max(initializer_list<T> r);
6754
  template<class T, class Compare>
6755
  constexpr T max(initializer_list<T> r, Compare comp);
@@ -6767,20 +7297,19 @@ template<input_range R, class Proj = identity,
6767
  *Preconditions:* `ranges::distance(r) > 0`. For the overloads in
6768
  namespace `std`, `T` meets the *Cpp17CopyConstructible* requirements.
6769
  For the first form, `T` meets the *Cpp17LessThanComparable* requirements
6770
  ([[cpp17.lessthancomparable]]).
6771
 
6772
- *Returns:* The largest value in the input range.
6773
-
6774
- *Remarks:* Returns a copy of the leftmost element when several elements
6775
- are equivalent to the largest. An invocation may explicitly specify an
6776
- argument for the template parameter `T` of the overloads in namespace
6777
- `std`.
6778
 
6779
  *Complexity:* Exactly `ranges::distance(r) - 1` comparisons and twice as
6780
  many applications of the projection, if any.
6781
 
 
 
 
6782
  ``` cpp
6783
  template<class T>
6784
  constexpr pair<const T&, const T&> minmax(const T& a, const T& b);
6785
  template<class T, class Compare>
6786
  constexpr pair<const T&, const T&> minmax(const T& a, const T& b, Compare comp);
@@ -6794,16 +7323,16 @@ template<class T, class Proj = identity,
6794
  *Preconditions:* For the first form, `T` meets the
6795
  *Cpp17LessThanComparable* requirements ([[cpp17.lessthancomparable]]).
6796
 
6797
  *Returns:* `{b, a}` if `b` is smaller than `a`, and `{a, b}` otherwise.
6798
 
6799
- *Remarks:* An invocation may explicitly specify an argument for the
6800
- template parameter `T` of the overloads in namespace `std`.
6801
-
6802
  *Complexity:* Exactly one comparison and two applications of the
6803
  projection, if any.
6804
 
 
 
 
6805
  ``` cpp
6806
  template<class T>
6807
  constexpr pair<T, T> minmax(initializer_list<T> t);
6808
  template<class T, class Compare>
6809
  constexpr pair<T, T> minmax(initializer_list<T> t, Compare comp);
@@ -6826,17 +7355,17 @@ requirements ([[cpp17.lessthancomparable]]).
6826
 
6827
  *Returns:* Let `X` be the return type. Returns `X{x, y}`, where `x` is a
6828
  copy of the leftmost element with the smallest value and `y` a copy of
6829
  the rightmost element with the largest value in the input range.
6830
 
6831
- *Remarks:* An invocation may explicitly specify an argument for the
6832
- template parameter `T` of the overloads in namespace `std`.
6833
-
6834
  *Complexity:* At most (3/2)`ranges::distance(r)` applications of the
6835
  corresponding predicate and twice as many applications of the
6836
  projection, if any.
6837
 
 
 
 
6838
  ``` cpp
6839
  template<class ForwardIterator>
6840
  constexpr ForwardIterator min_element(ForwardIterator first, ForwardIterator last);
6841
 
6842
  template<class ExecutionPolicy, class ForwardIterator>
@@ -6846,12 +7375,11 @@ template<class ExecutionPolicy, class ForwardIterator>
6846
  template<class ForwardIterator, class Compare>
6847
  constexpr ForwardIterator min_element(ForwardIterator first, ForwardIterator last,
6848
  Compare comp);
6849
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
6850
  ForwardIterator min_element(ExecutionPolicy&& exec,
6851
- ForwardIterator first, ForwardIterator last,
6852
- Compare comp);
6853
 
6854
  template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
6855
  indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
6856
  constexpr I ranges::min_element(I first, S last, Comp comp = {}, Proj proj = {});
6857
  template<forward_range R, class Proj = identity,
@@ -6931,23 +7459,25 @@ template<class ExecutionPolicy, class ForwardIterator, class Compare>
6931
  minmax_element(ExecutionPolicy&& exec,
6932
  ForwardIterator first, ForwardIterator last, Compare comp);
6933
 
6934
  template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
6935
  indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
6936
- constexpr ranges::minmax_result<I>
6937
  ranges::minmax_element(I first, S last, Comp comp = {}, Proj proj = {});
6938
  template<forward_range R, class Proj = identity,
6939
  indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
6940
- constexpr ranges::minmax_result<borrowed_iterator_t<R>>
6941
  ranges::minmax_element(R&& r, Comp comp = {}, Proj proj = {});
6942
  ```
6943
 
6944
  *Returns:* `{first, first}` if \[`first`, `last`) is empty, otherwise
6945
  `{m, M}`, where `m` is the first iterator in \[`first`, `last`) such
6946
  that no iterator in the range refers to a smaller element, and where `M`
6947
- is the last iterator[^5] in \[`first`, `last`) such that no iterator in
6948
- the range refers to a larger element.
 
 
6949
 
6950
  *Complexity:* Let N be `last - first`. At most
6951
  $\max(\bigl\lfloor{\frac{3}{2}} (N-1)\bigr\rfloor, 0)$ comparisons and
6952
  twice as many applications of the projection, if any.
6953
 
@@ -6965,16 +7495,19 @@ template<class T, class Proj = identity,
6965
  ```
6966
 
6967
  Let `comp` be `less{}` for the overloads with no parameter `comp`, and
6968
  let `proj` be `identity{}` for the overloads with no parameter `proj`.
6969
 
6970
- *Preconditions:* `bool(comp(proj(hi), proj(lo)))` is `false`. For the
6971
- first form, type `T` meets the *Cpp17LessThanComparable* requirements
6972
- ([[cpp17.lessthancomparable]]).
 
6973
 
6974
- *Returns:* `lo` if `bool(comp(proj(v), proj(lo)))` is `true`, `hi` if
6975
- `bool(comp(proj(hi), proj(v)))` is `true`, otherwise `v`.
 
 
6976
 
6977
  [*Note 1*: If NaN is avoided, `T` can be a floating-point
6978
  type. — *end note*]
6979
 
6980
  *Complexity:* At most two comparisons and three applications of the
@@ -7039,11 +7572,11 @@ the sequences yields the same result as the comparison of the first
7039
  corresponding pair of elements that are not equivalent.
7040
 
7041
  [*Example 1*:
7042
 
7043
  `ranges::lexicographical_compare(I1, S1, I2, S2, Comp, Proj1, Proj2)`
7044
- could be implemented as:
7045
 
7046
  ``` cpp
7047
  for ( ; first1 != last1 && first2 != last2 ; ++first1, (void) ++first2) {
7048
  if (invoke(comp, invoke(proj1, *first1), invoke(proj2, *first2))) return true;
7049
  if (invoke(comp, invoke(proj2, *first2), invoke(proj1, *first1))) return false;
@@ -7065,23 +7598,20 @@ template<class InputIterator1, class InputIterator2, class Cmp>
7065
  InputIterator2 b2, InputIterator2 e2,
7066
  Cmp comp)
7067
  -> decltype(comp(*b1, *b2));
7068
  ```
7069
 
 
 
 
7070
  *Mandates:* `decltype(comp(*b1, *b2))` is a comparison category type.
7071
 
7072
- *Effects:* Lexicographically compares two ranges and produces a result
7073
- of the strongest applicable comparison category type. Equivalent to:
 
7074
 
7075
- ``` cpp
7076
- for ( ; b1 != e1 && b2 != e2; void(++b1), void(++b2) )
7077
- if (auto cmp = comp(*b1,*b2); cmp != 0)
7078
- return cmp;
7079
- return b1 != e1 ? strong_ordering::greater :
7080
- b2 != e2 ? strong_ordering::less :
7081
- strong_ordering::equal;
7082
- ```
7083
 
7084
  ``` cpp
7085
  template<class InputIterator1, class InputIterator2>
7086
  constexpr auto
7087
  lexicographical_compare_three_way(InputIterator1 b1, InputIterator1 e1,
@@ -7382,10 +7912,22 @@ namespace std {
7382
 
7383
  // [numeric.iota], iota
7384
  template<class ForwardIterator, class T>
7385
  constexpr void iota(ForwardIterator first, ForwardIterator last, T value);
7386
 
 
 
 
 
 
 
 
 
 
 
 
 
7387
  // [numeric.ops.gcd], greatest common divisor
7388
  template<class M, class N>
7389
  constexpr common_type_t<M, N> gcd(M m, N n);
7390
 
7391
  // [numeric.ops.lcm], least common multiple
@@ -7400,12 +7942,14 @@ namespace std {
7400
  }
7401
  ```
7402
 
7403
  ## Generalized numeric operations <a id="numeric.ops">[[numeric.ops]]</a>
7404
 
 
 
7405
  [*Note 1*: The use of closed ranges as well as semi-open ranges to
7406
- specify requirements throughout this subclause is
7407
  intentional. — *end note*]
7408
 
7409
  ### Definitions <a id="numerics.defns">[[numerics.defns]]</a>
7410
 
7411
  Define `GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, ..., aN)` as follows:
@@ -7788,11 +8332,11 @@ GENERALIZED_NONCOMMUTATIVE_SUM(
7788
  *Remarks:* `result` may be equal to `first`.
7789
 
7790
  [*Note 1*: The difference between `exclusive_scan` and `inclusive_scan`
7791
  is that `exclusive_scan` excludes the iᵗʰ input element from the iᵗʰ
7792
  sum. If `binary_op` is not mathematically associative, the behavior of
7793
- `exclusive_scan` may be nondeterministic. — *end note*]
7794
 
7795
  ### Inclusive scan <a id="inclusive.scan">[[inclusive.scan]]</a>
7796
 
7797
  ``` cpp
7798
  template<class InputIterator, class OutputIterator>
@@ -7883,11 +8427,11 @@ through `result + K` the value of
7883
  *Remarks:* `result` may be equal to `first`.
7884
 
7885
  [*Note 1*: The difference between `exclusive_scan` and `inclusive_scan`
7886
  is that `inclusive_scan` includes the iᵗʰ input element in the iᵗʰ sum.
7887
  If `binary_op` is not mathematically associative, the behavior of
7888
- `inclusive_scan` may be nondeterministic. — *end note*]
7889
 
7890
  ### Transform exclusive scan <a id="transform.exclusive.scan">[[transform.exclusive.scan]]</a>
7891
 
7892
  ``` cpp
7893
  template<class InputIterator, class OutputIterator, class T,
@@ -7940,11 +8484,11 @@ GENERALIZED_NONCOMMUTATIVE_SUM(
7940
 
7941
  [*Note 1*: The difference between `transform_exclusive_scan` and
7942
  `transform_inclusive_scan` is that `transform_exclusive_scan` excludes
7943
  the iᵗʰ input element from the iᵗʰ sum. If `binary_op` is not
7944
  mathematically associative, the behavior of `transform_exclusive_scan`
7945
- may be nondeterministic. `transform_exclusive_scan` does not apply
7946
  `unary_op` to `init`. — *end note*]
7947
 
7948
  ### Transform inclusive scan <a id="transform.inclusive.scan">[[transform.inclusive.scan]]</a>
7949
 
7950
  ``` cpp
@@ -8023,11 +8567,11 @@ through `result + K` the value of
8023
 
8024
  [*Note 1*: The difference between `transform_exclusive_scan` and
8025
  `transform_inclusive_scan` is that `transform_inclusive_scan` includes
8026
  the iᵗʰ input element in the iᵗʰ sum. If `binary_op` is not
8027
  mathematically associative, the behavior of `transform_inclusive_scan`
8028
- may be nondeterministic. `transform_inclusive_scan` does not apply
8029
  `unary_op` to `init`. — *end note*]
8030
 
8031
  ### Adjacent difference <a id="adjacent.difference">[[adjacent.difference]]</a>
8032
 
8033
  ``` cpp
@@ -8071,11 +8615,11 @@ denotes an object of type `minus<>`.
8071
 
8072
  - For the overloads with no `ExecutionPolicy`, `T` meets the
8073
  *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
8074
  - For all overloads, in the ranges \[`first`, `last`\] and \[`result`,
8075
  `result + (last - first)`\], `binary_op` neither modifies elements nor
8076
- invalidate iterators or subranges. [^10]
8077
 
8078
  *Effects:* For the overloads with no `ExecutionPolicy` and a non-empty
8079
  range, the function creates an accumulator `acc` of type `T`,
8080
  initializes it with `*first`, and assigns the result to `*result`. For
8081
  every iterator `i` in \[`first + 1`, `last`) in order, creates an object
@@ -8112,18 +8656,37 @@ expression `++val`, where `val` has type `T`, is well-formed.
8112
  \[`first`, `last`), assigns `*i = value` and increments `value` as if by
8113
  `++value`.
8114
 
8115
  *Complexity:* Exactly `last - first` increments and assignments.
8116
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8117
  ### Greatest common divisor <a id="numeric.ops.gcd">[[numeric.ops.gcd]]</a>
8118
 
8119
  ``` cpp
8120
  template<class M, class N>
8121
  constexpr common_type_t<M, N> gcd(M m, N n);
8122
  ```
8123
 
8124
- *Mandates:* `M` and `N` both are integer types and not cv `bool`.
8125
 
8126
  *Preconditions:* |`m`| and |`n`| are representable as a value of
8127
  `common_type_t<M, N>`.
8128
 
8129
  [*Note 1*: These requirements ensure, for example, that
@@ -8140,11 +8703,11 @@ greatest common divisor of |`m`| and |`n`|.
8140
  ``` cpp
8141
  template<class M, class N>
8142
  constexpr common_type_t<M, N> lcm(M m, N n);
8143
  ```
8144
 
8145
- *Mandates:* `M` and `N` both are integer types and not cv `bool`.
8146
 
8147
  *Preconditions:* |`m`| and |`n`| are representable as a value of
8148
  `common_type_t<M, N>`. The least common multiple of |`m`| and |`n`| is
8149
  representable as a value of type `common_type_t<M, N>`.
8150
 
@@ -8189,95 +8752,93 @@ n for this purpose. — *end note*]
8189
  *Returns:* A pointer to array element $i+\frac{j-i}{2}$ of `x`, where
8190
  the result of the division is truncated towards zero.
8191
 
8192
  ## Specialized `<memory>` algorithms <a id="specialized.algorithms">[[specialized.algorithms]]</a>
8193
 
8194
- The contents specified in this subclause  [[specialized.algorithms]] are
8195
- declared in the header `<memory>`.
 
 
8196
 
8197
  Unless otherwise specified, if an exception is thrown in the following
8198
  algorithms, objects constructed by a placement *new-expression*
8199
  [[expr.new]] are destroyed in an unspecified order before allowing the
8200
  exception to propagate.
8201
 
8202
- [*Note 1*: When invoked on ranges of potentially-overlapping subobjects
8203
- [[intro.object]], the algorithms specified in this subclause
8204
- [[specialized.algorithms]] result in undefined behavior. — *end note*]
8205
-
8206
- Some algorithms specified in this clause make use of the exposition-only
8207
- function `voidify`:
8208
 
8209
  ``` cpp
8210
  template<class T>
8211
  constexpr void* voidify(T& obj) noexcept {
8212
- return const_cast<void*>(static_cast<const volatile void*>(addressof(obj)));
8213
  }
8214
  ```
8215
 
8216
  ### Special memory concepts <a id="special.mem.concepts">[[special.mem.concepts]]</a>
8217
 
8218
  Some algorithms in this subclause are constrained with the following
8219
  exposition-only concepts:
8220
 
8221
  ``` cpp
8222
  template<class I>
8223
- concept no-throw-input-iterator = // exposition only
8224
  input_iterator<I> &&
8225
  is_lvalue_reference_v<iter_reference_t<I>> &&
8226
  same_as<remove_cvref_t<iter_reference_t<I>>, iter_value_t<I>>;
8227
  ```
8228
 
8229
- A type `I` models *`no-throw-input-iterator`* only if no exceptions are
8230
  thrown from increment, copy construction, move construction, copy
8231
  assignment, move assignment, or indirection through valid iterators.
8232
 
8233
  [*Note 1*: This concept allows some `input_iterator`
8234
  [[iterator.concept.input]] operations to throw
8235
  exceptions. — *end note*]
8236
 
8237
  ``` cpp
8238
  template<class S, class I>
8239
- concept no-throw-sentinel = sentinel_for<S, I>; // exposition only
8240
  ```
8241
 
8242
- Types `S` and `I` model *`no-throw-sentinel`* only if no exceptions are
8243
  thrown from copy construction, move construction, copy assignment, move
8244
  assignment, or comparisons between valid values of type `I` and `S`.
8245
 
8246
  [*Note 2*: This concept allows some `sentinel_for`
8247
  [[iterator.concept.sentinel]] operations to throw
8248
  exceptions. — *end note*]
8249
 
8250
  ``` cpp
8251
  template<class R>
8252
- concept no-throw-input-range = // exposition only
8253
  range<R> &&
8254
- no-throw-input-iterator<iterator_t<R>> &&
8255
- no-throw-sentinel<sentinel_t<R>, iterator_t<R>>;
8256
  ```
8257
 
8258
- A type `R` models *`no-throw-input-range`* only if no exceptions are
8259
- thrown from calls to `ranges::begin` and `ranges::end` on an object of
8260
- type `R`.
8261
 
8262
  ``` cpp
8263
  template<class I>
8264
- concept no-throw-forward-iterator = // exposition only
8265
- no-throw-input-iterator<I> &&
8266
  forward_iterator<I> &&
8267
- no-throw-sentinel<I, I>;
8268
  ```
8269
 
8270
  [*Note 3*: This concept allows some `forward_iterator`
8271
  [[iterator.concept.forward]] operations to throw
8272
  exceptions. — *end note*]
8273
 
8274
  ``` cpp
8275
  template<class R>
8276
- concept no-throw-forward-range = // exposition only
8277
- no-throw-input-range<R> &&
8278
- no-throw-forward-iterator<iterator_t<R>>;
8279
  ```
8280
 
8281
  ### `uninitialized_default_construct` <a id="uninitialized.construct.default">[[uninitialized.construct.default]]</a>
8282
 
8283
  ``` cpp
@@ -8293,14 +8854,14 @@ for (; first != last; ++first)
8293
  typename iterator_traits<NoThrowForwardIterator>::value_type;
8294
  ```
8295
 
8296
  ``` cpp
8297
  namespace ranges {
8298
- template<no-throw-forward-iterator I, no-throw-sentinel<I> S>
8299
  requires default_initializable<iter_value_t<I>>
8300
  I uninitialized_default_construct(I first, S last);
8301
- template<no-throw-forward-range R>
8302
  requires default_initializable<range_value_t<R>>
8303
  borrowed_iterator_t<R> uninitialized_default_construct(R&& r);
8304
  }
8305
  ```
8306
 
@@ -8326,11 +8887,11 @@ for (; n > 0; (void)++first, --n)
8326
  return first;
8327
  ```
8328
 
8329
  ``` cpp
8330
  namespace ranges {
8331
- template<no-throw-forward-iterator I>
8332
  requires default_initializable<iter_value_t<I>>
8333
  I uninitialized_default_construct_n(I first, iter_difference_t<I> n);
8334
  }
8335
  ```
8336
 
@@ -8356,14 +8917,14 @@ for (; first != last; ++first)
8356
  typename iterator_traits<NoThrowForwardIterator>::value_type();
8357
  ```
8358
 
8359
  ``` cpp
8360
  namespace ranges {
8361
- template<no-throw-forward-iterator I, no-throw-sentinel<I> S>
8362
  requires default_initializable<iter_value_t<I>>
8363
  I uninitialized_value_construct(I first, S last);
8364
- template<no-throw-forward-range R>
8365
  requires default_initializable<range_value_t<R>>
8366
  borrowed_iterator_t<R> uninitialized_value_construct(R&& r);
8367
  }
8368
  ```
8369
 
@@ -8389,11 +8950,11 @@ for (; n > 0; (void)++first, --n)
8389
  return first;
8390
  ```
8391
 
8392
  ``` cpp
8393
  namespace ranges {
8394
- template<no-throw-forward-iterator I>
8395
  requires default_initializable<iter_value_t<I>>
8396
  I uninitialized_value_construct_n(I first, iter_difference_t<I> n);
8397
  }
8398
  ```
8399
 
@@ -8426,15 +8987,15 @@ for (; first != last; ++result, (void) ++first)
8426
  *Returns:* `result`.
8427
 
8428
  ``` cpp
8429
  namespace ranges {
8430
  template<input_iterator I, sentinel_for<I> S1,
8431
- no-throw-forward-iterator O, no-throw-sentinel<O> S2>
8432
  requires constructible_from<iter_value_t<O>, iter_reference_t<I>>
8433
  uninitialized_copy_result<I, O>
8434
  uninitialized_copy(I ifirst, S1 ilast, O ofirst, S2 olast);
8435
- template<input_range IR, no-throw-forward-range OR>
8436
  requires constructible_from<range_value_t<OR>, range_reference_t<IR>>
8437
  uninitialized_copy_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>
8438
  uninitialized_copy(IR&& in_range, OR&& out_range);
8439
  }
8440
  ```
@@ -8443,13 +9004,12 @@ namespace ranges {
8443
  `ilast`).
8444
 
8445
  *Effects:* Equivalent to:
8446
 
8447
  ``` cpp
8448
- for (; ifirst != ilast && ofirst != olast; ++ofirst, (void)++ifirst) {
8449
  ::new (voidify(*ofirst)) remove_reference_t<iter_reference_t<O>>(*ifirst);
8450
- }
8451
  return {std::move(ifirst), ofirst};
8452
  ```
8453
 
8454
  ``` cpp
8455
  template<class InputIterator, class Size, class NoThrowForwardIterator>
@@ -8461,21 +9021,20 @@ template<class InputIterator, class Size, class NoThrowForwardIterator>
8461
  `n`).
8462
 
8463
  *Effects:* Equivalent to:
8464
 
8465
  ``` cpp
8466
- for ( ; n > 0; ++result, (void) ++first, --n) {
8467
  ::new (voidify(*result))
8468
  typename iterator_traits<NoThrowForwardIterator>::value_type(*first);
8469
- }
8470
  ```
8471
 
8472
  *Returns:* `result`.
8473
 
8474
  ``` cpp
8475
  namespace ranges {
8476
- template<input_iterator I, no-throw-forward-iterator O, no-throw-sentinel<O> S>
8477
  requires constructible_from<iter_value_t<O>, iter_reference_t<I>>
8478
  uninitialized_copy_n_result<I, O>
8479
  uninitialized_copy_n(I ifirst, iter_difference_t<I> n, O ofirst, S olast);
8480
  }
8481
  ```
@@ -8484,11 +9043,11 @@ namespace ranges {
8484
  `ifirst`+\[0, `n`).
8485
 
8486
  *Effects:* Equivalent to:
8487
 
8488
  ``` cpp
8489
- auto t = uninitialized_copy(counted_iterator(ifirst, n),
8490
  default_sentinel, ofirst, olast);
8491
  return {std::move(t.in).base(), t.out};
8492
  ```
8493
 
8494
  ### `uninitialized_move` <a id="uninitialized.move">[[uninitialized.move]]</a>
@@ -8512,15 +9071,15 @@ return result;
8512
  ```
8513
 
8514
  ``` cpp
8515
  namespace ranges {
8516
  template<input_iterator I, sentinel_for<I> S1,
8517
- no-throw-forward-iterator O, no-throw-sentinel<O> S2>
8518
  requires constructible_from<iter_value_t<O>, iter_rvalue_reference_t<I>>
8519
  uninitialized_move_result<I, O>
8520
  uninitialized_move(I ifirst, S1 ilast, O ofirst, S2 olast);
8521
- template<input_range IR, no-throw-forward-range OR>
8522
  requires constructible_from<range_value_t<OR>, range_rvalue_reference_t<IR>>
8523
  uninitialized_move_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>
8524
  uninitialized_move(IR&& in_range, OR&& out_range);
8525
  }
8526
  ```
@@ -8529,19 +9088,18 @@ namespace ranges {
8529
  `ilast`).
8530
 
8531
  *Effects:* Equivalent to:
8532
 
8533
  ``` cpp
8534
- for (; ifirst != ilast && ofirst != olast; ++ofirst, (void)++ifirst) {
8535
  ::new (voidify(*ofirst))
8536
  remove_reference_t<iter_reference_t<O>>(ranges::iter_move(ifirst));
8537
- }
8538
  return {std::move(ifirst), ofirst};
8539
  ```
8540
 
8541
  [*Note 1*: If an exception is thrown, some objects in the range
8542
- \[`first`, `last`) are left in a valid, but unspecified
8543
  state. — *end note*]
8544
 
8545
  ``` cpp
8546
  template<class InputIterator, class Size, class NoThrowForwardIterator>
8547
  pair<InputIterator, NoThrowForwardIterator>
@@ -8560,11 +9118,11 @@ for (; n > 0; ++result, (void) ++first, --n)
8560
  return {first, result};
8561
  ```
8562
 
8563
  ``` cpp
8564
  namespace ranges {
8565
- template<input_iterator I, no-throw-forward-iterator O, no-throw-sentinel<O> S>
8566
  requires constructible_from<iter_value_t<O>, iter_rvalue_reference_t<I>>
8567
  uninitialized_move_n_result<I, O>
8568
  uninitialized_move_n(I ifirst, iter_difference_t<I> n, O ofirst, S olast);
8569
  }
8570
  ```
@@ -8573,17 +9131,17 @@ namespace ranges {
8573
  `ifirst`+\[0, `n`).
8574
 
8575
  *Effects:* Equivalent to:
8576
 
8577
  ``` cpp
8578
- auto t = uninitialized_move(counted_iterator(ifirst, n),
8579
  default_sentinel, ofirst, olast);
8580
  return {std::move(t.in).base(), t.out};
8581
  ```
8582
 
8583
  [*Note 2*: If an exception is thrown, some objects in the range
8584
- `first`+\[0, `n`) are left in a valid but unspecified
8585
  state. — *end note*]
8586
 
8587
  ### `uninitialized_fill` <a id="uninitialized.fill">[[uninitialized.fill]]</a>
8588
 
8589
  ``` cpp
@@ -8599,25 +9157,24 @@ for (; first != last; ++first)
8599
  typename iterator_traits<NoThrowForwardIterator>::value_type(x);
8600
  ```
8601
 
8602
  ``` cpp
8603
  namespace ranges {
8604
- template<no-throw-forward-iterator I, no-throw-sentinel<I> S, class T>
8605
  requires constructible_from<iter_value_t<I>, const T&>
8606
  I uninitialized_fill(I first, S last, const T& x);
8607
- template<no-throw-forward-range R, class T>
8608
  requires constructible_from<range_value_t<R>, const T&>
8609
  borrowed_iterator_t<R> uninitialized_fill(R&& r, const T& x);
8610
  }
8611
  ```
8612
 
8613
  *Effects:* Equivalent to:
8614
 
8615
  ``` cpp
8616
- for (; first != last; ++first) {
8617
  ::new (voidify(*first)) remove_reference_t<iter_reference_t<I>>(x);
8618
- }
8619
  return first;
8620
  ```
8621
 
8622
  ``` cpp
8623
  template<class NoThrowForwardIterator, class Size, class T>
@@ -8633,11 +9190,11 @@ for (; n--; ++first)
8633
  return first;
8634
  ```
8635
 
8636
  ``` cpp
8637
  namespace ranges {
8638
- template<no-throw-forward-iterator I, class T>
8639
  requires constructible_from<iter_value_t<I>, const T&>
8640
  I uninitialized_fill_n(I first, iter_difference_t<I> n, const T& x);
8641
  }
8642
  ```
8643
 
@@ -8659,11 +9216,11 @@ namespace ranges {
8659
  }
8660
  ```
8661
 
8662
  *Constraints:* The expression
8663
  `::new (declval<void*>()) T(declval<Args>()...)` is well-formed when
8664
- treated as an unevaluated operand.
8665
 
8666
  *Effects:* Equivalent to:
8667
 
8668
  ``` cpp
8669
  return ::new (voidify(*location)) T(std::forward<Args>(args)...);
@@ -8698,14 +9255,14 @@ for (; first != last; ++first)
8698
  destroy_at(addressof(*first));
8699
  ```
8700
 
8701
  ``` cpp
8702
  namespace ranges {
8703
- template<no-throw-input-iterator I, no-throw-sentinel<I> S>
8704
  requires destructible<iter_value_t<I>>
8705
  constexpr I destroy(I first, S last) noexcept;
8706
- template<no-throw-input-range R>
8707
  requires destructible<range_value_t<R>>
8708
  constexpr borrowed_iterator_t<R> destroy(R&& r) noexcept;
8709
  }
8710
  ```
8711
 
@@ -8730,20 +9287,20 @@ for (; n > 0; (void)++first, --n)
8730
  return first;
8731
  ```
8732
 
8733
  ``` cpp
8734
  namespace ranges {
8735
- template<no-throw-input-iterator I>
8736
  requires destructible<iter_value_t<I>>
8737
  constexpr I destroy_n(I first, iter_difference_t<I> n) noexcept;
8738
  }
8739
  ```
8740
 
8741
  *Effects:* Equivalent to:
8742
 
8743
  ``` cpp
8744
- return destroy(counted_iterator(first, n), default_sentinel).base();
8745
  ```
8746
 
8747
  ## C library algorithms <a id="alg.c.library">[[alg.c.library]]</a>
8748
 
8749
  [*Note 1*: The header `<cstdlib>` declares the functions described in
@@ -8756,40 +9313,46 @@ void* bsearch(const void* key, const void* base, size_t nmemb, size_t size,
8756
  compare-pred* compar);
8757
  void qsort(void* base, size_t nmemb, size_t size, c-compare-pred* compar);
8758
  void qsort(void* base, size_t nmemb, size_t size, compare-pred* compar);
8759
  ```
8760
 
 
 
 
8761
  *Effects:* These functions have the semantics specified in the C
8762
  standard library.
8763
 
8764
- *Preconditions:* The objects in the array pointed to by `base` are of
8765
- trivial type.
8766
-
8767
  *Throws:* Any exception thrown by `compar`
8768
  [[res.on.exception.handling]].
8769
 
8770
- ISO C 7.22.5.
8771
 
8772
  <!-- Link reference definitions -->
8773
  [accumulate]: #accumulate
8774
  [adjacent.difference]: #adjacent.difference
8775
  [alg.adjacent.find]: #alg.adjacent.find
8776
  [alg.all.of]: #alg.all.of
8777
  [alg.any.of]: #alg.any.of
8778
  [alg.binary.search]: #alg.binary.search
 
8779
  [alg.c.library]: #alg.c.library
8780
  [alg.clamp]: #alg.clamp
 
8781
  [alg.copy]: #alg.copy
8782
  [alg.count]: #alg.count
 
8783
  [alg.equal]: #alg.equal
8784
  [alg.fill]: #alg.fill
8785
  [alg.find]: #alg.find
8786
  [alg.find.end]: #alg.find.end
8787
  [alg.find.first.of]: #alg.find.first.of
 
 
8788
  [alg.foreach]: #alg.foreach
8789
  [alg.generate]: #alg.generate
8790
  [alg.heap.operations]: #alg.heap.operations
 
8791
  [alg.is.permutation]: #alg.is.permutation
8792
  [alg.lex.comparison]: #alg.lex.comparison
8793
  [alg.merge]: #alg.merge
8794
  [alg.min.max]: #alg.min.max
8795
  [alg.modifying.operations]: #alg.modifying.operations
@@ -8805,13 +9368,16 @@ ISO C 7.22.5.
8805
  [alg.replace]: #alg.replace
8806
  [alg.reverse]: #alg.reverse
8807
  [alg.rotate]: #alg.rotate
8808
  [alg.search]: #alg.search
8809
  [alg.set.operations]: #alg.set.operations
 
8810
  [alg.shift]: #alg.shift
8811
  [alg.sort]: #alg.sort
8812
  [alg.sorting]: #alg.sorting
 
 
8813
  [alg.swap]: #alg.swap
8814
  [alg.three.way]: #alg.three.way
8815
  [alg.transform]: #alg.transform
8816
  [alg.unique]: #alg.unique
8817
  [algorithm.stable]: library.md#algorithm.stable
@@ -8831,12 +9397,12 @@ ISO C 7.22.5.
8831
  [basic.lookup.argdep]: basic.md#basic.lookup.argdep
8832
  [basic.lookup.unqual]: basic.md#basic.lookup.unqual
8833
  [bidirectional.iterators]: iterators.md#bidirectional.iterators
8834
  [binary.search]: #binary.search
8835
  [class.conv]: class.md#class.conv
 
8836
  [containers]: containers.md#containers
8837
- [conv]: expr.md#conv
8838
  [conv.integral]: expr.md#conv.integral
8839
  [cpp17.copyassignable]: #cpp17.copyassignable
8840
  [cpp17.copyconstructible]: #cpp17.copyconstructible
8841
  [cpp17.lessthancomparable]: #cpp17.lessthancomparable
8842
  [cpp17.moveassignable]: #cpp17.moveassignable
@@ -8851,16 +9417,17 @@ ISO C 7.22.5.
8851
  [includes]: #includes
8852
  [inclusive.scan]: #inclusive.scan
8853
  [inner.product]: #inner.product
8854
  [input.iterators]: iterators.md#input.iterators
8855
  [intro.execution]: basic.md#intro.execution
8856
- [intro.object]: basic.md#intro.object
8857
  [intro.progress]: basic.md#intro.progress
8858
  [is.heap]: #is.heap
8859
  [is.sorted]: #is.sorted
 
8860
  [iterator.concept.forward]: iterators.md#iterator.concept.forward
8861
  [iterator.concept.input]: iterators.md#iterator.concept.input
 
8862
  [iterator.concept.sentinel]: iterators.md#iterator.concept.sentinel
8863
  [iterator.concept.sizedsentinel]: iterators.md#iterator.concept.sizedsentinel
8864
  [iterator.requirements]: iterators.md#iterator.requirements
8865
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
8866
  [lower.bound]: #lower.bound
@@ -8868,10 +9435,11 @@ ISO C 7.22.5.
8868
  [mismatch]: #mismatch
8869
  [multiset]: containers.md#multiset
8870
  [numeric.iota]: #numeric.iota
8871
  [numeric.ops]: #numeric.ops
8872
  [numeric.ops.gcd]: #numeric.ops.gcd
 
8873
  [numeric.ops.lcm]: #numeric.ops.lcm
8874
  [numeric.ops.midpoint]: #numeric.ops.midpoint
8875
  [numeric.ops.overview]: #numeric.ops.overview
8876
  [numerics.defns]: #numerics.defns
8877
  [output.iterators]: iterators.md#output.iterators
@@ -8892,15 +9460,17 @@ ISO C 7.22.5.
8892
  [set.union]: #set.union
8893
  [sort]: #sort
8894
  [sort.heap]: #sort.heap
8895
  [special.mem.concepts]: #special.mem.concepts
8896
  [specialized.algorithms]: #specialized.algorithms
 
8897
  [specialized.construct]: #specialized.construct
8898
  [specialized.destroy]: #specialized.destroy
8899
  [stable.sort]: #stable.sort
8900
  [swappable.requirements]: library.md#swappable.requirements
8901
  [temp.func.order]: temp.md#temp.func.order
 
8902
  [thread.jthread.class]: thread.md#thread.jthread.class
8903
  [thread.thread.class]: thread.md#thread.thread.class
8904
  [transform.exclusive.scan]: #transform.exclusive.scan
8905
  [transform.inclusive.scan]: #transform.inclusive.scan
8906
  [transform.reduce]: #transform.reduce
@@ -8913,17 +9483,17 @@ ISO C 7.22.5.
8913
 
8914
  [^1]: The decision whether to include a copying version was usually
8915
  based on complexity considerations. When the cost of doing the
8916
  operation dominates the cost of copy, the copying version is not
8917
  included. For example, `sort_copy` is not included because the cost
8918
- of sorting is much more significant, and users might as well do
8919
- `copy` followed by `sort`.
8920
 
8921
- [^2]: `copy_backward` should be used instead of copy when `last` is in
8922
  the range \[`result - `N, `result`).
8923
 
8924
- [^3]: `move_backward` should be used instead of move when `last` is in
8925
  the range \[`result - `N, `result`).
8926
 
8927
  [^4]: The use of fully closed ranges is intentional.
8928
 
8929
  [^5]: This behavior intentionally differs from `max_element`.
 
14
 
15
  | Subclause | | Header |
16
  | ---------------------------- | --------------------------------- | ------------- |
17
  | [[algorithms.requirements]] | Algorithms requirements | |
18
  | [[algorithms.parallel]] | Parallel algorithms | |
19
+ | [[algorithms.results]] | Algorithm result types | `<algorithm>` |
20
+ | [[alg.nonmodifying]] | Non-modifying sequence operations | |
21
  | [[alg.modifying.operations]] | Mutating sequence operations | |
22
  | [[alg.sorting]] | Sorting and related operations | |
23
  | [[numeric.ops]] | Generalized numeric operations | `<numeric>` |
24
  | [[specialized.algorithms]] | Specialized `<memory>` algorithms | `<memory>` |
25
  | [[alg.c.library]] | C library algorithms | `<cstdlib>` |
 
64
 
65
  Throughout this Clause, where the template parameters are not
66
  constrained, the names of template parameters are used to express type
67
  requirements.
68
 
69
+ - If an algorithm’s *Effects* element specifies that a value pointed to
70
+ by any iterator passed as an argument is modified, then the type of
71
+ that argument shall meet the requirements of a mutable iterator
72
+ [[iterator.requirements]].
73
  - If an algorithm’s template parameter is named `InputIterator`,
74
  `InputIterator1`, or `InputIterator2`, the template argument shall
75
  meet the *Cpp17InputIterator* requirements [[input.iterators]].
76
  - If an algorithm’s template parameter is named `OutputIterator`,
77
  `OutputIterator1`, or `OutputIterator2`, the template argument shall
78
  meet the *Cpp17OutputIterator* requirements [[output.iterators]].
79
  - If an algorithm’s template parameter is named `ForwardIterator`,
80
+ `ForwardIterator1`, `ForwardIterator2`, or `NoThrowForwardIterator`,
81
+ the template argument shall meet the *Cpp17ForwardIterator*
82
+ requirements [[forward.iterators]] if it is required to be a mutable
83
+ iterator, or model `forward_iterator` [[iterator.concept.forward]]
84
+ otherwise.
85
  - If an algorithm’s template parameter is named
86
+ `NoThrowForwardIterator`, the template argument is also required to
87
+ have the property that no exceptions are thrown from increment,
88
+ assignment, or comparison of, or indirection through, valid iterators.
 
 
89
  - If an algorithm’s template parameter is named `BidirectionalIterator`,
90
  `BidirectionalIterator1`, or `BidirectionalIterator2`, the template
91
  argument shall meet the *Cpp17BidirectionalIterator* requirements
92
+ [[bidirectional.iterators]] if it is required to be a mutable
93
+ iterator, or model `bidirectional_iterator` [[iterator.concept.bidir]]
94
+ otherwise.
95
  - If an algorithm’s template parameter is named `RandomAccessIterator`,
96
  `RandomAccessIterator1`, or `RandomAccessIterator2`, the template
97
  argument shall meet the *Cpp17RandomAccessIterator* requirements
98
+ [[random.access.iterators]] if it is required to be a mutable
99
+ iterator, or model `random_access_iterator`
100
+ [[iterator.concept.random.access]] otherwise.
101
 
102
+ [*Note 1*: These requirements do not affect iterator arguments that are
103
+ constrained, for which iterator category and mutability requirements are
104
+ expressed explicitly. *end note*]
 
105
 
106
+ Both in-place and copying versions are provided for certain
107
+ algorithms.[^1]
 
 
 
108
 
109
+ When such a version is provided for *algorithm* it is called
 
110
  *algorithm`_copy`*. Algorithms that take predicates end with the suffix
111
  `_if` (which follows the suffix `_copy`).
112
 
113
  When not otherwise constrained, the `Predicate` parameter is used
114
  whenever an algorithm expects a function object [[function.objects]]
115
  that, when applied to the result of dereferencing the corresponding
116
+ iterator, returns a value testable as `true`. If an algorithm takes
117
+ `Predicate pred` as its argument and `first` as its iterator argument
118
+ with value type `T`, the expression `pred(*first)` shall be well-formed
119
+ and the type `decltype(pred(*first))` shall model `boolean-testable`
120
+ [[concept.booleantestable]]. The function object `pred` shall not apply
121
+ any non-constant function through its argument. Given a glvalue `u` of
122
+ type (possibly const) `T` that designates the same object as `*first`,
123
+ `pred(u)` shall be a valid expression that is equal to `pred(*first)`.
124
 
125
  When not otherwise constrained, the `BinaryPredicate` parameter is used
126
+ whenever an algorithm expects a function object that, when applied to
127
+ the result of dereferencing two corresponding iterators or to
128
+ dereferencing an iterator and type `T` when `T` is part of the
129
+ signature, returns a value testable as `true`. If an algorithm takes
130
  `BinaryPredicate binary_pred` as its argument and `first1` and `first2`
131
+ as its iterator arguments with respective value types `T1` and `T2`, the
132
+ expression `binary_pred(*first1, *first2)` shall be well-formed and the
133
+ type `decltype(binary_pred(*first1, *first2))` shall model
134
+ `boolean-testable`. Unless otherwise specified, `BinaryPredicate` always
135
+ takes the first iterator’s `value_type` as its first argument, that is,
136
+ in those cases when `T value` is part of the signature, the expression
137
+ `binary_pred(*first1, value)` shall be well-formed and the type
138
+ `decltype(binary_pred(*first1, value))` shall model `boolean-testable`.
139
+ `binary_pred` shall not apply any non-constant function through any of
140
+ its arguments. Given a glvalue `u` of type (possibly const) `T1` that
141
+ designates the same object as `*first1`, and a glvalue `v` of type
142
+ (possibly const) `T2` that designates the same object as `*first2`,
143
+ `binary_pred(u, *first2)`, `binary_pred(*first1, v)`, and
144
  `binary_pred(u, v)` shall each be a valid expression that is equal to
145
  `binary_pred(*first1, *first2)`, and `binary_pred(u, value)` shall be a
146
  valid expression that is equal to `binary_pred(*first1, value)`.
147
 
148
  The parameters `UnaryOperation`, `BinaryOperation`, `BinaryOperation1`,
149
  and `BinaryOperation2` are used whenever an algorithm expects a function
150
  object [[function.objects]].
151
 
152
  [*Note 2*: Unless otherwise specified, algorithms that take function
153
+ objects as arguments can copy those function objects freely. If object
154
+ identity is important, a wrapper class that points to a non-copied
155
+ implementation object such as `reference_wrapper<T>` [[refwrap]], or
156
+ some equivalent solution, can be used. *end note*]
 
157
 
158
  When the description of an algorithm gives an expression such as
159
  `*first == value` for a condition, the expression shall evaluate to
160
  either `true` or `false` in boolean contexts.
161
 
 
187
  iter_difference_t<decltype(b)> n = 0;
188
  for (auto tmp = b; tmp != a; ++tmp) --n;
189
  return n;
190
  ```
191
 
192
+ In the description of the algorithms, given an iterator `a` whose
193
+ difference type is `D`, and an expression `n` of integer-like type other
194
+ than cv `D`, the semantics of `a + n` and `a - n` are, respectively,
195
+ those of `a + D(n)` and `a - D(n)`.
196
+
197
  In the description of algorithm return values, a sentinel value `s`
198
  denoting the end of a range \[`i`, `s`) is sometimes returned where an
199
  iterator is expected. In these cases, the semantics are as if the
200
  sentinel is converted into an iterator using `ranges::next(i, s)`.
201
 
202
  Overloads of algorithms that take `range` arguments [[range.range]]
203
  behave as if they are implemented by calling `ranges::begin` and
204
  `ranges::end` on the `range`(s) and dispatching to the overload in
205
  namespace `ranges` that takes separate iterator and sentinel arguments.
206
 
207
+ The well-formedness and behavior of a call to an algorithm with an
208
+ explicitly-specified template argument list is unspecified, except where
209
+ explicitly stated otherwise.
210
 
211
+ [*Note 3*: Consequently, an implementation can declare an algorithm
212
+ with different template parameters than those presented. — *end note*]
213
 
214
  ## Parallel algorithms <a id="algorithms.parallel">[[algorithms.parallel]]</a>
215
 
216
  ### Preamble <a id="algorithms.parallel.defns">[[algorithms.parallel.defns]]</a>
217
 
 
284
 
285
  Unless otherwise specified, function objects passed into parallel
286
  algorithms as objects of type `Predicate`, `BinaryPredicate`, `Compare`,
287
  `UnaryOperation`, `BinaryOperation`, `BinaryOperation1`,
288
  `BinaryOperation2`, and the operators used by the analogous overloads to
289
+ these parallel algorithms that are formed by an invocation with the
290
+ specified default predicate or operation (where applicable) shall not
291
+ directly or indirectly modify objects via their arguments, nor shall
292
  they rely on the identity of the provided objects.
293
 
294
  ### Effect of execution policies on algorithm execution <a id="algorithms.parallel.exec">[[algorithms.parallel.exec]]</a>
295
 
296
  Parallel algorithms have template parameters named `ExecutionPolicy`
 
310
  Unless otherwise stated, implementations may make arbitrary copies of
311
  elements (with type `T`) from sequences where
312
  `is_trivially_copy_constructible_v<T>` and
313
  `is_trivially_destructible_v<T>` are `true`.
314
 
315
+ [*Note 2*: This implies that user-supplied function objects cannot rely
316
+ on object identity of arguments for such input sequences. If object
317
+ identity of the arguments to these function objects is important, a
318
+ wrapping iterator that returns a non-copied implementation object such
319
+ as `reference_wrapper<T>` [[refwrap]], or some equivalent solution, can
320
+ be used. — *end note*]
321
 
322
  The invocations of element access functions in parallel algorithms
323
  invoked with an execution policy object of type
324
  `execution::sequenced_policy` all occur in the calling thread of
325
  execution.
 
331
  invoked with an execution policy object of type
332
  `execution::unsequenced_policy` are permitted to execute in an unordered
333
  fashion in the calling thread of execution, unsequenced with respect to
334
  one another in the calling thread of execution.
335
 
336
+ [*Note 4*: This means that multiple function object invocations can be
337
  interleaved on a single thread of execution, which overrides the usual
338
  guarantee from [[intro.execution]] that function executions do not
339
  overlap with one another. — *end note*]
340
 
341
  The behavior of a program is undefined if it invokes a
342
  vectorization-unsafe standard library function from user code called
343
+ from an `execution::unsequenced_policy` algorithm.
344
 
345
  [*Note 5*: Because `execution::unsequenced_policy` allows the execution
346
  of element access functions to be interleaved on a single thread of
347
  execution, blocking synchronization, including the use of mutexes, risks
348
  deadlock. — *end note*]
 
421
  with respect to one another within each thread of execution. These
422
  threads of execution are either the invoking thread of execution or
423
  threads of execution implicitly created by the library; the latter will
424
  provide weakly parallel forward progress guarantees.
425
 
426
+ [*Note 7*: This means that multiple function object invocations can be
427
  interleaved on a single thread of execution, which overrides the usual
428
  guarantee from [[intro.execution]] that function executions do not
429
  overlap with one another. — *end note*]
430
 
431
  The behavior of a program is undefined if it invokes a
432
  vectorization-unsafe standard library function from user code called
433
+ from an `execution::parallel_unsequenced_policy` algorithm.
434
 
435
  [*Note 8*: Because `execution::parallel_unsequenced_policy` allows the
436
  execution of element access functions to be interleaved on a single
437
  thread of execution, blocking synchronization, including the use of
438
  mutexes, risks deadlock. — *end note*]
 
500
  `is_execution_policy_v<remove_cvref_t<ExecutionPolicy>>` is `true`.
501
 
502
  ## Header `<algorithm>` synopsis <a id="algorithm.syn">[[algorithm.syn]]</a>
503
 
504
  ``` cpp
505
+ #include <initializer_list> // see [initializer.list.syn]
506
 
507
  namespace std {
508
  namespace ranges {
509
  // [algorithms.results], algorithm result types
510
  template<class I, class F>
 
525
  template<class T>
526
  struct min_max_result;
527
 
528
  template<class I>
529
  struct in_found_result;
530
+
531
+ template<class I, class T>
532
+ struct in_value_result;
533
+
534
+ template<class O, class T>
535
+ struct out_value_result;
536
  }
537
 
538
  // [alg.nonmodifying], non-modifying sequence operations
539
  // [alg.all.of], all of
540
  template<class InputIterator, class Predicate>
 
582
  template<input_range R, class Proj = identity,
583
  indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
584
  constexpr bool none_of(R&& r, Pred pred, Proj proj = {});
585
  }
586
 
587
+ // [alg.contains], contains
588
+ namespace ranges {
589
+ template<input_iterator I, sentinel_for<I> S, class T, class Proj = identity>
590
+ requires indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>
591
+ constexpr bool contains(I first, S last, const T& value, Proj proj = {});
592
+ template<input_range R, class T, class Proj = identity>
593
+ requires
594
+ indirect_binary_predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T*>
595
+ constexpr bool contains(R&& r, const T& value, Proj proj = {});
596
+
597
+ template<forward_iterator I1, sentinel_for<I1> S1,
598
+ forward_iterator I2, sentinel_for<I2> S2,
599
+ class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
600
+ requires indirectly_comparable<I1, I2, Pred, Proj1, Proj2>
601
+ constexpr bool contains_subrange(I1 first1, S1 last1, I2 first2, S2 last2,
602
+ Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
603
+ template<forward_range R1, forward_range R2,
604
+ class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
605
+ requires indirectly_comparable<iterator_t<R1>, iterator_t<R2>, Pred, Proj1, Proj2>
606
+ constexpr bool contains_subrange(R1&& r1, R2&& r2,
607
+ Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
608
+ }
609
+
610
  // [alg.foreach], for each
611
  template<class InputIterator, class Function>
612
  constexpr Function for_each(InputIterator first, InputIterator last, Function f);
613
  template<class ExecutionPolicy, class ForwardIterator, class Function>
614
  void for_each(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
 
690
  indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
691
  constexpr borrowed_iterator_t<R>
692
  find_if_not(R&& r, Pred pred, Proj proj = {});
693
  }
694
 
695
+ // [alg.find.last], find last
696
+ namespace ranges {
697
+ template<forward_iterator I, sentinel_for<I> S, class T, class Proj = identity>
698
+ requires indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>
699
+ constexpr subrange<I> find_last(I first, S last, const T& value, Proj proj = {});
700
+ template<forward_range R, class T, class Proj = identity>
701
+ requires
702
+ indirect_binary_predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T*>
703
+ constexpr borrowed_subrange_t<R> find_last(R&& r, const T& value, Proj proj = {});
704
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
705
+ indirect_unary_predicate<projected<I, Proj>> Pred>
706
+ constexpr subrange<I> find_last_if(I first, S last, Pred pred, Proj proj = {});
707
+ template<forward_range R, class Proj = identity,
708
+ indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
709
+ constexpr borrowed_subrange_t<R> find_last_if(R&& r, Pred pred, Proj proj = {});
710
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
711
+ indirect_unary_predicate<projected<I, Proj>> Pred>
712
+ constexpr subrange<I> find_last_if_not(I first, S last, Pred pred, Proj proj = {});
713
+ template<forward_range R, class Proj = identity,
714
+ indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
715
+ constexpr borrowed_subrange_t<R> find_last_if_not(R&& r, Pred pred, Proj proj = {});
716
+ }
717
+
718
  // [alg.find.end], find end
719
  template<class ForwardIterator1, class ForwardIterator2>
720
  constexpr ForwardIterator1
721
  find_end(ForwardIterator1 first1, ForwardIterator1 last1,
722
  ForwardIterator2 first2, ForwardIterator2 last2);
 
778
 
779
  namespace ranges {
780
  template<input_iterator I1, sentinel_for<I1> S1, forward_iterator I2, sentinel_for<I2> S2,
781
  class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
782
  requires indirectly_comparable<I1, I2, Pred, Proj1, Proj2>
783
+ constexpr I1 find_first_of(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {},
 
784
  Proj1 proj1 = {}, Proj2 proj2 = {});
785
  template<input_range R1, forward_range R2,
786
  class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
787
  requires indirectly_comparable<iterator_t<R1>, iterator_t<R2>, Pred, Proj1, Proj2>
788
  constexpr borrowed_iterator_t<R1>
789
+ find_first_of(R1&& r1, R2&& r2, Pred pred = {},
 
790
  Proj1 proj1 = {}, Proj2 proj2 = {});
791
  }
792
 
793
  // [alg.adjacent.find], adjacent find
794
  template<class ForwardIterator>
 
1041
  search_n(ForwardIterator first, ForwardIterator last,
1042
  Size count, const T& value);
1043
  template<class ForwardIterator, class Size, class T, class BinaryPredicate>
1044
  constexpr ForwardIterator
1045
  search_n(ForwardIterator first, ForwardIterator last,
1046
+ Size count, const T& value, BinaryPredicate pred);
 
1047
  template<class ExecutionPolicy, class ForwardIterator, class Size, class T>
1048
  ForwardIterator
1049
  search_n(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
1050
  ForwardIterator first, ForwardIterator last,
1051
  Size count, const T& value);
 
1074
 
1075
  template<class ForwardIterator, class Searcher>
1076
  constexpr ForwardIterator
1077
  search(ForwardIterator first, ForwardIterator last, const Searcher& searcher);
1078
 
1079
+ namespace ranges {
1080
+ // [alg.starts.with], starts with
1081
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
1082
+ class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
1083
+ requires indirectly_comparable<I1, I2, Pred, Proj1, Proj2>
1084
+ constexpr bool starts_with(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {},
1085
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1086
+ template<input_range R1, input_range R2, class Pred = ranges::equal_to,
1087
+ class Proj1 = identity, class Proj2 = identity>
1088
+ requires indirectly_comparable<iterator_t<R1>, iterator_t<R2>, Pred, Proj1, Proj2>
1089
+ constexpr bool starts_with(R1&& r1, R2&& r2, Pred pred = {},
1090
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1091
+
1092
+ // [alg.ends.with], ends with
1093
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
1094
+ class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
1095
+ requires (forward_iterator<I1> || sized_sentinel_for<S1, I1>) &&
1096
+ (forward_iterator<I2> || sized_sentinel_for<S2, I2>) &&
1097
+ indirectly_comparable<I1, I2, Pred, Proj1, Proj2>
1098
+ constexpr bool ends_with(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {},
1099
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1100
+ template<input_range R1, input_range R2, class Pred = ranges::equal_to,
1101
+ class Proj1 = identity, class Proj2 = identity>
1102
+ requires (forward_range<R1> || sized_range<R1>) &&
1103
+ (forward_range<R2> || sized_range<R2>) &&
1104
+ indirectly_comparable<iterator_t<R1>, iterator_t<R2>, Pred, Proj1, Proj2>
1105
+ constexpr bool ends_with(R1&& r1, R2&& r2, Pred pred = {},
1106
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1107
+
1108
+ // [alg.fold], fold
1109
+ template<class F>
1110
+ class flipped { // exposition only
1111
+ F f; // exposition only
1112
+
1113
+ public:
1114
+ template<class T, class U> requires invocable<F&, U, T>
1115
+ invoke_result_t<F&, U, T> operator()(T&&, U&&);
1116
+ };
1117
+
1118
+ template<class F, class T, class I, class U>
1119
+ concept indirectly-binary-left-foldable-impl = // exposition only
1120
+ movable<T> && movable<U> &&
1121
+ convertible_to<T, U> && invocable<F&, U, iter_reference_t<I>> &&
1122
+ assignable_from<U&, invoke_result_t<F&, U, iter_reference_t<I>>>;
1123
+
1124
+ template<class F, class T, class I>
1125
+ concept indirectly-binary-left-foldable = // exposition only
1126
+ copy_constructible<F> && indirectly_readable<I> &&
1127
+ invocable<F&, T, iter_reference_t<I>> &&
1128
+ convertible_to<invoke_result_t<F&, T, iter_reference_t<I>>,
1129
+ decay_t<invoke_result_t<F&, T, iter_reference_t<I>>>> &&
1130
+ indirectly-binary-left-foldable-impl<F, T, I,
1131
+ decay_t<invoke_result_t<F&, T, iter_reference_t<I>>>>;
1132
+
1133
+ template<class F, class T, class I>
1134
+ concept indirectly-binary-right-foldable = // exposition only
1135
+ indirectly-binary-left-foldable<flipped<F>, T, I>;
1136
+
1137
+ template<input_iterator I, sentinel_for<I> S, class T,
1138
+ indirectly-binary-left-foldable<T, I> F>
1139
+ constexpr auto fold_left(I first, S last, T init, F f);
1140
+
1141
+ template<input_range R, class T, indirectly-binary-left-foldable<T, iterator_t<R>> F>
1142
+ constexpr auto fold_left(R&& r, T init, F f);
1143
+
1144
+ template<input_iterator I, sentinel_for<I> S,
1145
+ indirectly-binary-left-foldable<iter_value_t<I>, I> F>
1146
+ requires constructible_from<iter_value_t<I>, iter_reference_t<I>>
1147
+ constexpr auto fold_left_first(I first, S last, F f);
1148
+
1149
+ template<input_range R, indirectly-binary-left-foldable<range_value_t<R>, iterator_t<R>> F>
1150
+ requires constructible_from<range_value_t<R>, range_reference_t<R>>
1151
+ constexpr auto fold_left_first(R&& r, F f);
1152
+
1153
+ template<bidirectional_iterator I, sentinel_for<I> S, class T,
1154
+ indirectly-binary-right-foldable<T, I> F>
1155
+ constexpr auto fold_right(I first, S last, T init, F f);
1156
+
1157
+ template<bidirectional_range R, class T,
1158
+ indirectly-binary-right-foldable<T, iterator_t<R>> F>
1159
+ constexpr auto fold_right(R&& r, T init, F f);
1160
+
1161
+ template<bidirectional_iterator I, sentinel_for<I> S,
1162
+ indirectly-binary-right-foldable<iter_value_t<I>, I> F>
1163
+ requires constructible_from<iter_value_t<I>, iter_reference_t<I>>
1164
+ constexpr auto fold_right_last(I first, S last, F f);
1165
+
1166
+ template<bidirectional_range R,
1167
+ indirectly-binary-right-foldable<range_value_t<R>, iterator_t<R>> F>
1168
+ requires constructible_from<range_value_t<R>, range_reference_t<R>>
1169
+ constexpr auto fold_right_last(R&& r, F f);
1170
+
1171
+ template<class I, class T>
1172
+ using fold_left_with_iter_result = in_value_result<I, T>;
1173
+ template<class I, class T>
1174
+ using fold_left_first_with_iter_result = in_value_result<I, T>;
1175
+
1176
+ template<input_iterator I, sentinel_for<I> S, class T,
1177
+ indirectly-binary-left-foldable<T, I> F>
1178
+ constexpr see below fold_left_with_iter(I first, S last, T init, F f);
1179
+
1180
+ template<input_range R, class T, indirectly-binary-left-foldable<T, iterator_t<R>> F>
1181
+ constexpr see below fold_left_with_iter(R&& r, T init, F f);
1182
+
1183
+ template<input_iterator I, sentinel_for<I> S,
1184
+ indirectly-binary-left-foldable<iter_value_t<I>, I> F>
1185
+ requires constructible_from<iter_value_t<I>, iter_reference_t<I>>
1186
+ constexpr see below fold_left_first_with_iter(I first, S last, F f);
1187
+
1188
+ template<input_range R,
1189
+ indirectly-binary-left-foldable<range_value_t<R>, iterator_t<R>> F>
1190
+ requires constructible_from<range_value_t<R>, range_reference_t<R>>
1191
+ constexpr see below fold_left_first_with_iter(R&& r, F f);
1192
+ }
1193
+
1194
  // [alg.modifying.operations], mutating sequence operations
1195
  // [alg.copy], copy
1196
  template<class InputIterator, class OutputIterator>
1197
  constexpr OutputIterator copy(InputIterator first, InputIterator last,
1198
  OutputIterator result);
 
1836
  template<class ExecutionPolicy, class ForwardIterator>
1837
  ForwardIterator
1838
  shift_left(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
1839
  ForwardIterator first, ForwardIterator last,
1840
  typename iterator_traits<ForwardIterator>::difference_type n);
1841
+
1842
+ namespace ranges {
1843
+ template<permutable I, sentinel_for<I> S>
1844
+ constexpr subrange<I> shift_left(I first, S last, iter_difference_t<I> n);
1845
+ template<forward_range R>
1846
+ requires permutable<iterator_t<R>>
1847
+ constexpr borrowed_subrange_t<R> shift_left(R&& r, range_difference_t<R> n);
1848
+ }
1849
+
1850
  template<class ForwardIterator>
1851
  constexpr ForwardIterator
1852
  shift_right(ForwardIterator first, ForwardIterator last,
1853
  typename iterator_traits<ForwardIterator>::difference_type n);
1854
  template<class ExecutionPolicy, class ForwardIterator>
1855
  ForwardIterator
1856
  shift_right(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
1857
  ForwardIterator first, ForwardIterator last,
1858
  typename iterator_traits<ForwardIterator>::difference_type n);
1859
 
1860
+ namespace ranges {
1861
+ template<permutable I, sentinel_for<I> S>
1862
+ constexpr subrange<I> shift_right(I first, S last, iter_difference_t<I> n);
1863
+ template<forward_range R>
1864
+ requires permutable<iterator_t<R>>
1865
+ constexpr borrowed_subrange_t<R> shift_right(R&& r, range_difference_t<R> n);
1866
+ }
1867
+
1868
  // [alg.sorting], sorting and related operations
1869
  // [alg.sort], sorting
1870
  template<class RandomAccessIterator>
1871
  constexpr void sort(RandomAccessIterator first, RandomAccessIterator last);
1872
  template<class RandomAccessIterator, class Compare>
 
1915
  borrowed_iterator_t<R>
1916
  stable_sort(R&& r, Comp comp = {}, Proj proj = {});
1917
  }
1918
 
1919
  template<class RandomAccessIterator>
1920
+ constexpr void partial_sort(RandomAccessIterator first, RandomAccessIterator middle,
 
1921
  RandomAccessIterator last);
1922
  template<class RandomAccessIterator, class Compare>
1923
+ constexpr void partial_sort(RandomAccessIterator first, RandomAccessIterator middle,
 
1924
  RandomAccessIterator last, Compare comp);
1925
  template<class ExecutionPolicy, class RandomAccessIterator>
1926
  void partial_sort(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
1927
+ RandomAccessIterator first, RandomAccessIterator middle,
 
1928
  RandomAccessIterator last);
1929
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
1930
  void partial_sort(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
1931
+ RandomAccessIterator first, RandomAccessIterator middle,
 
1932
  RandomAccessIterator last, Compare comp);
1933
 
1934
  namespace ranges {
1935
  template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
1936
  class Proj = identity>
 
3074
  requires convertible_to<I, I2>
3075
  constexpr operator in_found_result<I2>() && {
3076
  return {std::move(in), found};
3077
  }
3078
  };
3079
+
3080
+ template<class I, class T>
3081
+ struct in_value_result {
3082
+ [[no_unique_address]] I in;
3083
+ [[no_unique_address]] T value;
3084
+
3085
+ template<class I2, class T2>
3086
+ requires convertible_to<const I&, I2> && convertible_to<const T&, T2>
3087
+ constexpr operator in_value_result<I2, T2>() const & {
3088
+ return {in, value};
3089
+ }
3090
+
3091
+ template<class I2, class T2>
3092
+ requires convertible_to<I, I2> && convertible_to<T, T2>
3093
+ constexpr operator in_value_result<I2, T2>() && {
3094
+ return {std::move(in), std::move(value)};
3095
+ }
3096
+ };
3097
+
3098
+ template<class O, class T>
3099
+ struct out_value_result {
3100
+ [[no_unique_address]] O out;
3101
+ [[no_unique_address]] T value;
3102
+
3103
+ template<class O2, class T2>
3104
+ requires convertible_to<const O&, O2> && convertible_to<const T&, T2>
3105
+ constexpr operator out_value_result<O2, T2>() const & {
3106
+ return {out, value};
3107
+ }
3108
+
3109
+ template<class O2, class T2>
3110
+ requires convertible_to<O, O2> && convertible_to<T, T2>
3111
+ constexpr operator out_value_result<O2, T2>() && {
3112
+ return {std::move(out), std::move(value)};
3113
+ }
3114
+ };
3115
  }
3116
  ```
3117
 
3118
  ## Non-modifying sequence operations <a id="alg.nonmodifying">[[alg.nonmodifying]]</a>
3119
 
 
3202
  \[`first`, `last`), and `true` otherwise.
3203
 
3204
  *Complexity:* At most `last - first` applications of the predicate and
3205
  any projection.
3206
 
3207
+ ### Contains <a id="alg.contains">[[alg.contains]]</a>
3208
+
3209
+ ``` cpp
3210
+ template<input_iterator I, sentinel_for<I> S, class T, class Proj = identity>
3211
+ requires indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>
3212
+ constexpr bool ranges::contains(I first, S last, const T& value, Proj proj = {});
3213
+ template<input_range R, class T, class Proj = identity>
3214
+ requires indirect_binary_predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T*>
3215
+ constexpr bool ranges::contains(R&& r, const T& value, Proj proj = {});
3216
+ ```
3217
+
3218
+ *Returns:* `ranges::find(std::move(first), last, value, proj) != last`.
3219
+
3220
+ ``` cpp
3221
+ template<forward_iterator I1, sentinel_for<I1> S1,
3222
+ forward_iterator I2, sentinel_for<I2> S2,
3223
+ class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
3224
+ requires indirectly_comparable<I1, I2, Pred, Proj1, Proj2>
3225
+ constexpr bool ranges::contains_subrange(I1 first1, S1 last1, I2 first2, S2 last2,
3226
+ Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
3227
+ template<forward_range R1, forward_range R2,
3228
+ class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
3229
+ requires indirectly_comparable<iterator_t<R1>, iterator_t<R2>, Pred, Proj1, Proj2>
3230
+ constexpr bool ranges::contains_subrange(R1&& r1, R2&& r2, Pred pred = {},
3231
+ Proj1 proj1 = {}, Proj2 proj2 = {});
3232
+ ```
3233
+
3234
+ *Returns:*
3235
+ `first2 == last2 || !ranges::search(first1, last1, first2, last2, pred, proj1, proj2).empty()`.
3236
+
3237
  ### For each <a id="alg.foreach">[[alg.foreach]]</a>
3238
 
3239
  ``` cpp
3240
  template<class InputIterator, class Function>
3241
  constexpr Function for_each(InputIterator first, InputIterator last, Function f);
 
3250
  *Effects:* Applies `f` to the result of dereferencing every iterator in
3251
  the range \[`first`, `last`), starting from `first` and proceeding to
3252
  `last - 1`.
3253
 
3254
  [*Note 2*: If the type of `first` meets the requirements of a mutable
3255
+ iterator, `f` can apply non-constant functions through the dereferenced
3256
  iterator. — *end note*]
3257
 
3258
  *Returns:* `f`.
3259
 
3260
  *Complexity:* Applies `f` exactly `last - first` times.
 
3273
 
3274
  *Effects:* Applies `f` to the result of dereferencing every iterator in
3275
  the range \[`first`, `last`).
3276
 
3277
  [*Note 3*: If the type of `first` meets the requirements of a mutable
3278
+ iterator, `f` can apply non-constant functions through the dereferenced
3279
  iterator. — *end note*]
3280
 
3281
  *Complexity:* Applies `f` exactly `last - first` times.
3282
 
3283
  *Remarks:* If `f` returns a result, the result is ignored.
3284
  Implementations do not have the freedom granted under
3285
  [[algorithms.parallel.exec]] to make arbitrary copies of elements from
3286
  the input sequence.
3287
 
3288
  [*Note 4*: Does not return a copy of its `Function` parameter, since
3289
+ parallelization often does not permit efficient state
3290
  accumulation. — *end note*]
3291
 
3292
  ``` cpp
3293
  template<input_iterator I, sentinel_for<I> S, class Proj = identity,
3294
  indirectly_unary_invocable<projected<I, Proj>> Fun>
 
3303
  *Effects:* Calls `invoke(f, invoke(proj, *i))` for every iterator `i` in
3304
  the range \[`first`, `last`), starting from `first` and proceeding to
3305
  `last - 1`.
3306
 
3307
  [*Note 5*: If the result of `invoke(proj, *i)` is a mutable reference,
3308
+ `f` can apply non-constant functions. — *end note*]
3309
 
3310
  *Returns:* `{last, std::move(f)}`.
3311
 
3312
  *Complexity:* Applies `f` and `proj` exactly `last - first` times.
3313
 
 
3320
  template<class InputIterator, class Size, class Function>
3321
  constexpr InputIterator for_each_n(InputIterator first, Size n, Function f);
3322
  ```
3323
 
3324
  *Mandates:* The type `Size` is convertible to an integral
3325
+ type [[conv.integral]], [[class.conv]].
3326
 
3327
+ *Preconditions:* `n >= 0` is `true`. `Function` meets the
3328
+ *Cpp17MoveConstructible* requirements.
3329
 
3330
  [*Note 7*: `Function` need not meet the requirements of
3331
  *Cpp17CopyConstructible*. — *end note*]
3332
 
 
 
3333
  *Effects:* Applies `f` to the result of dereferencing every iterator in
3334
  the range \[`first`, `first + n`) in order.
3335
 
3336
  [*Note 8*: If the type of `first` meets the requirements of a mutable
3337
+ iterator, `f` can apply non-constant functions through the dereferenced
3338
  iterator. — *end note*]
3339
 
3340
  *Returns:* `first + n`.
3341
 
3342
  *Remarks:* If `f` returns a result, the result is ignored.
 
3346
  ForwardIterator for_each_n(ExecutionPolicy&& exec, ForwardIterator first, Size n,
3347
  Function f);
3348
  ```
3349
 
3350
  *Mandates:* The type `Size` is convertible to an integral
3351
+ type [[conv.integral]], [[class.conv]].
3352
 
3353
+ *Preconditions:* `n >= 0` is `true`. `Function` meets the
3354
+ *Cpp17CopyConstructible* requirements.
 
 
3355
 
3356
  *Effects:* Applies `f` to the result of dereferencing every iterator in
3357
  the range \[`first`, `first + n`).
3358
 
3359
  [*Note 9*: If the type of `first` meets the requirements of a mutable
3360
+ iterator, `f` can apply non-constant functions through the dereferenced
3361
  iterator. — *end note*]
3362
 
3363
  *Returns:* `first + n`.
3364
 
3365
  *Remarks:* If `f` returns a result, the result is ignored.
 
3378
 
3379
  *Effects:* Calls `invoke(f, invoke(proj, *i))` for every iterator `i` in
3380
  the range \[`first`, `first + n`) in order.
3381
 
3382
  [*Note 10*: If the result of `invoke(proj, *i)` is a mutable reference,
3383
+ `f` can apply non-constant functions. — *end note*]
3384
 
3385
  *Returns:* `{first + n, std::move(f)}`.
3386
 
3387
  *Remarks:* If `f` returns a result, the result is ignored.
3388
 
 
3450
  which E is `true`. Returns `last` if no such iterator is found.
3451
 
3452
  *Complexity:* At most `last - first` applications of the corresponding
3453
  predicate and any projection.
3454
 
3455
+ ### Find last <a id="alg.find.last">[[alg.find.last]]</a>
3456
+
3457
+ ``` cpp
3458
+ template<forward_iterator I, sentinel_for<I> S, class T, class Proj = identity>
3459
+ requires indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>
3460
+ constexpr subrange<I> ranges::find_last(I first, S last, const T& value, Proj proj = {});
3461
+ template<forward_range R, class T, class Proj = identity>
3462
+ requires indirect_binary_predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T*>
3463
+ constexpr borrowed_subrange_t<R> ranges::find_last(R&& r, const T& value, Proj proj = {});
3464
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
3465
+ indirect_unary_predicate<projected<I, Proj>> Pred>
3466
+ constexpr subrange<I> ranges::find_last_if(I first, S last, Pred pred, Proj proj = {});
3467
+ template<forward_range R, class Proj = identity,
3468
+ indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
3469
+ constexpr borrowed_subrange_t<R> ranges::find_last_if(R&& r, Pred pred, Proj proj = {});
3470
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
3471
+ indirect_unary_predicate<projected<I, Proj>> Pred>
3472
+ constexpr subrange<I> ranges::find_last_if_not(I first, S last, Pred pred, Proj proj = {});
3473
+ template<forward_range R, class Proj = identity,
3474
+ indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
3475
+ constexpr borrowed_subrange_t<R> ranges::find_last_if_not(R&& r, Pred pred, Proj proj = {});
3476
+ ```
3477
+
3478
+ Let E be:
3479
+
3480
+ - `bool(invoke(proj, *i) == value)` for `ranges::find_last`;
3481
+ - `bool(invoke(pred, invoke(proj, *i)))` for `ranges::find_last_if`;
3482
+ - `bool(!invoke(pred, invoke(proj, *i)))` for
3483
+ `ranges::find_last_if_not`.
3484
+
3485
+ *Returns:* Let `i` be the last iterator in the range \[`first`, `last`)
3486
+ for which E is `true`. Returns `{i, last}`, or `{last, last}` if no such
3487
+ iterator is found.
3488
+
3489
+ *Complexity:* At most `last - first` applications of the corresponding
3490
+ predicate and projection.
3491
+
3492
  ### Find end <a id="alg.find.end">[[alg.find.end]]</a>
3493
 
3494
  ``` cpp
3495
  template<class ForwardIterator1, class ForwardIterator2>
3496
  constexpr ForwardIterator1
 
3867
  - `invoke(pred, invoke(proj1, *i), invoke(proj2, *(first2 + (i - first1))))`
3868
  for the overloads with parameter `proj1`.
3869
 
3870
  *Returns:* If `last1 - first1 != last2 - first2`, return `false`.
3871
  Otherwise return `true` if E holds for every iterator `i` in the range
3872
+ \[`first1`, `last1`). Otherwise, returns `false`.
3873
 
3874
+ *Complexity:* If
3875
 
3876
+ - the types of `first1`, `last1`, `first2`, and `last2` meet the
3877
+ *Cpp17RandomAccessIterator* requirements [[random.access.iterators]]
3878
+ and `last1 - first1 != last2 - first2` for the overloads in namespace
3879
+ `std`;
3880
+ - the types of `first1`, `last1`, `first2`, and `last2` pairwise model
3881
+ `sized_sentinel_for` [[iterator.concept.sizedsentinel]] and
3882
+ `last1 - first1 != last2 - first2` for the first overload in namespace
3883
+ `ranges`,
3884
+ - `R1` and `R2` each model `sized_range` and
3885
+ `ranges::distance(r1) != ranges::distance(r2)` for the second overload
3886
+ in namespace `ranges`,
3887
 
3888
+ then no applications of the corresponding predicate and each projection;
3889
+ otherwise,
3890
 
3891
  - For the overloads with no `ExecutionPolicy`, at most
3892
  min(`last1 - first1`, `last2 - first2`) applications of the
3893
  corresponding predicate and any projections.
3894
  - For the overloads with an `ExecutionPolicy`, 𝑂(min(`last1 - first1`,
 
3912
  constexpr bool is_permutation(ForwardIterator1 first1, ForwardIterator1 last1,
3913
  ForwardIterator2 first2, ForwardIterator2 last2,
3914
  BinaryPredicate pred);
3915
  ```
3916
 
3917
+ Let `last2` be `first2 + (last1 - first1)` for the overloads with no
3918
+ parameter named `last2`, and let `pred` be `equal_to{}` for the
3919
+ overloads with no parameter `pred`.
3920
+
3921
  *Mandates:* `ForwardIterator1` and `ForwardIterator2` have the same
3922
  value type.
3923
 
3924
  *Preconditions:* The comparison function is an equivalence relation.
3925
 
 
 
 
3926
  *Returns:* If `last1 - first1 != last2 - first2`, return `false`.
3927
  Otherwise return `true` if there exists a permutation of the elements in
3928
+ the range \[`first2`, `last2`), beginning with `ForwardIterator2 begin`,
3929
+ such that `equal(first1, last1, begin, pred)` returns `true`; otherwise,
3930
+ returns `false`.
 
3931
 
3932
  *Complexity:* No applications of the corresponding predicate if
3933
  `ForwardIterator1` and `ForwardIterator2` meet the requirements of
3934
  random access iterators and `last1 - first1 != last2 - first2`.
3935
  Otherwise, exactly `last1 - first1` applications of the corresponding
3936
+ predicate if `equal(first1, last1, first2, last2, pred)` would return
3937
+ `true`; otherwise, at worst 𝑂(N^2), where N has the value
3938
+ `last1 - first1`.
 
 
3939
 
3940
  ``` cpp
3941
  template<forward_iterator I1, sentinel_for<I1> S1, forward_iterator I2,
3942
  sentinel_for<I2> S2, class Proj1 = identity, class Proj2 = identity,
3943
  indirect_equivalence_relation<projected<I1, Proj1>,
 
3960
  returns `true`; otherwise, returns `false`.
3961
 
3962
  *Complexity:* No applications of the corresponding predicate and
3963
  projections if:
3964
 
3965
+ - for the first overload,
3966
  - `S1` and `I1` model `sized_sentinel_for<S1, I1>`,
3967
  - `S2` and `I2` model `sized_sentinel_for<S2, I2>`, and
3968
+ - `last1 - first1 != last2 - first2`;
3969
+ - for the second overload, `R1` and `R2` each model `sized_range`, and
3970
+ `ranges::distance(r1) != ranges::distance(r2)`.
3971
 
3972
  Otherwise, exactly `last1 - first1` applications of the corresponding
3973
  predicate and projections if
3974
  `ranges::equal(first1, last1, first2, last2, pred, proj1, proj2)` would
3975
  return `true`; otherwise, at worst 𝑂(N^2), where N has the value
 
4069
  Size count, const T& value,
4070
  BinaryPredicate pred);
4071
  ```
4072
 
4073
  *Mandates:* The type `Size` is convertible to an integral
4074
+ type [[conv.integral]], [[class.conv]].
4075
 
4076
  *Returns:* The first iterator `i` in the range \[`first`, `last-count`)
4077
  such that for every non-negative integer `n` less than `count` the
4078
  following corresponding conditions hold:
4079
+ `*(i + n) == value, pred(*(i + n), value) != false`. Returns `last` if
4080
+ no such iterator is found.
4081
 
4082
  *Complexity:* At most `last - first` applications of the corresponding
4083
  predicate.
4084
 
4085
  ``` cpp
 
4115
  *Effects:* Equivalent to: `return searcher(first, last).first;`
4116
 
4117
  *Remarks:* `Searcher` need not meet the *Cpp17CopyConstructible*
4118
  requirements.
4119
 
4120
+ ### Starts with <a id="alg.starts.with">[[alg.starts.with]]</a>
4121
+
4122
+ ``` cpp
4123
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
4124
+ class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
4125
+ requires indirectly_comparable<I1, I2, Pred, Proj1, Proj2>
4126
+ constexpr bool ranges::starts_with(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {},
4127
+ Proj1 proj1 = {}, Proj2 proj2 = {});
4128
+ template<input_range R1, input_range R2, class Pred = ranges::equal_to, class Proj1 = identity,
4129
+ class Proj2 = identity>
4130
+ requires indirectly_comparable<iterator_t<R1>, iterator_t<R2>, Pred, Proj1, Proj2>
4131
+ constexpr bool ranges::starts_with(R1&& r1, R2&& r2, Pred pred = {},
4132
+ Proj1 proj1 = {}, Proj2 proj2 = {});
4133
+ ```
4134
+
4135
+ *Returns:*
4136
+
4137
+ ``` cpp
4138
+ ranges::mismatch(std::move(first1), last1, std::move(first2), last2,
4139
+ pred, proj1, proj2).in2 == last2
4140
+ ```
4141
+
4142
+ ### Ends with <a id="alg.ends.with">[[alg.ends.with]]</a>
4143
+
4144
+ ``` cpp
4145
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
4146
+ class Pred = ranges::equal_to, class Proj1 = identity, class Proj2 = identity>
4147
+ requires (forward_iterator<I1> || sized_sentinel_for<S1, I1>) &&
4148
+ (forward_iterator<I2> || sized_sentinel_for<S2, I2>) &&
4149
+ indirectly_comparable<I1, I2, Pred, Proj1, Proj2>
4150
+ constexpr bool ranges::ends_with(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {},
4151
+ Proj1 proj1 = {}, Proj2 proj2 = {});
4152
+ ```
4153
+
4154
+ Let `N1` be `last1 - first1` and `N2` be `last2 - first2`.
4155
+
4156
+ *Returns:* `false` if `N1` < `N2`, otherwise
4157
+
4158
+ ``` cpp
4159
+ ranges::equal(std::move(first1) + (N1 - N2), last1, std::move(first2), last2,
4160
+ pred, proj1, proj2)
4161
+ ```
4162
+
4163
+ ``` cpp
4164
+ template<input_range R1, input_range R2, class Pred = ranges::equal_to, class Proj1 = identity,
4165
+ class Proj2 = identity>
4166
+ requires (forward_range<R1> || sized_range<R1>) &&
4167
+ (forward_range<R2> || sized_range<R2>) &&
4168
+ indirectly_comparable<iterator_t<R1>, iterator_t<R2>, Pred, Proj1, Proj2>
4169
+ constexpr bool ranges::ends_with(R1&& r1, R2&& r2, Pred pred = {},
4170
+ Proj1 proj1 = {}, Proj2 proj2 = {});
4171
+ ```
4172
+
4173
+ Let `N1` be `ranges::distance(r1)` and `N2` be `ranges::distance(r2)`.
4174
+
4175
+ *Returns:* `false` if `N1` < `N2`, otherwise
4176
+
4177
+ ``` cpp
4178
+ ranges::equal(ranges::drop_view(ranges::ref_view(r1), N1 - N2), r2, pred, proj1, proj2)
4179
+ ```
4180
+
4181
+ ### Fold <a id="alg.fold">[[alg.fold]]</a>
4182
+
4183
+ ``` cpp
4184
+ template<input_iterator I, sentinel_for<I> S, class T, indirectly-binary-left-foldable<T, I> F>
4185
+ constexpr auto ranges::fold_left(I first, S last, T init, F f);
4186
+ template<input_range R, class T, indirectly-binary-left-foldable<T, iterator_t<R>> F>
4187
+ constexpr auto ranges::fold_left(R&& r, T init, F f);
4188
+ ```
4189
+
4190
+ *Returns:*
4191
+
4192
+ ``` cpp
4193
+ ranges::fold_left_with_iter(std::move(first), last, std::move(init), f).value
4194
+ ```
4195
+
4196
+ ``` cpp
4197
+ template<input_iterator I, sentinel_for<I> S,
4198
+ indirectly-binary-left-foldable<iter_value_t<I>, I> F>
4199
+ requires constructible_from<iter_value_t<I>, iter_reference_t<I>>
4200
+ constexpr auto ranges::fold_left_first(I first, S last, F f);
4201
+ template<input_range R, indirectly-binary-left-foldable<range_value_t<R>, iterator_t<R>> F>
4202
+ requires constructible_from<range_value_t<R>, range_reference_t<R>>
4203
+ constexpr auto ranges::fold_left_first(R&& r, F f);
4204
+ ```
4205
+
4206
+ *Returns:*
4207
+
4208
+ ``` cpp
4209
+ ranges::fold_left_first_with_iter(std::move(first), last, f).value
4210
+ ```
4211
+
4212
+ ``` cpp
4213
+ template<bidirectional_iterator I, sentinel_for<I> S, class T,
4214
+ indirectly-binary-right-foldable<T, I> F>
4215
+ constexpr auto ranges::fold_right(I first, S last, T init, F f);
4216
+ template<bidirectional_range R, class T,
4217
+ indirectly-binary-right-foldable<T, iterator_t<R>> F>
4218
+ constexpr auto ranges::fold_right(R&& r, T init, F f);
4219
+ ```
4220
+
4221
+ *Effects:* Equivalent to:
4222
+
4223
+ ``` cpp
4224
+ using U = decay_t<invoke_result_t<F&, iter_reference_t<I>, T>>;
4225
+ if (first == last)
4226
+ return U(std::move(init));
4227
+ I tail = ranges::next(first, last);
4228
+ U accum = invoke(f, *--tail, std::move(init));
4229
+ while (first != tail)
4230
+ accum = invoke(f, *--tail, std::move(accum));
4231
+ return accum;
4232
+ ```
4233
+
4234
+ ``` cpp
4235
+ template<bidirectional_iterator I, sentinel_for<I> S,
4236
+ indirectly-binary-right-foldable<iter_value_t<I>, I> F>
4237
+ requires constructible_from<iter_value_t<I>, iter_reference_t<I>>
4238
+ constexpr auto ranges::fold_right_last(I first, S last, F f);
4239
+ template<bidirectional_range R,
4240
+ indirectly-binary-right-foldable<range_value_t<R>, iterator_t<R>> F>
4241
+ requires constructible_from<range_value_t<R>, range_reference_t<R>>
4242
+ constexpr auto ranges::fold_right_last(R&& r, F f);
4243
+ ```
4244
+
4245
+ Let `U` be
4246
+ `decltype(ranges::fold_right(first, last, iter_value_t<I>(*first), f))`.
4247
+
4248
+ *Effects:* Equivalent to:
4249
+
4250
+ ``` cpp
4251
+ if (first == last)
4252
+ return optional<U>();
4253
+ I tail = ranges::prev(ranges::next(first, std::move(last)));
4254
+ return optional<U>(in_place,
4255
+ ranges::fold_right(std::move(first), tail, iter_value_t<I>(*tail), std::move(f)));
4256
+ ```
4257
+
4258
+ ``` cpp
4259
+ template<input_iterator I, sentinel_for<I> S, class T,
4260
+ indirectly-binary-left-foldable<T, I> F>
4261
+ constexpr see below ranges::fold_left_with_iter(I first, S last, T init, F f);
4262
+ template<input_range R, class T, indirectly-binary-left-foldable<T, iterator_t<R>> F>
4263
+ constexpr see below ranges::fold_left_with_iter(R&& r, T init, F f);
4264
+ ```
4265
+
4266
+ Let `U` be `decay_t<invoke_result_t<F&, T, iter_reference_t<I>>>`.
4267
+
4268
+ *Effects:* Equivalent to:
4269
+
4270
+ ``` cpp
4271
+ if (first == last)
4272
+ return {std::move(first), U(std::move(init))};
4273
+ U accum = invoke(f, std::move(init), *first);
4274
+ for (++first; first != last; ++first)
4275
+ accum = invoke(f, std::move(accum), *first);
4276
+ return {std::move(first), std::move(accum)};
4277
+ ```
4278
+
4279
+ *Remarks:* The return type is `fold_left_with_iter_result<I, U>` for the
4280
+ first overload and
4281
+ `fold_left_with_iter_result<borrowed_iterator_t<R>, U>` for the second
4282
+ overload.
4283
+
4284
+ ``` cpp
4285
+ template<input_iterator I, sentinel_for<I> S,
4286
+ indirectly-binary-left-foldable<iter_value_t<I>, I> F>
4287
+ requires constructible_from<iter_value_t<I>, iter_reference_t<I>>
4288
+ constexpr see below ranges::fold_left_first_with_iter(I first, S last, F f);
4289
+ template<input_range R, indirectly-binary-left-foldable<range_value_t<R>, iterator_t<R>> F>
4290
+ requires constructible_from<range_value_t<R>, range_reference_t<R>>
4291
+ constexpr see below ranges::fold_left_first_with_iter(R&& r, F f);
4292
+ ```
4293
+
4294
+ Let `U` be
4295
+
4296
+ ``` cpp
4297
+ decltype(ranges::fold_left(std::move(first), last, iter_value_t<I>(*first), f))
4298
+ ```
4299
+
4300
+ *Effects:* Equivalent to:
4301
+
4302
+ ``` cpp
4303
+ if (first == last)
4304
+ return {std::move(first), optional<U>()};
4305
+ optional<U> init(in_place, *first);
4306
+ for (++first; first != last; ++first)
4307
+ *init = invoke(f, std::move(*init), *first);
4308
+ return {std::move(first), std::move(init)};
4309
+ ```
4310
+
4311
+ *Remarks:* The return type is
4312
+ `fold_left_first_with_iter_result<I, optional<U>>` for the first
4313
+ overload and
4314
+ `fold_left_first_with_iter_result<borrowed_iterator_t<R>, optional<U>>`
4315
+ for the second overload.
4316
+
4317
  ## Mutating sequence operations <a id="alg.modifying.operations">[[alg.modifying.operations]]</a>
4318
 
4319
  ### Copy <a id="alg.copy">[[alg.copy]]</a>
4320
 
4321
  ``` cpp
 
4381
  ```
4382
 
4383
  Let N be max(0, `n`).
4384
 
4385
  *Mandates:* The type `Size` is convertible to an integral
4386
+ type [[conv.integral]], [[class.conv]].
4387
 
4388
  *Effects:* For each non-negative integer i < N, performs
4389
+ `*(result + `i`) = *(first + `i`)`.
4390
 
4391
  *Returns:*
4392
 
4393
  - `result + `N for the overloads in namespace `std`.
4394
  - `{first + `N`, result + `N`}` for the overload in namespace `ranges`.
 
4427
  which the condition E holds.
4428
 
4429
  *Preconditions:* The ranges \[`first`, `last`) and \[`result`,
4430
  `result + (last - first)`) do not overlap.
4431
 
4432
+ [*Note 1*: For the overload with an `ExecutionPolicy`, there might be a
4433
  performance cost if `iterator_traits<ForwardIterator1>::value_type` is
4434
  not *Cpp17MoveConstructible*
4435
  ([[cpp17.moveconstructible]]). — *end note*]
4436
 
4437
  *Effects:* Copies all of the elements referred to by the iterator `i` in
 
4468
 
4469
  *Preconditions:* `result` is not in the range (`first`, `last`).
4470
 
4471
  *Effects:* Copies elements in the range \[`first`, `last`) into the
4472
  range \[`result - `N, `result`) starting from `last - 1` and proceeding
4473
+ to `first`.[^2]
4474
+
4475
+ For each positive integer n ≤ N, performs
4476
  `*(result - `n`) = *(last - `n`)`.
4477
 
4478
  *Returns:*
4479
 
4480
  - `result - `N for the overload in namespace `std`.
 
4567
 
4568
  *Preconditions:* `result` is not in the range (`first`, `last`).
4569
 
4570
  *Effects:* Moves elements in the range \[`first`, `last`) into the range
4571
  \[`result - `N, `result`) starting from `last - 1` and proceeding to
4572
+ `first`.[^3]
4573
+
4574
+ For each positive integer n ≤ N, performs `*(result - `n`) = `E.
4575
 
4576
  *Returns:*
4577
 
4578
  - `result - `N for the overload in namespace `std`.
4579
  - `{last, result - `N`}` for the overloads in namespace `ranges`.
 
4891
  constexpr OutputIterator fill_n(OutputIterator first, Size n, const T& value);
4892
  template<class ExecutionPolicy, class ForwardIterator, class Size, class T>
4893
  ForwardIterator fill_n(ExecutionPolicy&& exec,
4894
  ForwardIterator first, Size n, const T& value);
4895
 
 
4896
  template<class T, output_iterator<const T&> O, sentinel_for<O> S>
4897
  constexpr O ranges::fill(O first, S last, const T& value);
4898
  template<class T, output_range<const T&> R>
4899
  constexpr borrowed_iterator_t<R> ranges::fill(R&& r, const T& value);
4900
  template<class T, output_iterator<const T&> O>
 
4904
  Let N be max(0, `n`) for the `fill_n` algorithms, and `last - first` for
4905
  the `fill` algorithms.
4906
 
4907
  *Mandates:* The expression `value` is
4908
  writable [[iterator.requirements.general]] to the output iterator. The
4909
+ type `Size` is convertible to an integral
4910
+ type [[conv.integral]], [[class.conv]].
4911
 
4912
  *Effects:* Assigns `value` through all the iterators in the range
4913
  \[`first`, `first + `N).
4914
 
4915
  *Returns:* `first + `N.
 
4946
 
4947
  Let N be max(0, `n`) for the `generate_n` algorithms, and `last - first`
4948
  for the `generate` algorithms.
4949
 
4950
  *Mandates:* `Size` is convertible to an integral
4951
+ type [[conv.integral]], [[class.conv]].
4952
 
4953
  *Effects:* Assigns the result of successive evaluations of `gen()`
4954
  through each iterator in the range \[`first`, `first + `N).
4955
 
4956
  *Returns:* `first + `N.
 
5011
  *Returns:* Let j be the end of the resulting range. Returns:
5012
 
5013
  - j for the overloads in namespace `std`.
5014
  - `{`j`, last}` for the overloads in namespace `ranges`.
5015
 
 
 
5016
  *Complexity:* Exactly `last - first` applications of the corresponding
5017
  predicate and any projection.
5018
 
5019
+ *Remarks:* Stable [[algorithm.stable]].
5020
+
5021
  [*Note 1*: Each element in the range \[`ret`, `last`), where `ret` is
5022
  the returned value, has a valid but unspecified state, because the
5023
  algorithms can eliminate elements by moving from elements that were
5024
  originally in that range. — *end note*]
5025
 
 
5083
  `result`.
5084
 
5085
  *Preconditions:* The ranges \[`first`, `last`) and \[`result`,
5086
  `result + (last - first)`) do not overlap.
5087
 
5088
+ [*Note 2*: For the overloads with an `ExecutionPolicy`, there might be
5089
+ a performance cost if `iterator_traits<ForwardIterator1>::value_type`
5090
+ does not meet the *Cpp17MoveConstructible*
5091
+ ([[cpp17.moveconstructible]]) requirements. — *end note*]
5092
 
5093
  *Effects:* Copies all the elements referred to by the iterator `i` in
5094
  the range \[`first`, `last`) for which E is `false`.
5095
 
5096
  *Returns:*
 
5135
 
5136
  - `bool(pred(*(i - 1), *i))` for the overloads in namespace `std`;
5137
  - `bool(invoke(comp, invoke(proj, *(i - 1)), invoke(proj, *i)))` for the
5138
  overloads in namespace `ranges`.
5139
 
5140
+ *Preconditions:* For the overloads in namespace `std`, `pred` is an
5141
  equivalence relation and the type of `*first` meets the
5142
  *Cpp17MoveAssignable* requirements ([[cpp17.moveassignable]]).
5143
 
5144
  *Effects:* For a nonempty range, eliminates all but the first element
5145
  from every consecutive group of equivalent elements referred to by the
 
5210
  - The ranges \[`first`, `last`) and \[`result`, `result+(last-first)`)
5211
  do not overlap.
5212
  - For the overloads in namespace `std`:
5213
  - The comparison function is an equivalence relation.
5214
  - For the overloads with no `ExecutionPolicy`, let `T` be the value
5215
+ type of `InputIterator`. If `InputIterator` models
5216
+ `forward_iterator` [[iterator.concept.forward]], then there are no
5217
+ additional requirements for `T`. Otherwise, if `OutputIterator`
5218
+ meets the *Cpp17ForwardIterator* requirements and its value type is
5219
+ the same as `T`, then `T` meets the *Cpp17CopyAssignable*
5220
  ([[cpp17.copyassignable]]) requirements. Otherwise, `T` meets both
5221
  the *Cpp17CopyConstructible* ([[cpp17.copyconstructible]]) and
5222
  *Cpp17CopyAssignable* requirements. \[*Note 1*: For the overloads
5223
+ with an `ExecutionPolicy`, there might be a performance cost if the
5224
  value type of `ForwardIterator1` does not meet both the
5225
  *Cpp17CopyConstructible* and *Cpp17CopyAssignable*
5226
  requirements. — *end note*]
5227
 
5228
  *Effects:* Copies only the first element from every consecutive group of
 
5394
  ```
5395
 
5396
  *Effects:* Equivalent to:
5397
 
5398
  ``` cpp
5399
+ return ranges::rotate_copy(ranges::begin(r), middle, ranges::end(r), std::move(result));
5400
  ```
5401
 
5402
  ### Sample <a id="alg.random.sample">[[alg.random.sample]]</a>
5403
 
5404
  ``` cpp
 
5431
  requirements [[input.iterators]].
5432
  - `SampleIterator` meets the *Cpp17OutputIterator*
5433
  requirements [[output.iterators]].
5434
  - `SampleIterator` meets the *Cpp17RandomAccessIterator*
5435
  requirements [[random.access.iterators]] unless `PopulationIterator`
5436
+ models `forward_iterator` [[iterator.concept.forward]].
5437
  - `remove_reference_t<UniformRandomBitGenerator>` meets the requirements
5438
  of a uniform random bit generator type [[rand.req.urng]].
5439
 
5440
  *Effects:* Copies min(`last - first`, `n`) elements (the *sample*) from
5441
  \[`first`, `last`) (the *population*) to `out` such that each possible
 
5449
  *Complexity:* 𝑂(`last - first`).
5450
 
5451
  *Remarks:*
5452
 
5453
  - For the overload in namespace `std`, stable if and only if
5454
+ `PopulationIterator` models `forward_iterator`. For the first overload
5455
+ in namespace `ranges`, stable if and only if `I` models
5456
+ `forward_iterator`.
5457
  - To the extent that the implementation of this function makes use of
5458
  random numbers, the object `g` serves as the implementation’s source
5459
  of randomness.
5460
 
5461
  ### Shuffle <a id="alg.random.shuffle">[[alg.random.shuffle]]</a>
 
5504
  typename iterator_traits<ForwardIterator>::difference_type n);
5505
  template<class ExecutionPolicy, class ForwardIterator>
5506
  ForwardIterator
5507
  shift_left(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last,
5508
  typename iterator_traits<ForwardIterator>::difference_type n);
5509
+
5510
+ template<permutable I, sentinel_for<I> S>
5511
+ constexpr subrange<I> ranges::shift_left(I first, S last, iter_difference_t<I> n);
5512
+ template<forward_range R>
5513
+ requires permutable<iterator_t<R>>
5514
+ constexpr borrowed_subrange_t<R> ranges::shift_left(R&& r, range_difference_t<R> n)
5515
  ```
5516
 
5517
+ *Preconditions:* `n >= 0` is `true`. For the overloads in namespace
5518
+ `std`, the type of `*first` meets the *Cpp17MoveAssignable*
5519
+ requirements.
5520
 
5521
  *Effects:* If `n == 0` or `n >= last - first`, does nothing. Otherwise,
5522
  moves the element from position `first + n + i` into position
5523
+ `first + i` for each non-negative integer `i < (last - first) - n`. For
5524
+ the overloads without an `ExecutionPolicy` template parameter, does so
5525
+ in order starting from `i = 0` and proceeding to
5526
+ `i = (last - first) - n - 1`.
5527
 
5528
+ *Returns:* Let *NEW_LAST* be `first + (last - first - n)` if
5529
+ `n < last - first`, otherwise `first`.
5530
+
5531
+ - *NEW_LAST* for the overloads in namespace `std`.
5532
+ - `{first, `*`NEW_LAST`*`}` for the overloads in namespace `ranges`.
5533
 
5534
  *Complexity:* At most `(last - first) - n` assignments.
5535
 
5536
  ``` cpp
5537
  template<class ForwardIterator>
 
5540
  typename iterator_traits<ForwardIterator>::difference_type n);
5541
  template<class ExecutionPolicy, class ForwardIterator>
5542
  ForwardIterator
5543
  shift_right(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last,
5544
  typename iterator_traits<ForwardIterator>::difference_type n);
5545
+
5546
+ template<permutable I, sentinel_for<I> S>
5547
+ constexpr subrange<I> ranges::shift_right(I first, S last, iter_difference_t<I> n);
5548
+ template<forward_range R>
5549
+ requires permutable<iterator_t<R>>
5550
+ constexpr borrowed_subrange_t<R> ranges::shift_right(R&& r, range_difference_t<R> n);
5551
  ```
5552
 
5553
+ *Preconditions:* `n >= 0` is `true`. For the overloads in namespace
5554
+ `std`, the type of `*first` meets the *Cpp17MoveAssignable*
5555
+ requirements, and `ForwardIterator` meets the
5556
  *Cpp17BidirectionalIterator* requirements [[bidirectional.iterators]] or
5557
  the *Cpp17ValueSwappable* requirements.
5558
 
5559
  *Effects:* If `n == 0` or `n >= last - first`, does nothing. Otherwise,
5560
  moves the element from position `first + i` into position
5561
  `first + n + i` for each non-negative integer `i < (last - first) - n`.
5562
+ Does so in order starting from `i = (last - first) - n - 1` and
5563
+ proceeding to `i = 0` if:
 
5564
 
5565
+ - for the overload in namespace `std` without an `ExecutionPolicy`
5566
+ template parameter, `ForwardIterator` meets the
5567
+ *Cpp17BidirectionalIterator* requirements,
5568
+ - for the overloads in namespace `ranges`, `I` models
5569
+ `bidirectional_iterator`.
5570
+
5571
+ *Returns:* Let *NEW_FIRST* be `first + n` if `n < last - first`,
5572
+ otherwise `last`.
5573
+
5574
+ - *NEW_FIRST* for the overloads in namespace `std`.
5575
+ - `{`*`NEW_FIRST`*`, last}` for the overloads in namespace `ranges`.
5576
 
5577
  *Complexity:* At most `(last - first) - n` assignments or swaps.
5578
 
5579
  ## Sorting and related operations <a id="alg.sorting">[[alg.sorting]]</a>
5580
 
5581
+ ### General <a id="alg.sorting.general">[[alg.sorting.general]]</a>
5582
+
5583
  The operations in  [[alg.sorting]] defined directly in namespace `std`
5584
  have two versions: one that takes a function object of type `Compare`
5585
  and one that uses an `operator<`.
5586
 
5587
  `Compare` is a function object type [[function.objects]] that meets the
5588
  requirements for a template parameter named `BinaryPredicate` 
5589
  [[algorithms.requirements]]. The return value of the function call
5590
+ operation applied to an object of type `Compare`, when converted to
5591
+ `bool`, yields `true` if the first argument of the call is less than the
5592
+ second, and `false` otherwise. `Compare comp` is used throughout for
5593
+ algorithms assuming an ordering relation.
5594
 
5595
  For all algorithms that take `Compare`, there is a version that uses
5596
  `operator<` instead. That is, `comp(*i, *j) != false` defaults to
5597
  `*i < *j != false`. For algorithms other than those described in 
5598
  [[alg.binary.search]], `comp` shall induce a strict weak ordering on the
 
5628
  bool(invoke(comp, invoke(proj, *(i + n)), invoke(proj, *i)))
5629
  ```
5630
 
5631
  is `false`.
5632
 
5633
+ A sequence is *sorted with respect to a comparator `comp`* for a
5634
+ comparator `comp` if it is sorted with respect to `comp` and
5635
+ `identity{}` (the identity projection).
5636
+
5637
  A sequence \[`start`, `finish`) is *partitioned with respect to an
5638
  expression* `f(e)` if there exists an integer `n` such that for all
5639
  `0 <= i < (finish - start)`, `f(*(start + i))` is `true` if and only if
5640
  `i < n`.
5641
 
 
5867
  `RandomAccessIterator` meets the *Cpp17ValueSwappable*
5868
  requirements [[swappable.requirements]], the type of `*result_first`
5869
  meets the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
5870
  *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
5871
 
5872
+ For iterators `a1` and `b1` in \[`first`, `last`), and iterators `x2`
5873
+ and `y2` in \[`result_first`, `result_last`), after evaluating the
5874
+ assignment `*y2 = *b1`, let E be the value of
5875
 
5876
  ``` cpp
5877
  bool(invoke(comp, invoke(proj1, *a1), invoke(proj2, *y2))).
5878
  ```
5879
 
 
6051
  return ranges::nth_element(ranges::begin(r), nth, ranges::end(r), comp, proj);
6052
  ```
6053
 
6054
  ### Binary search <a id="alg.binary.search">[[alg.binary.search]]</a>
6055
 
6056
+ #### General <a id="alg.binary.search.general">[[alg.binary.search.general]]</a>
6057
+
6058
+ All of the algorithms in [[alg.binary.search]] are versions of binary
6059
+ search and assume that the sequence being searched is partitioned with
6060
+ respect to an expression formed by binding the search key to an argument
6061
+ of the comparison function. They work on non-random access iterators
6062
+ minimizing the number of comparisons, which will be logarithmic for all
6063
+ types of iterators. They are especially appropriate for random access
6064
+ iterators, because these algorithms do a logarithmic number of steps
6065
+ through the data structure. For non-random access iterators they execute
6066
+ a linear number of steps.
6067
 
6068
  #### `lower_bound` <a id="lower.bound">[[lower.bound]]</a>
6069
 
6070
  ``` cpp
6071
  template<class ForwardIterator, class T>
 
6345
  - `i` for the overloads in namespace `std`.
6346
  - `{i, last}` for the overloads in namespace `ranges`.
6347
 
6348
  *Complexity:* Let N = `last - first`:
6349
 
6350
+ - For the overloads with no `ExecutionPolicy`, at most N log N swaps,
6351
  but only 𝑂(N) swaps if there is enough extra memory. Exactly N
6352
  applications of the predicate and projection.
6353
  - For the overload with an `ExecutionPolicy`, 𝑂(N log N) swaps and 𝑂(N)
6354
  applications of the predicate.
6355
 
6356
  ``` cpp
6357
+ template<class InputIterator, class OutputIterator1, class OutputIterator2, class Predicate>
 
6358
  constexpr pair<OutputIterator1, OutputIterator2>
6359
  partition_copy(InputIterator first, InputIterator last,
6360
  OutputIterator1 out_true, OutputIterator2 out_false, Predicate pred);
6361
  template<class ExecutionPolicy, class ForwardIterator, class ForwardIterator1,
6362
  class ForwardIterator2, class Predicate>
 
6387
  `*first` is writable [[iterator.requirements.general]] to `out_true` and
6388
  `out_false`.
6389
 
6390
  *Preconditions:* The input range and output ranges do not overlap.
6391
 
6392
+ [*Note 1*: For the overload with an `ExecutionPolicy`, there might be a
6393
  performance cost if `first`’s value type does not meet the
6394
  *Cpp17CopyConstructible* requirements. — *end note*]
6395
 
6396
  *Effects:* For each iterator `i` in \[`first`, `last`), copies `*i` to
6397
  the output range beginning with `out_true` if E(`*i`) is `true`, or to
 
6576
  return ranges::inplace_merge(ranges::begin(r), middle, ranges::end(r), comp, proj);
6577
  ```
6578
 
6579
  ### Set operations on sorted structures <a id="alg.set.operations">[[alg.set.operations]]</a>
6580
 
6581
+ #### General <a id="alg.set.operations.general">[[alg.set.operations.general]]</a>
6582
+
6583
+ Subclause [[alg.set.operations]] defines all the basic set operations on
6584
+ sorted structures. They also work with `multiset`s [[multiset]]
6585
+ containing multiple copies of equivalent elements. The semantics of the
6586
+ set operations are generalized to `multiset`s in a standard way by
6587
+ defining `set_union` to contain the maximum number of occurrences of
6588
+ every element, `set_intersection` to contain the minimum, and so on.
6589
 
6590
  #### `includes` <a id="includes">[[includes]]</a>
6591
 
6592
  ``` cpp
6593
  template<class InputIterator1, class InputIterator2>
 
6640
  comparisons and applications of each projection.
6641
 
6642
  #### `set_union` <a id="set.union">[[set.union]]</a>
6643
 
6644
  ``` cpp
6645
+ template<class InputIterator1, class InputIterator2, class OutputIterator>
 
6646
  constexpr OutputIterator
6647
  set_union(InputIterator1 first1, InputIterator1 last1,
6648
  InputIterator2 first2, InputIterator2 last2,
6649
  OutputIterator result);
6650
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
 
6653
  set_union(ExecutionPolicy&& exec,
6654
  ForwardIterator1 first1, ForwardIterator1 last1,
6655
  ForwardIterator2 first2, ForwardIterator2 last2,
6656
  ForwardIterator result);
6657
 
6658
+ template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare>
 
6659
  constexpr OutputIterator
6660
  set_union(InputIterator1 first1, InputIterator1 last1,
6661
  InputIterator2 first2, InputIterator2 last2,
6662
  OutputIterator result, Compare comp);
6663
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
 
6851
  comparisons and applications of each projection.
6852
 
6853
  *Remarks:* If \[`first1`, `last1`) contains m elements that are
6854
  equivalent to each other and \[`first2`, `last2`) contains n elements
6855
  that are equivalent to them, the last max(m - n, 0) elements from
6856
+ \[`first1`, `last1`) are copied to the output range, in order.
6857
 
6858
  #### `set_symmetric_difference` <a id="set.symmetric.difference">[[set.symmetric.difference]]</a>
6859
 
6860
  ``` cpp
6861
  template<class InputIterator1, class InputIterator2,
 
6934
  elements from \[`first2`, `last2`) if m < n. In either case, the
6935
  elements are copied in order.
6936
 
6937
  ### Heap operations <a id="alg.heap.operations">[[alg.heap.operations]]</a>
6938
 
6939
+ #### General <a id="alg.heap.operations.general">[[alg.heap.operations.general]]</a>
6940
+
6941
  A random access range \[`a`, `b`) is a *heap with respect to `comp` and
6942
  `proj`* for a comparator and projection `comp` and `proj` if its
6943
  elements are organized such that:
6944
 
6945
  - With `N = b - a`, for all i, 0 < i < N,
 
6976
 
6977
  Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
6978
  no parameters by those names.
6979
 
6980
  *Preconditions:* The range \[`first`, `last - 1`) is a valid heap with
6981
+ respect to `comp` and `proj`. For the overloads in namespace `std`,
6982
+ `RandomAccessIterator` meets the *Cpp17ValueSwappable*
6983
+ requirements [[swappable.requirements]] and the type of `*first` meets
6984
+ the *Cpp17MoveConstructible* requirements ([[cpp17.moveconstructible]])
6985
+ and the *Cpp17MoveAssignable* requirements ([[cpp17.moveassignable]]).
6986
 
6987
  *Effects:* Places the value in the location `last - 1` into the
6988
  resulting heap \[`first`, `last`).
6989
 
6990
  *Returns:* `last` for the overloads in namespace `ranges`.
 
7054
  ```
7055
 
7056
  Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
7057
  no parameters by those names.
7058
 
7059
+ *Preconditions:* For the overloads in namespace `std`,
7060
+ `RandomAccessIterator` meets the *Cpp17ValueSwappable*
7061
+ requirements [[swappable.requirements]] and the type of `*first` meets
7062
+ the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
7063
+ *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
7064
 
7065
  *Effects:* Constructs a heap with respect to `comp` and `proj` out of
7066
  the range \[`first`, `last`).
7067
 
7068
  *Returns:* `last` for the overloads in namespace `ranges`.
 
7214
  ```
7215
 
7216
  *Preconditions:* For the first form, `T` meets the
7217
  *Cpp17LessThanComparable* requirements ([[cpp17.lessthancomparable]]).
7218
 
7219
+ *Returns:* The smaller value. Returns the first argument when the
7220
+ arguments are equivalent.
 
 
 
7221
 
7222
  *Complexity:* Exactly one comparison and two applications of the
7223
  projection, if any.
7224
 
7225
+ *Remarks:* An invocation may explicitly specify an argument for the
7226
+ template parameter `T` of the overloads in namespace `std`.
7227
+
7228
  ``` cpp
7229
  template<class T>
7230
  constexpr T min(initializer_list<T> r);
7231
  template<class T, class Compare>
7232
  constexpr T min(initializer_list<T> r, Compare comp);
 
7244
  *Preconditions:* `ranges::distance(r) > 0`. For the overloads in
7245
  namespace `std`, `T` meets the *Cpp17CopyConstructible* requirements.
7246
  For the first form, `T` meets the *Cpp17LessThanComparable* requirements
7247
  ([[cpp17.lessthancomparable]]).
7248
 
7249
+ *Returns:* The smallest value in the input range. Returns a copy of the
7250
+ leftmost element when several elements are equivalent to the smallest.
 
 
 
 
7251
 
7252
  *Complexity:* Exactly `ranges::distance(r) - 1` comparisons and twice as
7253
  many applications of the projection, if any.
7254
 
7255
+ *Remarks:* An invocation may explicitly specify an argument for the
7256
+ template parameter `T` of the overloads in namespace `std`.
7257
+
7258
  ``` cpp
7259
  template<class T>
7260
  constexpr const T& max(const T& a, const T& b);
7261
  template<class T, class Compare>
7262
  constexpr const T& max(const T& a, const T& b, Compare comp);
 
7267
  ```
7268
 
7269
  *Preconditions:* For the first form, `T` meets the
7270
  *Cpp17LessThanComparable* requirements ([[cpp17.lessthancomparable]]).
7271
 
7272
+ *Returns:* The larger value. Returns the first argument when the
7273
+ arguments are equivalent.
 
 
 
7274
 
7275
  *Complexity:* Exactly one comparison and two applications of the
7276
  projection, if any.
7277
 
7278
+ *Remarks:* An invocation may explicitly specify an argument for the
7279
+ template parameter `T` of the overloads in namespace `std`.
7280
+
7281
  ``` cpp
7282
  template<class T>
7283
  constexpr T max(initializer_list<T> r);
7284
  template<class T, class Compare>
7285
  constexpr T max(initializer_list<T> r, Compare comp);
 
7297
  *Preconditions:* `ranges::distance(r) > 0`. For the overloads in
7298
  namespace `std`, `T` meets the *Cpp17CopyConstructible* requirements.
7299
  For the first form, `T` meets the *Cpp17LessThanComparable* requirements
7300
  ([[cpp17.lessthancomparable]]).
7301
 
7302
+ *Returns:* The largest value in the input range. Returns a copy of the
7303
+ leftmost element when several elements are equivalent to the largest.
 
 
 
 
7304
 
7305
  *Complexity:* Exactly `ranges::distance(r) - 1` comparisons and twice as
7306
  many applications of the projection, if any.
7307
 
7308
+ *Remarks:* An invocation may explicitly specify an argument for the
7309
+ template parameter `T` of the overloads in namespace `std`.
7310
+
7311
  ``` cpp
7312
  template<class T>
7313
  constexpr pair<const T&, const T&> minmax(const T& a, const T& b);
7314
  template<class T, class Compare>
7315
  constexpr pair<const T&, const T&> minmax(const T& a, const T& b, Compare comp);
 
7323
  *Preconditions:* For the first form, `T` meets the
7324
  *Cpp17LessThanComparable* requirements ([[cpp17.lessthancomparable]]).
7325
 
7326
  *Returns:* `{b, a}` if `b` is smaller than `a`, and `{a, b}` otherwise.
7327
 
 
 
 
7328
  *Complexity:* Exactly one comparison and two applications of the
7329
  projection, if any.
7330
 
7331
+ *Remarks:* An invocation may explicitly specify an argument for the
7332
+ template parameter `T` of the overloads in namespace `std`.
7333
+
7334
  ``` cpp
7335
  template<class T>
7336
  constexpr pair<T, T> minmax(initializer_list<T> t);
7337
  template<class T, class Compare>
7338
  constexpr pair<T, T> minmax(initializer_list<T> t, Compare comp);
 
7355
 
7356
  *Returns:* Let `X` be the return type. Returns `X{x, y}`, where `x` is a
7357
  copy of the leftmost element with the smallest value and `y` a copy of
7358
  the rightmost element with the largest value in the input range.
7359
 
 
 
 
7360
  *Complexity:* At most (3/2)`ranges::distance(r)` applications of the
7361
  corresponding predicate and twice as many applications of the
7362
  projection, if any.
7363
 
7364
+ *Remarks:* An invocation may explicitly specify an argument for the
7365
+ template parameter `T` of the overloads in namespace `std`.
7366
+
7367
  ``` cpp
7368
  template<class ForwardIterator>
7369
  constexpr ForwardIterator min_element(ForwardIterator first, ForwardIterator last);
7370
 
7371
  template<class ExecutionPolicy, class ForwardIterator>
 
7375
  template<class ForwardIterator, class Compare>
7376
  constexpr ForwardIterator min_element(ForwardIterator first, ForwardIterator last,
7377
  Compare comp);
7378
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
7379
  ForwardIterator min_element(ExecutionPolicy&& exec,
7380
+ ForwardIterator first, ForwardIterator last, Compare comp);
 
7381
 
7382
  template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
7383
  indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
7384
  constexpr I ranges::min_element(I first, S last, Comp comp = {}, Proj proj = {});
7385
  template<forward_range R, class Proj = identity,
 
7459
  minmax_element(ExecutionPolicy&& exec,
7460
  ForwardIterator first, ForwardIterator last, Compare comp);
7461
 
7462
  template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
7463
  indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
7464
+ constexpr ranges::minmax_element_result<I>
7465
  ranges::minmax_element(I first, S last, Comp comp = {}, Proj proj = {});
7466
  template<forward_range R, class Proj = identity,
7467
  indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
7468
+ constexpr ranges::minmax_element_result<borrowed_iterator_t<R>>
7469
  ranges::minmax_element(R&& r, Comp comp = {}, Proj proj = {});
7470
  ```
7471
 
7472
  *Returns:* `{first, first}` if \[`first`, `last`) is empty, otherwise
7473
  `{m, M}`, where `m` is the first iterator in \[`first`, `last`) such
7474
  that no iterator in the range refers to a smaller element, and where `M`
7475
+ is the last iterator[^5]
7476
+
7477
+ in \[`first`, `last`) such that no iterator in the range refers to a
7478
+ larger element.
7479
 
7480
  *Complexity:* Let N be `last - first`. At most
7481
  $\max(\bigl\lfloor{\frac{3}{2}} (N-1)\bigr\rfloor, 0)$ comparisons and
7482
  twice as many applications of the projection, if any.
7483
 
 
7495
  ```
7496
 
7497
  Let `comp` be `less{}` for the overloads with no parameter `comp`, and
7498
  let `proj` be `identity{}` for the overloads with no parameter `proj`.
7499
 
7500
+ *Preconditions:*
7501
+ `bool(invoke(comp, invoke(proj, hi), invoke(proj, lo)))` is `false`. For
7502
+ the first form, type `T` meets the *Cpp17LessThanComparable*
7503
+ requirements ([[cpp17.lessthancomparable]]).
7504
 
7505
+ *Returns:* `lo` if
7506
+ `bool(invoke(comp, invoke(proj, v), invoke(proj, lo)))` is `true`, `hi`
7507
+ if `bool(invoke(comp, invoke(proj, hi), invoke(proj, v)))` is `true`,
7508
+ otherwise `v`.
7509
 
7510
  [*Note 1*: If NaN is avoided, `T` can be a floating-point
7511
  type. — *end note*]
7512
 
7513
  *Complexity:* At most two comparisons and three applications of the
 
7572
  corresponding pair of elements that are not equivalent.
7573
 
7574
  [*Example 1*:
7575
 
7576
  `ranges::lexicographical_compare(I1, S1, I2, S2, Comp, Proj1, Proj2)`
7577
+ can be implemented as:
7578
 
7579
  ``` cpp
7580
  for ( ; first1 != last1 && first2 != last2 ; ++first1, (void) ++first2) {
7581
  if (invoke(comp, invoke(proj1, *first1), invoke(proj2, *first2))) return true;
7582
  if (invoke(comp, invoke(proj2, *first2), invoke(proj1, *first1))) return false;
 
7598
  InputIterator2 b2, InputIterator2 e2,
7599
  Cmp comp)
7600
  -> decltype(comp(*b1, *b2));
7601
  ```
7602
 
7603
+ Let N be min(`e1 - b1`, `e2 - b2`). Let E(n) be
7604
+ `comp(*(b1 + `n`), *(b2 + `n`))`.
7605
+
7606
  *Mandates:* `decltype(comp(*b1, *b2))` is a comparison category type.
7607
 
7608
+ *Returns:* E(i), where i is the smallest integer in \[`0`, N) such that
7609
+ E(i)` != 0` is `true`, or `(e1 - b1) <=> (e2 - b2)` if no such integer
7610
+ exists.
7611
 
7612
+ *Complexity:* At most N applications of `comp`.
 
 
 
 
 
 
 
7613
 
7614
  ``` cpp
7615
  template<class InputIterator1, class InputIterator2>
7616
  constexpr auto
7617
  lexicographical_compare_three_way(InputIterator1 b1, InputIterator1 e1,
 
7912
 
7913
  // [numeric.iota], iota
7914
  template<class ForwardIterator, class T>
7915
  constexpr void iota(ForwardIterator first, ForwardIterator last, T value);
7916
 
7917
+ namespace ranges {
7918
+ template<class O, class T>
7919
+ using iota_result = out_value_result<O, T>;
7920
+
7921
+ template<input_or_output_iterator O, sentinel_for<O> S, weakly_incrementable T>
7922
+ requires indirectly_writable<O, const T&>
7923
+ constexpr iota_result<O, T> iota(O first, S last, T value);
7924
+
7925
+ template<weakly_incrementable T, output_range<const T&> R>
7926
+ constexpr iota_result<borrowed_iterator_t<R>, T> iota(R&& r, T value);
7927
+ }
7928
+
7929
  // [numeric.ops.gcd], greatest common divisor
7930
  template<class M, class N>
7931
  constexpr common_type_t<M, N> gcd(M m, N n);
7932
 
7933
  // [numeric.ops.lcm], least common multiple
 
7942
  }
7943
  ```
7944
 
7945
  ## Generalized numeric operations <a id="numeric.ops">[[numeric.ops]]</a>
7946
 
7947
+ ### General <a id="numeric.ops.general">[[numeric.ops.general]]</a>
7948
+
7949
  [*Note 1*: The use of closed ranges as well as semi-open ranges to
7950
+ specify requirements throughout [[numeric.ops]] is
7951
  intentional. — *end note*]
7952
 
7953
  ### Definitions <a id="numerics.defns">[[numerics.defns]]</a>
7954
 
7955
  Define `GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, ..., aN)` as follows:
 
8332
  *Remarks:* `result` may be equal to `first`.
8333
 
8334
  [*Note 1*: The difference between `exclusive_scan` and `inclusive_scan`
8335
  is that `exclusive_scan` excludes the iᵗʰ input element from the iᵗʰ
8336
  sum. If `binary_op` is not mathematically associative, the behavior of
8337
+ `exclusive_scan` can be nondeterministic. — *end note*]
8338
 
8339
  ### Inclusive scan <a id="inclusive.scan">[[inclusive.scan]]</a>
8340
 
8341
  ``` cpp
8342
  template<class InputIterator, class OutputIterator>
 
8427
  *Remarks:* `result` may be equal to `first`.
8428
 
8429
  [*Note 1*: The difference between `exclusive_scan` and `inclusive_scan`
8430
  is that `inclusive_scan` includes the iᵗʰ input element in the iᵗʰ sum.
8431
  If `binary_op` is not mathematically associative, the behavior of
8432
+ `inclusive_scan` can be nondeterministic. — *end note*]
8433
 
8434
  ### Transform exclusive scan <a id="transform.exclusive.scan">[[transform.exclusive.scan]]</a>
8435
 
8436
  ``` cpp
8437
  template<class InputIterator, class OutputIterator, class T,
 
8484
 
8485
  [*Note 1*: The difference between `transform_exclusive_scan` and
8486
  `transform_inclusive_scan` is that `transform_exclusive_scan` excludes
8487
  the iᵗʰ input element from the iᵗʰ sum. If `binary_op` is not
8488
  mathematically associative, the behavior of `transform_exclusive_scan`
8489
+ can be nondeterministic. `transform_exclusive_scan` does not apply
8490
  `unary_op` to `init`. — *end note*]
8491
 
8492
  ### Transform inclusive scan <a id="transform.inclusive.scan">[[transform.inclusive.scan]]</a>
8493
 
8494
  ``` cpp
 
8567
 
8568
  [*Note 1*: The difference between `transform_exclusive_scan` and
8569
  `transform_inclusive_scan` is that `transform_inclusive_scan` includes
8570
  the iᵗʰ input element in the iᵗʰ sum. If `binary_op` is not
8571
  mathematically associative, the behavior of `transform_inclusive_scan`
8572
+ can be nondeterministic. `transform_inclusive_scan` does not apply
8573
  `unary_op` to `init`. — *end note*]
8574
 
8575
  ### Adjacent difference <a id="adjacent.difference">[[adjacent.difference]]</a>
8576
 
8577
  ``` cpp
 
8615
 
8616
  - For the overloads with no `ExecutionPolicy`, `T` meets the
8617
  *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
8618
  - For all overloads, in the ranges \[`first`, `last`\] and \[`result`,
8619
  `result + (last - first)`\], `binary_op` neither modifies elements nor
8620
+ invalidates iterators or subranges.[^10]
8621
 
8622
  *Effects:* For the overloads with no `ExecutionPolicy` and a non-empty
8623
  range, the function creates an accumulator `acc` of type `T`,
8624
  initializes it with `*first`, and assigns the result to `*result`. For
8625
  every iterator `i` in \[`first + 1`, `last`) in order, creates an object
 
8656
  \[`first`, `last`), assigns `*i = value` and increments `value` as if by
8657
  `++value`.
8658
 
8659
  *Complexity:* Exactly `last - first` increments and assignments.
8660
 
8661
+ ``` cpp
8662
+ template<input_or_output_iterator O, sentinel_for<O> S, weakly_incrementable T>
8663
+ requires indirectly_writable<O, const T&>
8664
+ constexpr ranges::iota_result<O, T> ranges::iota(O first, S last, T value);
8665
+ template<weakly_incrementable T, output_range<const T&> R>
8666
+ constexpr ranges::iota_result<borrowed_iterator_t<R>, T> ranges::iota(R&& r, T value);
8667
+ ```
8668
+
8669
+ *Effects:* Equivalent to:
8670
+
8671
+ ``` cpp
8672
+ while (first != last) {
8673
+ *first = as_const(value);
8674
+ ++first;
8675
+ ++value;
8676
+ }
8677
+ return {std::move(first), std::move(value)};
8678
+ ```
8679
+
8680
  ### Greatest common divisor <a id="numeric.ops.gcd">[[numeric.ops.gcd]]</a>
8681
 
8682
  ``` cpp
8683
  template<class M, class N>
8684
  constexpr common_type_t<M, N> gcd(M m, N n);
8685
  ```
8686
 
8687
+ *Mandates:* `M` and `N` both are integer types other than cv `bool`.
8688
 
8689
  *Preconditions:* |`m`| and |`n`| are representable as a value of
8690
  `common_type_t<M, N>`.
8691
 
8692
  [*Note 1*: These requirements ensure, for example, that
 
8703
  ``` cpp
8704
  template<class M, class N>
8705
  constexpr common_type_t<M, N> lcm(M m, N n);
8706
  ```
8707
 
8708
+ *Mandates:* `M` and `N` both are integer types other than cv `bool`.
8709
 
8710
  *Preconditions:* |`m`| and |`n`| are representable as a value of
8711
  `common_type_t<M, N>`. The least common multiple of |`m`| and |`n`| is
8712
  representable as a value of type `common_type_t<M, N>`.
8713
 
 
8752
  *Returns:* A pointer to array element $i+\frac{j-i}{2}$ of `x`, where
8753
  the result of the division is truncated towards zero.
8754
 
8755
  ## Specialized `<memory>` algorithms <a id="specialized.algorithms">[[specialized.algorithms]]</a>
8756
 
8757
+ ### General <a id="specialized.algorithms.general">[[specialized.algorithms.general]]</a>
8758
+
8759
+ The contents specified in [[specialized.algorithms]] are declared in the
8760
+ header `<memory>`.
8761
 
8762
  Unless otherwise specified, if an exception is thrown in the following
8763
  algorithms, objects constructed by a placement *new-expression*
8764
  [[expr.new]] are destroyed in an unspecified order before allowing the
8765
  exception to propagate.
8766
 
8767
+ Some algorithms specified in [[specialized.algorithms]] make use of the
8768
+ exposition-only function `voidify`:
 
 
 
 
8769
 
8770
  ``` cpp
8771
  template<class T>
8772
  constexpr void* voidify(T& obj) noexcept {
8773
+ return addressof(obj);
8774
  }
8775
  ```
8776
 
8777
  ### Special memory concepts <a id="special.mem.concepts">[[special.mem.concepts]]</a>
8778
 
8779
  Some algorithms in this subclause are constrained with the following
8780
  exposition-only concepts:
8781
 
8782
  ``` cpp
8783
  template<class I>
8784
+ concept nothrow-input-iterator = // exposition only
8785
  input_iterator<I> &&
8786
  is_lvalue_reference_v<iter_reference_t<I>> &&
8787
  same_as<remove_cvref_t<iter_reference_t<I>>, iter_value_t<I>>;
8788
  ```
8789
 
8790
+ A type `I` models `nothrow-input-iterator` only if no exceptions are
8791
  thrown from increment, copy construction, move construction, copy
8792
  assignment, move assignment, or indirection through valid iterators.
8793
 
8794
  [*Note 1*: This concept allows some `input_iterator`
8795
  [[iterator.concept.input]] operations to throw
8796
  exceptions. — *end note*]
8797
 
8798
  ``` cpp
8799
  template<class S, class I>
8800
+ concept nothrow-sentinel-for = sentinel_for<S, I>; // exposition only
8801
  ```
8802
 
8803
+ Types `S` and `I` model `nothrow-sentinel-for` only if no exceptions are
8804
  thrown from copy construction, move construction, copy assignment, move
8805
  assignment, or comparisons between valid values of type `I` and `S`.
8806
 
8807
  [*Note 2*: This concept allows some `sentinel_for`
8808
  [[iterator.concept.sentinel]] operations to throw
8809
  exceptions. — *end note*]
8810
 
8811
  ``` cpp
8812
  template<class R>
8813
+ concept nothrow-input-range = // exposition only
8814
  range<R> &&
8815
+ nothrow-input-iterator<iterator_t<R>> &&
8816
+ nothrow-sentinel-for<sentinel_t<R>, iterator_t<R>>;
8817
  ```
8818
 
8819
+ A type `R` models `nothrow-input-range` only if no exceptions are thrown
8820
+ from calls to `ranges::begin` and `ranges::end` on an object of type
8821
+ `R`.
8822
 
8823
  ``` cpp
8824
  template<class I>
8825
+ concept nothrow-forward-iterator = // exposition only
8826
+ nothrow-input-iterator<I> &&
8827
  forward_iterator<I> &&
8828
+ nothrow-sentinel-for<I, I>;
8829
  ```
8830
 
8831
  [*Note 3*: This concept allows some `forward_iterator`
8832
  [[iterator.concept.forward]] operations to throw
8833
  exceptions. — *end note*]
8834
 
8835
  ``` cpp
8836
  template<class R>
8837
+ concept nothrow-forward-range = // exposition only
8838
+ nothrow-input-range<R> &&
8839
+ nothrow-forward-iterator<iterator_t<R>>;
8840
  ```
8841
 
8842
  ### `uninitialized_default_construct` <a id="uninitialized.construct.default">[[uninitialized.construct.default]]</a>
8843
 
8844
  ``` cpp
 
8854
  typename iterator_traits<NoThrowForwardIterator>::value_type;
8855
  ```
8856
 
8857
  ``` cpp
8858
  namespace ranges {
8859
+ template<nothrow-forward-iterator I, nothrow-sentinel-for<I> S>
8860
  requires default_initializable<iter_value_t<I>>
8861
  I uninitialized_default_construct(I first, S last);
8862
+ template<nothrow-forward-range R>
8863
  requires default_initializable<range_value_t<R>>
8864
  borrowed_iterator_t<R> uninitialized_default_construct(R&& r);
8865
  }
8866
  ```
8867
 
 
8887
  return first;
8888
  ```
8889
 
8890
  ``` cpp
8891
  namespace ranges {
8892
+ template<nothrow-forward-iterator I>
8893
  requires default_initializable<iter_value_t<I>>
8894
  I uninitialized_default_construct_n(I first, iter_difference_t<I> n);
8895
  }
8896
  ```
8897
 
 
8917
  typename iterator_traits<NoThrowForwardIterator>::value_type();
8918
  ```
8919
 
8920
  ``` cpp
8921
  namespace ranges {
8922
+ template<nothrow-forward-iterator I, nothrow-sentinel-for<I> S>
8923
  requires default_initializable<iter_value_t<I>>
8924
  I uninitialized_value_construct(I first, S last);
8925
+ template<nothrow-forward-range R>
8926
  requires default_initializable<range_value_t<R>>
8927
  borrowed_iterator_t<R> uninitialized_value_construct(R&& r);
8928
  }
8929
  ```
8930
 
 
8950
  return first;
8951
  ```
8952
 
8953
  ``` cpp
8954
  namespace ranges {
8955
+ template<nothrow-forward-iterator I>
8956
  requires default_initializable<iter_value_t<I>>
8957
  I uninitialized_value_construct_n(I first, iter_difference_t<I> n);
8958
  }
8959
  ```
8960
 
 
8987
  *Returns:* `result`.
8988
 
8989
  ``` cpp
8990
  namespace ranges {
8991
  template<input_iterator I, sentinel_for<I> S1,
8992
+ nothrow-forward-iterator O, nothrow-sentinel-for<O> S2>
8993
  requires constructible_from<iter_value_t<O>, iter_reference_t<I>>
8994
  uninitialized_copy_result<I, O>
8995
  uninitialized_copy(I ifirst, S1 ilast, O ofirst, S2 olast);
8996
+ template<input_range IR, nothrow-forward-range OR>
8997
  requires constructible_from<range_value_t<OR>, range_reference_t<IR>>
8998
  uninitialized_copy_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>
8999
  uninitialized_copy(IR&& in_range, OR&& out_range);
9000
  }
9001
  ```
 
9004
  `ilast`).
9005
 
9006
  *Effects:* Equivalent to:
9007
 
9008
  ``` cpp
9009
+ for (; ifirst != ilast && ofirst != olast; ++ofirst, (void)++ifirst)
9010
  ::new (voidify(*ofirst)) remove_reference_t<iter_reference_t<O>>(*ifirst);
 
9011
  return {std::move(ifirst), ofirst};
9012
  ```
9013
 
9014
  ``` cpp
9015
  template<class InputIterator, class Size, class NoThrowForwardIterator>
 
9021
  `n`).
9022
 
9023
  *Effects:* Equivalent to:
9024
 
9025
  ``` cpp
9026
+ for ( ; n > 0; ++result, (void) ++first, --n)
9027
  ::new (voidify(*result))
9028
  typename iterator_traits<NoThrowForwardIterator>::value_type(*first);
 
9029
  ```
9030
 
9031
  *Returns:* `result`.
9032
 
9033
  ``` cpp
9034
  namespace ranges {
9035
+ template<input_iterator I, nothrow-forward-iterator O, nothrow-sentinel-for<O> S>
9036
  requires constructible_from<iter_value_t<O>, iter_reference_t<I>>
9037
  uninitialized_copy_n_result<I, O>
9038
  uninitialized_copy_n(I ifirst, iter_difference_t<I> n, O ofirst, S olast);
9039
  }
9040
  ```
 
9043
  `ifirst`+\[0, `n`).
9044
 
9045
  *Effects:* Equivalent to:
9046
 
9047
  ``` cpp
9048
+ auto t = uninitialized_copy(counted_iterator(std::move(ifirst), n),
9049
  default_sentinel, ofirst, olast);
9050
  return {std::move(t.in).base(), t.out};
9051
  ```
9052
 
9053
  ### `uninitialized_move` <a id="uninitialized.move">[[uninitialized.move]]</a>
 
9071
  ```
9072
 
9073
  ``` cpp
9074
  namespace ranges {
9075
  template<input_iterator I, sentinel_for<I> S1,
9076
+ nothrow-forward-iterator O, nothrow-sentinel-for<O> S2>
9077
  requires constructible_from<iter_value_t<O>, iter_rvalue_reference_t<I>>
9078
  uninitialized_move_result<I, O>
9079
  uninitialized_move(I ifirst, S1 ilast, O ofirst, S2 olast);
9080
+ template<input_range IR, nothrow-forward-range OR>
9081
  requires constructible_from<range_value_t<OR>, range_rvalue_reference_t<IR>>
9082
  uninitialized_move_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>
9083
  uninitialized_move(IR&& in_range, OR&& out_range);
9084
  }
9085
  ```
 
9088
  `ilast`).
9089
 
9090
  *Effects:* Equivalent to:
9091
 
9092
  ``` cpp
9093
+ for (; ifirst != ilast && ofirst != olast; ++ofirst, (void)++ifirst)
9094
  ::new (voidify(*ofirst))
9095
  remove_reference_t<iter_reference_t<O>>(ranges::iter_move(ifirst));
 
9096
  return {std::move(ifirst), ofirst};
9097
  ```
9098
 
9099
  [*Note 1*: If an exception is thrown, some objects in the range
9100
+ \[`ifirst`, `ilast`) are left in a valid, but unspecified
9101
  state. — *end note*]
9102
 
9103
  ``` cpp
9104
  template<class InputIterator, class Size, class NoThrowForwardIterator>
9105
  pair<InputIterator, NoThrowForwardIterator>
 
9118
  return {first, result};
9119
  ```
9120
 
9121
  ``` cpp
9122
  namespace ranges {
9123
+ template<input_iterator I, nothrow-forward-iterator O, nothrow-sentinel-for<O> S>
9124
  requires constructible_from<iter_value_t<O>, iter_rvalue_reference_t<I>>
9125
  uninitialized_move_n_result<I, O>
9126
  uninitialized_move_n(I ifirst, iter_difference_t<I> n, O ofirst, S olast);
9127
  }
9128
  ```
 
9131
  `ifirst`+\[0, `n`).
9132
 
9133
  *Effects:* Equivalent to:
9134
 
9135
  ``` cpp
9136
+ auto t = uninitialized_move(counted_iterator(std::move(ifirst), n),
9137
  default_sentinel, ofirst, olast);
9138
  return {std::move(t.in).base(), t.out};
9139
  ```
9140
 
9141
  [*Note 2*: If an exception is thrown, some objects in the range
9142
+ `ifirst`+\[0, `n`) are left in a valid but unspecified
9143
  state. — *end note*]
9144
 
9145
  ### `uninitialized_fill` <a id="uninitialized.fill">[[uninitialized.fill]]</a>
9146
 
9147
  ``` cpp
 
9157
  typename iterator_traits<NoThrowForwardIterator>::value_type(x);
9158
  ```
9159
 
9160
  ``` cpp
9161
  namespace ranges {
9162
+ template<nothrow-forward-iterator I, nothrow-sentinel-for<I> S, class T>
9163
  requires constructible_from<iter_value_t<I>, const T&>
9164
  I uninitialized_fill(I first, S last, const T& x);
9165
+ template<nothrow-forward-range R, class T>
9166
  requires constructible_from<range_value_t<R>, const T&>
9167
  borrowed_iterator_t<R> uninitialized_fill(R&& r, const T& x);
9168
  }
9169
  ```
9170
 
9171
  *Effects:* Equivalent to:
9172
 
9173
  ``` cpp
9174
+ for (; first != last; ++first)
9175
  ::new (voidify(*first)) remove_reference_t<iter_reference_t<I>>(x);
 
9176
  return first;
9177
  ```
9178
 
9179
  ``` cpp
9180
  template<class NoThrowForwardIterator, class Size, class T>
 
9190
  return first;
9191
  ```
9192
 
9193
  ``` cpp
9194
  namespace ranges {
9195
+ template<nothrow-forward-iterator I, class T>
9196
  requires constructible_from<iter_value_t<I>, const T&>
9197
  I uninitialized_fill_n(I first, iter_difference_t<I> n, const T& x);
9198
  }
9199
  ```
9200
 
 
9216
  }
9217
  ```
9218
 
9219
  *Constraints:* The expression
9220
  `::new (declval<void*>()) T(declval<Args>()...)` is well-formed when
9221
+ treated as an unevaluated operand [[term.unevaluated.operand]].
9222
 
9223
  *Effects:* Equivalent to:
9224
 
9225
  ``` cpp
9226
  return ::new (voidify(*location)) T(std::forward<Args>(args)...);
 
9255
  destroy_at(addressof(*first));
9256
  ```
9257
 
9258
  ``` cpp
9259
  namespace ranges {
9260
+ template<nothrow-input-iterator I, nothrow-sentinel-for<I> S>
9261
  requires destructible<iter_value_t<I>>
9262
  constexpr I destroy(I first, S last) noexcept;
9263
+ template<nothrow-input-range R>
9264
  requires destructible<range_value_t<R>>
9265
  constexpr borrowed_iterator_t<R> destroy(R&& r) noexcept;
9266
  }
9267
  ```
9268
 
 
9287
  return first;
9288
  ```
9289
 
9290
  ``` cpp
9291
  namespace ranges {
9292
+ template<nothrow-input-iterator I>
9293
  requires destructible<iter_value_t<I>>
9294
  constexpr I destroy_n(I first, iter_difference_t<I> n) noexcept;
9295
  }
9296
  ```
9297
 
9298
  *Effects:* Equivalent to:
9299
 
9300
  ``` cpp
9301
+ return destroy(counted_iterator(std::move(first), n), default_sentinel).base();
9302
  ```
9303
 
9304
  ## C library algorithms <a id="alg.c.library">[[alg.c.library]]</a>
9305
 
9306
  [*Note 1*: The header `<cstdlib>` declares the functions described in
 
9313
  compare-pred* compar);
9314
  void qsort(void* base, size_t nmemb, size_t size, c-compare-pred* compar);
9315
  void qsort(void* base, size_t nmemb, size_t size, compare-pred* compar);
9316
  ```
9317
 
9318
+ *Preconditions:* For `qsort`, the objects in the array pointed to by
9319
+ `base` are of trivially copyable type.
9320
+
9321
  *Effects:* These functions have the semantics specified in the C
9322
  standard library.
9323
 
 
 
 
9324
  *Throws:* Any exception thrown by `compar`
9325
  [[res.on.exception.handling]].
9326
 
9327
+ See also: ISO C 7.22.5
9328
 
9329
  <!-- Link reference definitions -->
9330
  [accumulate]: #accumulate
9331
  [adjacent.difference]: #adjacent.difference
9332
  [alg.adjacent.find]: #alg.adjacent.find
9333
  [alg.all.of]: #alg.all.of
9334
  [alg.any.of]: #alg.any.of
9335
  [alg.binary.search]: #alg.binary.search
9336
+ [alg.binary.search.general]: #alg.binary.search.general
9337
  [alg.c.library]: #alg.c.library
9338
  [alg.clamp]: #alg.clamp
9339
+ [alg.contains]: #alg.contains
9340
  [alg.copy]: #alg.copy
9341
  [alg.count]: #alg.count
9342
+ [alg.ends.with]: #alg.ends.with
9343
  [alg.equal]: #alg.equal
9344
  [alg.fill]: #alg.fill
9345
  [alg.find]: #alg.find
9346
  [alg.find.end]: #alg.find.end
9347
  [alg.find.first.of]: #alg.find.first.of
9348
+ [alg.find.last]: #alg.find.last
9349
+ [alg.fold]: #alg.fold
9350
  [alg.foreach]: #alg.foreach
9351
  [alg.generate]: #alg.generate
9352
  [alg.heap.operations]: #alg.heap.operations
9353
+ [alg.heap.operations.general]: #alg.heap.operations.general
9354
  [alg.is.permutation]: #alg.is.permutation
9355
  [alg.lex.comparison]: #alg.lex.comparison
9356
  [alg.merge]: #alg.merge
9357
  [alg.min.max]: #alg.min.max
9358
  [alg.modifying.operations]: #alg.modifying.operations
 
9368
  [alg.replace]: #alg.replace
9369
  [alg.reverse]: #alg.reverse
9370
  [alg.rotate]: #alg.rotate
9371
  [alg.search]: #alg.search
9372
  [alg.set.operations]: #alg.set.operations
9373
+ [alg.set.operations.general]: #alg.set.operations.general
9374
  [alg.shift]: #alg.shift
9375
  [alg.sort]: #alg.sort
9376
  [alg.sorting]: #alg.sorting
9377
+ [alg.sorting.general]: #alg.sorting.general
9378
+ [alg.starts.with]: #alg.starts.with
9379
  [alg.swap]: #alg.swap
9380
  [alg.three.way]: #alg.three.way
9381
  [alg.transform]: #alg.transform
9382
  [alg.unique]: #alg.unique
9383
  [algorithm.stable]: library.md#algorithm.stable
 
9397
  [basic.lookup.argdep]: basic.md#basic.lookup.argdep
9398
  [basic.lookup.unqual]: basic.md#basic.lookup.unqual
9399
  [bidirectional.iterators]: iterators.md#bidirectional.iterators
9400
  [binary.search]: #binary.search
9401
  [class.conv]: class.md#class.conv
9402
+ [concept.booleantestable]: concepts.md#concept.booleantestable
9403
  [containers]: containers.md#containers
 
9404
  [conv.integral]: expr.md#conv.integral
9405
  [cpp17.copyassignable]: #cpp17.copyassignable
9406
  [cpp17.copyconstructible]: #cpp17.copyconstructible
9407
  [cpp17.lessthancomparable]: #cpp17.lessthancomparable
9408
  [cpp17.moveassignable]: #cpp17.moveassignable
 
9417
  [includes]: #includes
9418
  [inclusive.scan]: #inclusive.scan
9419
  [inner.product]: #inner.product
9420
  [input.iterators]: iterators.md#input.iterators
9421
  [intro.execution]: basic.md#intro.execution
 
9422
  [intro.progress]: basic.md#intro.progress
9423
  [is.heap]: #is.heap
9424
  [is.sorted]: #is.sorted
9425
+ [iterator.concept.bidir]: iterators.md#iterator.concept.bidir
9426
  [iterator.concept.forward]: iterators.md#iterator.concept.forward
9427
  [iterator.concept.input]: iterators.md#iterator.concept.input
9428
+ [iterator.concept.random.access]: iterators.md#iterator.concept.random.access
9429
  [iterator.concept.sentinel]: iterators.md#iterator.concept.sentinel
9430
  [iterator.concept.sizedsentinel]: iterators.md#iterator.concept.sizedsentinel
9431
  [iterator.requirements]: iterators.md#iterator.requirements
9432
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
9433
  [lower.bound]: #lower.bound
 
9435
  [mismatch]: #mismatch
9436
  [multiset]: containers.md#multiset
9437
  [numeric.iota]: #numeric.iota
9438
  [numeric.ops]: #numeric.ops
9439
  [numeric.ops.gcd]: #numeric.ops.gcd
9440
+ [numeric.ops.general]: #numeric.ops.general
9441
  [numeric.ops.lcm]: #numeric.ops.lcm
9442
  [numeric.ops.midpoint]: #numeric.ops.midpoint
9443
  [numeric.ops.overview]: #numeric.ops.overview
9444
  [numerics.defns]: #numerics.defns
9445
  [output.iterators]: iterators.md#output.iterators
 
9460
  [set.union]: #set.union
9461
  [sort]: #sort
9462
  [sort.heap]: #sort.heap
9463
  [special.mem.concepts]: #special.mem.concepts
9464
  [specialized.algorithms]: #specialized.algorithms
9465
+ [specialized.algorithms.general]: #specialized.algorithms.general
9466
  [specialized.construct]: #specialized.construct
9467
  [specialized.destroy]: #specialized.destroy
9468
  [stable.sort]: #stable.sort
9469
  [swappable.requirements]: library.md#swappable.requirements
9470
  [temp.func.order]: temp.md#temp.func.order
9471
+ [term.unevaluated.operand]: expr.md#term.unevaluated.operand
9472
  [thread.jthread.class]: thread.md#thread.jthread.class
9473
  [thread.thread.class]: thread.md#thread.thread.class
9474
  [transform.exclusive.scan]: #transform.exclusive.scan
9475
  [transform.inclusive.scan]: #transform.inclusive.scan
9476
  [transform.reduce]: #transform.reduce
 
9483
 
9484
  [^1]: The decision whether to include a copying version was usually
9485
  based on complexity considerations. When the cost of doing the
9486
  operation dominates the cost of copy, the copying version is not
9487
  included. For example, `sort_copy` is not included because the cost
9488
+ of sorting is much more significant, and users can invoke `copy`
9489
+ followed by `sort`.
9490
 
9491
+ [^2]: `copy_backward` can be used instead of `copy` when `last` is in
9492
  the range \[`result - `N, `result`).
9493
 
9494
+ [^3]: `move_backward` can be used instead of `move` when `last` is in
9495
  the range \[`result - `N, `result`).
9496
 
9497
  [^4]: The use of fully closed ranges is intentional.
9498
 
9499
  [^5]: This behavior intentionally differs from `max_element`.