From Jason Turner

[alg.sorting]

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

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp76zluuda/{from.md → to.md} +1194 -452
tmp/tmp76zluuda/{from.md → to.md} RENAMED
@@ -1,19 +1,18 @@
1
  ## Sorting and related operations <a id="alg.sorting">[[alg.sorting]]</a>
2
 
3
- All the operations in  [[alg.sorting]] have two versions: one that takes
4
- a function object of type `Compare` and one that uses an `operator<`.
 
5
 
6
- `Compare`
7
-
8
- is a function object type ([[function.objects]]). The return value of
9
- the function call operation applied to an object of type `Compare`, when
10
- contextually converted to `bool` (Clause  [[conv]]), yields `true` if
11
- the first argument of the call is less than the second, and `false`
12
- otherwise. `Compare comp` is used throughout for algorithms assuming an
13
- ordering relation. It is assumed that `comp` will not apply any
14
- non-constant function through the dereferenced iterator.
15
 
16
  For all algorithms that take `Compare`, there is a version that uses
17
  `operator<` instead. That is, `comp(*i, *j) != false` defaults to
18
  `*i < *j != false`. For algorithms other than those described in 
19
  [[alg.binary.search]], `comp` shall induce a strict weak ordering on the
@@ -31,21 +30,27 @@ for a partial ordering. If we define `equiv(a, b)` as
31
 
32
  [*Note 1*:
33
 
34
  Under these conditions, it can be shown that
35
 
36
- - `equiv` is an equivalence relation
37
  - `comp` induces a well-defined relation on the equivalence classes
38
- determined by `equiv`
39
- - The induced relation is a strict total ordering.
40
 
41
  — *end note*]
42
 
43
- A sequence is *sorted with respect to a comparator* `comp` if for every
44
- iterator `i` pointing to the sequence and every non-negative integer `n`
45
- such that `i + n` is a valid iterator pointing to an element of the
46
- sequence, `comp(*(i + n), *i) == false`.
 
 
 
 
 
 
47
 
48
  A sequence \[`start`, `finish`) is *partitioned with respect to an
49
  expression* `f(e)` if there exists an integer `n` such that for all
50
  `0 <= i < (finish - start)`, `f(*(start + i))` is `true` if and only if
51
  `i < n`.
@@ -61,33 +66,50 @@ equivalent if and only if `!(a < b) && !(b < a)`.
61
 
62
  #### `sort` <a id="sort">[[sort]]</a>
63
 
64
  ``` cpp
65
  template<class RandomAccessIterator>
66
- void sort(RandomAccessIterator first, RandomAccessIterator last);
67
  template<class ExecutionPolicy, class RandomAccessIterator>
68
  void sort(ExecutionPolicy&& exec,
69
  RandomAccessIterator first, RandomAccessIterator last);
70
 
71
  template<class RandomAccessIterator, class Compare>
72
- void sort(RandomAccessIterator first, RandomAccessIterator last,
73
  Compare comp);
74
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
75
  void sort(ExecutionPolicy&& exec,
76
  RandomAccessIterator first, RandomAccessIterator last,
77
  Compare comp);
 
 
 
 
 
 
 
 
 
 
78
  ```
79
 
80
- *Requires:* `RandomAccessIterator` shall satisfy the requirements of
81
- `ValueSwappable` ([[swappable.requirements]]). The type of `*first`
82
- shall satisfy the requirements of `MoveConstructible`
83
- (Table  [[tab:moveconstructible]]) and of `MoveAssignable`
84
- (Table  [[tab:moveassignable]]).
85
 
86
- *Effects:* Sorts the elements in the range \[`first`, `last`).
 
 
 
 
87
 
88
- *Complexity:* 𝑂(N log N) comparisons, where N = `last - first`.
 
 
 
 
 
 
89
 
90
  #### `stable_sort` <a id="stable.sort">[[stable.sort]]</a>
91
 
92
  ``` cpp
93
  template<class RandomAccessIterator>
@@ -101,70 +123,112 @@ template<class RandomAccessIterator, class Compare>
101
  Compare comp);
102
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
103
  void stable_sort(ExecutionPolicy&& exec,
104
  RandomAccessIterator first, RandomAccessIterator last,
105
  Compare comp);
 
 
 
 
 
 
 
 
 
106
  ```
107
 
108
- *Requires:* `RandomAccessIterator` shall satisfy the requirements of
109
- `ValueSwappable` ([[swappable.requirements]]). The type of `*first`
110
- shall satisfy the requirements of `MoveConstructible`
111
- (Table  [[tab:moveconstructible]]) and of `MoveAssignable`
112
- (Table  [[tab:moveassignable]]).
113
 
114
- *Effects:* Sorts the elements in the range \[`first`, `last`).
 
 
 
 
115
 
116
- *Complexity:* At most N log²(N) comparisons, where N = `last - first`,
117
- but only N log N comparisons if there is enough extra memory.
118
 
119
- *Remarks:* Stable ([[algorithm.stable]]).
 
 
 
 
 
 
 
120
 
121
  #### `partial_sort` <a id="partial.sort">[[partial.sort]]</a>
122
 
123
  ``` cpp
124
  template<class RandomAccessIterator>
125
- void partial_sort(RandomAccessIterator first,
126
  RandomAccessIterator middle,
127
  RandomAccessIterator last);
128
  template<class ExecutionPolicy, class RandomAccessIterator>
129
  void partial_sort(ExecutionPolicy&& exec,
130
  RandomAccessIterator first,
131
  RandomAccessIterator middle,
132
  RandomAccessIterator last);
133
 
134
  template<class RandomAccessIterator, class Compare>
135
- void partial_sort(RandomAccessIterator first,
136
  RandomAccessIterator middle,
137
  RandomAccessIterator last,
138
  Compare comp);
139
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
140
  void partial_sort(ExecutionPolicy&& exec,
141
  RandomAccessIterator first,
142
  RandomAccessIterator middle,
143
  RandomAccessIterator last,
144
  Compare comp);
 
 
 
 
 
 
145
  ```
146
 
147
- *Requires:* `RandomAccessIterator` shall satisfy the requirements of
148
- `ValueSwappable` ([[swappable.requirements]]). The type of `*first`
149
- shall satisfy the requirements of `MoveConstructible`
150
- (Table  [[tab:moveconstructible]]) and of `MoveAssignable`
151
- (Table  [[tab:moveassignable]]).
152
 
153
- *Effects:* Places the first `middle - first` sorted elements from the
154
- range \[`first`, `last`) into the range \[`first`, `middle`). The rest
155
- of the elements in the range \[`middle`, `last`) are placed in an
156
- unspecified order.
 
 
 
 
 
 
 
 
 
157
 
158
  *Complexity:* Approximately `(last - first) * log(middle - first)`
159
- comparisons.
 
 
 
 
 
 
 
 
 
 
 
 
 
160
 
161
  #### `partial_sort_copy` <a id="partial.sort.copy">[[partial.sort.copy]]</a>
162
 
163
  ``` cpp
164
  template<class InputIterator, class RandomAccessIterator>
165
- RandomAccessIterator
166
  partial_sort_copy(InputIterator first, InputIterator last,
167
  RandomAccessIterator result_first,
168
  RandomAccessIterator result_last);
169
  template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterator>
170
  RandomAccessIterator
@@ -173,11 +237,11 @@ template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterato
173
  RandomAccessIterator result_first,
174
  RandomAccessIterator result_last);
175
 
176
  template<class InputIterator, class RandomAccessIterator,
177
  class Compare>
178
- RandomAccessIterator
179
  partial_sort_copy(InputIterator first, InputIterator last,
180
  RandomAccessIterator result_first,
181
  RandomAccessIterator result_last,
182
  Compare comp);
183
  template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterator,
@@ -186,398 +250,611 @@ template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterato
186
  partial_sort_copy(ExecutionPolicy&& exec,
187
  ForwardIterator first, ForwardIterator last,
188
  RandomAccessIterator result_first,
189
  RandomAccessIterator result_last,
190
  Compare comp);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
191
  ```
192
 
193
- *Requires:* `RandomAccessIterator` shall satisfy the requirements of
194
- `ValueSwappable` ([[swappable.requirements]]). The type of
195
- `*result_first` shall satisfy the requirements of `MoveConstructible`
196
- (Table  [[tab:moveconstructible]]) and of `MoveAssignable`
197
- (Table  [[tab:moveassignable]]).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
198
 
199
- *Effects:* Places the first
200
- `min(last - first, result_last - result_first)` sorted elements into the
201
- range \[`result_first`,
202
- `result_first + min(last - first, result_last - result_first)`).
203
 
204
- *Returns:* The smaller of: `result_last` or
205
- `result_first + (last - first)`.
206
 
207
- *Complexity:* Approximately
208
- `(last - first) * log(min(last - first, result_last - result_first))`
209
- comparisons.
210
 
211
  #### `is_sorted` <a id="is.sorted">[[is.sorted]]</a>
212
 
213
  ``` cpp
214
  template<class ForwardIterator>
215
- bool is_sorted(ForwardIterator first, ForwardIterator last);
216
  ```
217
 
218
- *Returns:* `is_sorted_until(first, last) == last`
219
 
220
  ``` cpp
221
  template<class ExecutionPolicy, class ForwardIterator>
222
  bool is_sorted(ExecutionPolicy&& exec,
223
  ForwardIterator first, ForwardIterator last);
224
  ```
225
 
226
- *Returns:*
227
- `is_sorted_until(std::forward<ExecutionPolicy>(exec), first, last) == last`
 
 
 
228
 
229
  ``` cpp
230
  template<class ForwardIterator, class Compare>
231
- bool is_sorted(ForwardIterator first, ForwardIterator last,
232
  Compare comp);
233
  ```
234
 
235
- *Returns:* `is_sorted_until(first, last, comp) == last`
 
236
 
237
  ``` cpp
238
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
239
  bool is_sorted(ExecutionPolicy&& exec,
240
  ForwardIterator first, ForwardIterator last,
241
  Compare comp);
242
  ```
243
 
244
- *Returns:*
245
 
246
  ``` cpp
247
- is_sorted_until(std::forward<ExecutionPolicy>(exec), first, last, comp) == last
248
  ```
249
 
 
 
 
 
 
 
 
 
 
 
 
 
250
  ``` cpp
251
  template<class ForwardIterator>
252
- ForwardIterator is_sorted_until(ForwardIterator first, ForwardIterator last);
 
253
  template<class ExecutionPolicy, class ForwardIterator>
254
- ForwardIterator is_sorted_until(ExecutionPolicy&& exec,
 
255
  ForwardIterator first, ForwardIterator last);
256
 
257
  template<class ForwardIterator, class Compare>
258
- ForwardIterator is_sorted_until(ForwardIterator first, ForwardIterator last,
 
259
  Compare comp);
260
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
261
- ForwardIterator is_sorted_until(ExecutionPolicy&& exec,
 
262
  ForwardIterator first, ForwardIterator last,
263
  Compare comp);
 
 
 
 
 
 
 
 
264
  ```
265
 
266
- *Returns:* If `(last - first) < 2`, returns `last`. Otherwise, returns
267
- the last iterator `i` in \[`first`, `last`\] for which the range
268
- \[`first`, `i`) is sorted.
 
 
269
 
270
  *Complexity:* Linear.
271
 
272
  ### Nth element <a id="alg.nth.element">[[alg.nth.element]]</a>
273
 
274
  ``` cpp
275
  template<class RandomAccessIterator>
276
- void nth_element(RandomAccessIterator first, RandomAccessIterator nth,
277
  RandomAccessIterator last);
278
  template<class ExecutionPolicy, class RandomAccessIterator>
279
  void nth_element(ExecutionPolicy&& exec,
280
  RandomAccessIterator first, RandomAccessIterator nth,
281
  RandomAccessIterator last);
282
 
283
  template<class RandomAccessIterator, class Compare>
284
- void nth_element(RandomAccessIterator first, RandomAccessIterator nth,
285
  RandomAccessIterator last, Compare comp);
286
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
287
  void nth_element(ExecutionPolicy&& exec,
288
  RandomAccessIterator first, RandomAccessIterator nth,
289
  RandomAccessIterator last, Compare comp);
 
 
 
 
 
 
290
  ```
291
 
292
- *Requires:* `RandomAccessIterator` shall satisfy the requirements of
293
- `ValueSwappable` ([[swappable.requirements]]). The type of `*first`
294
- shall satisfy the requirements of `MoveConstructible`
295
- (Table  [[tab:moveconstructible]]) and of `MoveAssignable`
296
- (Table  [[tab:moveassignable]]).
 
 
 
 
297
 
298
  *Effects:* After `nth_element` the element in the position pointed to by
299
  `nth` is the element that would be in that position if the whole range
300
- were sorted, unless `nth == last`. Also for every iterator `i` in the
301
- range \[`first`, `nth`) and every iterator `j` in the range \[`nth`,
302
- `last`) it holds that: `!(*j < *i)` or `comp(*j, *i) == false`.
 
 
 
303
 
304
  *Complexity:* For the overloads with no `ExecutionPolicy`, linear on
305
  average. For the overloads with an `ExecutionPolicy`, 𝑂(N) applications
306
  of the predicate, and 𝑂(N log N) swaps, where N = `last - first`.
307
 
 
 
 
 
 
 
 
 
 
 
 
 
 
308
  ### Binary search <a id="alg.binary.search">[[alg.binary.search]]</a>
309
 
310
- All of the algorithms in this section are versions of binary search and
311
- assume that the sequence being searched is partitioned with respect to
312
- an expression formed by binding the search key to an argument of the
313
- implied or explicit comparison function. They work on non-random access
314
- iterators minimizing the number of comparisons, which will be
315
- logarithmic for all types of iterators. They are especially appropriate
316
- for random access iterators, because these algorithms do a logarithmic
317
- number of steps through the data structure. For non-random access
318
- iterators they execute a linear number of steps.
319
 
320
  #### `lower_bound` <a id="lower.bound">[[lower.bound]]</a>
321
 
322
  ``` cpp
323
  template<class ForwardIterator, class T>
324
- ForwardIterator
325
  lower_bound(ForwardIterator first, ForwardIterator last,
326
  const T& value);
327
 
328
  template<class ForwardIterator, class T, class Compare>
329
- ForwardIterator
330
  lower_bound(ForwardIterator first, ForwardIterator last,
331
  const T& value, Compare comp);
 
 
 
 
 
 
 
 
 
 
332
  ```
333
 
334
- *Requires:* The elements `e` of \[`first`, `last`) shall be partitioned
335
- with respect to the expression `e < value` or `comp(e, value)`.
 
 
 
 
336
 
337
  *Returns:* The furthermost iterator `i` in the range \[`first`, `last`\]
338
- such that for every iterator `j` in the range \[`first`, `i`) the
339
- following corresponding conditions hold: `*j < value` or
340
- `comp(*j, value) != false`.
341
 
342
- *Complexity:* At most log₂(`last - first`) + 𝑂(1) comparisons.
 
343
 
344
  #### `upper_bound` <a id="upper.bound">[[upper.bound]]</a>
345
 
346
  ``` cpp
347
  template<class ForwardIterator, class T>
348
- ForwardIterator
349
  upper_bound(ForwardIterator first, ForwardIterator last,
350
  const T& value);
351
 
352
  template<class ForwardIterator, class T, class Compare>
353
- ForwardIterator
354
  upper_bound(ForwardIterator first, ForwardIterator last,
355
  const T& value, Compare comp);
 
 
 
 
 
 
 
 
 
356
  ```
357
 
358
- *Requires:* The elements `e` of \[`first`, `last`) shall be partitioned
359
- with respect to the expression `!(value < e)` or `!comp(value, e)`.
 
 
 
 
360
 
361
  *Returns:* The furthermost iterator `i` in the range \[`first`, `last`\]
362
- such that for every iterator `j` in the range \[`first`, `i`) the
363
- following corresponding conditions hold: `!(value < *j)` or
364
- `comp(value, *j) == false`.
365
 
366
- *Complexity:* At most log₂(`last - first`) + 𝑂(1) comparisons.
 
367
 
368
  #### `equal_range` <a id="equal.range">[[equal.range]]</a>
369
 
370
  ``` cpp
371
  template<class ForwardIterator, class T>
372
- pair<ForwardIterator, ForwardIterator>
373
  equal_range(ForwardIterator first,
374
  ForwardIterator last, const T& value);
375
 
376
  template<class ForwardIterator, class T, class Compare>
377
- pair<ForwardIterator, ForwardIterator>
378
  equal_range(ForwardIterator first,
379
  ForwardIterator last, const T& value,
380
  Compare comp);
 
 
 
 
 
 
 
 
 
 
381
  ```
382
 
383
- *Requires:* The elements `e` of \[`first`, `last`) shall be partitioned
384
- with respect to the expressions `e < value` and `!(value < e)` or
385
- `comp(e, value)` and `!comp(value, e)`. Also, for all elements `e` of
386
- `[first, last)`, `e < value` shall imply `!(value < e)` or
387
- `comp(e, value)` shall imply `!comp(value, e)`.
 
 
 
 
388
 
389
  *Returns:*
390
 
 
391
  ``` cpp
392
- make_pair(lower_bound(first, last, value),
393
- upper_bound(first, last, value))
394
  ```
395
-
396
- or
397
-
398
  ``` cpp
399
- make_pair(lower_bound(first, last, value, comp),
400
- upper_bound(first, last, value, comp))
401
  ```
402
 
403
- *Complexity:* At most 2 * log₂(`last - first`) + 𝑂(1) comparisons.
 
404
 
405
  #### `binary_search` <a id="binary.search">[[binary.search]]</a>
406
 
407
  ``` cpp
408
  template<class ForwardIterator, class T>
409
- bool binary_search(ForwardIterator first, ForwardIterator last,
 
410
  const T& value);
411
 
412
  template<class ForwardIterator, class T, class Compare>
413
- bool binary_search(ForwardIterator first, ForwardIterator last,
 
414
  const T& value, Compare comp);
 
 
 
 
 
 
 
 
 
 
415
  ```
416
 
417
- *Requires:* The elements `e` of \[`first`, `last`) are partitioned with
418
- respect to the expressions `e < value` and `!(value < e)` or
419
- `comp(e, value)` and `!comp(value, e)`. Also, for all elements `e` of
420
- `[first, last)`, `e < value` implies `!(value < e)` or `comp(e, value)`
421
- implies `!comp(value, e)`.
422
 
423
- *Returns:* `true` if there is an iterator `i` in the range \[`first`,
424
- `last`) that satisfies the corresponding conditions:
425
- `!(*i < value) && !(value < *i)` or
426
- `comp(*i, value) == false && comp(value, *i) == false`.
 
 
427
 
428
- *Complexity:* At most log₂(`last - first`) + 𝑂(1) comparisons.
 
 
 
 
 
 
429
 
430
  ### Partitions <a id="alg.partitions">[[alg.partitions]]</a>
431
 
432
  ``` cpp
433
  template<class InputIterator, class Predicate>
434
- bool is_partitioned(InputIterator first, InputIterator last, Predicate pred);
435
  template<class ExecutionPolicy, class ForwardIterator, class Predicate>
436
  bool is_partitioned(ExecutionPolicy&& exec,
437
  ForwardIterator first, ForwardIterator last, Predicate pred);
 
 
 
 
 
 
 
438
  ```
439
 
440
- *Requires:* For the overload with no `ExecutionPolicy`,
441
- `InputIterator`’s value type shall be convertible to `Predicate`’s
442
- argument type. For the overload with an `ExecutionPolicy`,
443
- `ForwardIterator`’s value type shall be convertible to `Predicate`’s
444
- argument type.
445
 
446
- *Returns:* `true` if \[`first`, `last`) is empty or if \[`first`,
447
- `last`) is partitioned by `pred`, i.e. if all elements that satisfy
448
- `pred` appear before those that do not.
449
 
450
- *Complexity:* Linear. At most `last - first` applications of `pred`.
 
451
 
452
  ``` cpp
453
  template<class ForwardIterator, class Predicate>
454
- ForwardIterator
455
  partition(ForwardIterator first, ForwardIterator last, Predicate pred);
456
  template<class ExecutionPolicy, class ForwardIterator, class Predicate>
457
  ForwardIterator
458
  partition(ExecutionPolicy&& exec,
459
  ForwardIterator first, ForwardIterator last, Predicate pred);
 
 
 
 
 
 
 
 
 
 
460
  ```
461
 
462
- *Requires:* `ForwardIterator` shall satisfy the requirements of
463
- `ValueSwappable` ([[swappable.requirements]]).
464
 
465
- *Effects:* Places all the elements in the range \[`first`, `last`) that
466
- satisfy `pred` before all the elements that do not satisfy it.
467
 
468
- *Returns:* An iterator `i` such that for every iterator `j` in the range
469
- \[`first`, `i`) `pred(*j) != false`, and for every iterator `k` in the
470
- range \[`i`, `last`), `pred(*k) == false`.
 
 
 
 
 
 
471
 
472
  *Complexity:* Let N = `last - first`:
473
 
474
  - For the overload with no `ExecutionPolicy`, exactly N applications of
475
- the predicate. At most N / 2 swaps if `ForwardIterator` meets the
476
- `BidirectionalIterator` requirements and at most N swaps otherwise.
 
 
477
  - For the overload with an `ExecutionPolicy`, 𝑂(N log N) swaps and 𝑂(N)
478
  applications of the predicate.
479
 
480
  ``` cpp
481
  template<class BidirectionalIterator, class Predicate>
482
  BidirectionalIterator
483
- stable_partition(BidirectionalIterator first, BidirectionalIterator last,
484
- Predicate pred);
485
  template<class ExecutionPolicy, class BidirectionalIterator, class Predicate>
486
  BidirectionalIterator
487
  stable_partition(ExecutionPolicy&& exec,
488
- BidirectionalIterator first, BidirectionalIterator last,
489
- Predicate pred);
 
 
 
 
 
 
 
 
490
  ```
491
 
492
- *Requires:* `BidirectionalIterator` shall satisfy the requirements of
493
- `ValueSwappable` ([[swappable.requirements]]). The type of `*first`
494
- shall satisfy the requirements of `MoveConstructible`
495
- (Table  [[tab:moveconstructible]]) and of `MoveAssignable`
496
- (Table  [[tab:moveassignable]]).
497
-
498
- *Effects:* Places all the elements in the range \[`first`, `last`) that
499
- satisfy `pred` before all the elements that do not satisfy it.
500
-
501
- *Returns:* An iterator `i` such that for every iterator `j` in the range
502
- \[`first`, `i`), `pred(*j) != false`, and for every iterator `k` in the
503
- range \[`i`, `last`), `pred(*k) == false`. The relative order of the
504
- elements in both groups is preserved.
 
 
 
 
 
 
505
 
506
  *Complexity:* Let N = `last - first`:
507
 
508
- - For the overload with no `ExecutionPolicy`, at most N log N swaps, but
509
- only 𝑂(N) swaps if there is enough extra memory. Exactly N
510
- applications of the predicate.
511
  - For the overload with an `ExecutionPolicy`, 𝑂(N log N) swaps and 𝑂(N)
512
  applications of the predicate.
513
 
514
  ``` cpp
515
  template<class InputIterator, class OutputIterator1,
516
  class OutputIterator2, class Predicate>
517
- pair<OutputIterator1, OutputIterator2>
518
  partition_copy(InputIterator first, InputIterator last,
519
- OutputIterator1 out_true, OutputIterator2 out_false,
520
- Predicate pred);
521
  template<class ExecutionPolicy, class ForwardIterator, class ForwardIterator1,
522
  class ForwardIterator2, class Predicate>
523
  pair<ForwardIterator1, ForwardIterator2>
524
  partition_copy(ExecutionPolicy&& exec,
525
  ForwardIterator first, ForwardIterator last,
526
- ForwardIterator1 out_true, ForwardIterator2 out_false,
527
- Predicate pred);
 
 
 
 
 
 
 
 
 
 
 
 
 
528
  ```
529
 
530
- *Requires:*
 
531
 
532
- - For the overload with no `ExecutionPolicy`, `InputIterator`’s value
533
- type shall be `CopyAssignable` (Table  [[tab:copyassignable]]), and
534
- shall be writable ([[iterator.requirements.general]]) to the
535
- `out_true` and `out_false` `OutputIterator`s, and shall be convertible
536
- to `Predicate`’s argument type.
537
- - For the overload with an `ExecutionPolicy`, `ForwardIterator`’s value
538
- type shall be `CopyAssignable`, and shall be writable to the
539
- `out_true` and `out_false` `ForwardIterator`s, and shall be
540
- convertible to `Predicate`’s argument type. \[*Note 1*: There may be a
541
- performance cost if `ForwardIterator`’s value type is not
542
- `CopyConstructible`. — *end note*]
543
- - For both overloads, the input range shall not overlap with either of
544
- the output ranges.
545
 
546
  *Effects:* For each iterator `i` in \[`first`, `last`), copies `*i` to
547
- the output range beginning with `out_true` if `pred(*i)` is `true`, or
548
- to the output range beginning with `out_false` otherwise.
549
 
550
- *Returns:* A pair `p` such that `p.first` is the end of the output range
551
- beginning at `out_true` and `p.second` is the end of the output range
552
- beginning at `out_false`.
553
 
554
- *Complexity:* Exactly `last - first` applications of `pred`.
 
 
 
555
 
556
  ``` cpp
557
  template<class ForwardIterator, class Predicate>
558
- ForwardIterator partition_point(ForwardIterator first,
559
- ForwardIterator last,
560
- Predicate pred);
 
 
 
 
 
 
 
561
  ```
562
 
563
- *Requires:* `ForwardIterator`’s value type shall be convertible to
564
- `Predicate`’s argument type. \[`first`, `last`) shall be partitioned by
565
- `pred`, i.e. all elements that satisfy `pred` shall appear before those
566
- that do not.
567
 
568
- *Returns:* An iterator `mid` such that `all_of(first, mid, pred)` and
569
- `none_of(mid, last, pred)` are both `true`.
570
 
571
- *Complexity:* 𝑂(log(`last - first`)) applications of `pred`.
 
 
 
 
572
 
573
  ### Merge <a id="alg.merge">[[alg.merge]]</a>
574
 
575
  ``` cpp
576
  template<class InputIterator1, class InputIterator2,
577
  class OutputIterator>
578
- OutputIterator
579
  merge(InputIterator1 first1, InputIterator1 last1,
580
  InputIterator2 first2, InputIterator2 last2,
581
  OutputIterator result);
582
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
583
  class ForwardIterator>
@@ -587,43 +864,67 @@ template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
587
  ForwardIterator2 first2, ForwardIterator2 last2,
588
  ForwardIterator result);
589
 
590
  template<class InputIterator1, class InputIterator2,
591
  class OutputIterator, class Compare>
592
- OutputIterator
593
  merge(InputIterator1 first1, InputIterator1 last1,
594
  InputIterator2 first2, InputIterator2 last2,
595
  OutputIterator result, Compare comp);
596
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
597
  class ForwardIterator, class Compare>
598
  ForwardIterator
599
  merge(ExecutionPolicy&& exec,
600
  ForwardIterator1 first1, ForwardIterator1 last1,
601
  ForwardIterator2 first2, ForwardIterator2 last2,
602
  ForwardIterator result, Compare comp);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
603
  ```
604
 
605
- *Requires:* The ranges \[`first1`, `last1`) and \[`first2`, `last2`)
606
- shall be sorted with respect to `operator<` or `comp`. The resulting
607
- range shall not overlap with either of the original ranges.
608
 
609
- *Effects:*  Copies all the elements of the two ranges \[`first1`,
 
 
 
 
 
610
  `last1`) and \[`first2`, `last2`) into the range \[`result`,
611
- `result_last`), where `result_last` is
612
- `result + (last1 - first1) + (last2 - first2)`, such that the resulting
613
- range satisfies `is_sorted(result, result_last)` or
614
- `is_sorted(result, result_last, comp)`, respectively.
 
 
615
 
616
- *Returns:* `result + (last1 - first1) + (last2 - first2)`.
617
 
618
- *Complexity:* Let N = `(last1 - first1) + (last2 - first2)`:
 
619
 
620
- - For the overloads with no `ExecutionPolicy`, at most N - 1
621
- comparisons.
 
 
622
  - For the overloads with an `ExecutionPolicy`, 𝑂(N) comparisons.
623
 
624
- *Remarks:* Stable ([[algorithm.stable]]).
625
 
626
  ``` cpp
627
  template<class BidirectionalIterator>
628
  void inplace_merge(BidirectionalIterator first,
629
  BidirectionalIterator middle,
@@ -641,81 +942,124 @@ template<class BidirectionalIterator, class Compare>
641
  template<class ExecutionPolicy, class BidirectionalIterator, class Compare>
642
  void inplace_merge(ExecutionPolicy&& exec,
643
  BidirectionalIterator first,
644
  BidirectionalIterator middle,
645
  BidirectionalIterator last, Compare comp);
 
 
 
 
 
646
  ```
647
 
648
- *Requires:* The ranges \[`first`, `middle`) and \[`middle`, `last`)
649
- shall be sorted with respect to `operator<` or `comp`.
650
- `BidirectionalIterator` shall satisfy the requirements of
651
- `ValueSwappable` ([[swappable.requirements]]). The type of `*first`
652
- shall satisfy the requirements of `MoveConstructible`
653
- (Table  [[tab:moveconstructible]]) and of `MoveAssignable`
654
- (Table  [[tab:moveassignable]]).
 
 
655
 
656
  *Effects:* Merges two sorted consecutive ranges \[`first`, `middle`) and
657
  \[`middle`, `last`), putting the result of the merge into the range
658
- \[`first`, `last`). The resulting range will be in non-decreasing order;
659
- that is, for every iterator `i` in \[`first`, `last`) other than
660
- `first`, the condition `*i < *(i - 1)` or, respectively,
661
- `comp(*i, *(i - 1))` will be `false`.
662
 
663
  *Complexity:* Let N = `last - first`:
664
 
665
- - For the overloads with no `ExecutionPolicy`, if enough additional
666
  memory is available, exactly N - 1 comparisons.
667
- - For the overloads with no `ExecutionPolicy` if no additional memory is
668
- available, 𝑂(N log N) comparisons.
669
- - For the overloads with an `ExecutionPolicy`, 𝑂(N log N) comparisons.
670
 
671
- *Remarks:* Stable ([[algorithm.stable]]).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
672
 
673
  ### Set operations on sorted structures <a id="alg.set.operations">[[alg.set.operations]]</a>
674
 
675
- This section defines all the basic set operations on sorted structures.
676
- They also work with `multiset`s ([[multiset]]) containing multiple
677
- copies of equivalent elements. The semantics of the set operations are
678
- generalized to `multiset`s in a standard way by defining `set_union()`
679
- to contain the maximum number of occurrences of every element,
680
- `set_intersection()` to contain the minimum, and so on.
681
 
682
  #### `includes` <a id="includes">[[includes]]</a>
683
 
684
  ``` cpp
685
  template<class InputIterator1, class InputIterator2>
686
- bool includes(InputIterator1 first1, InputIterator1 last1,
687
  InputIterator2 first2, InputIterator2 last2);
688
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
689
  bool includes(ExecutionPolicy&& exec,
690
  ForwardIterator1 first1, ForwardIterator1 last1,
691
  ForwardIterator2 first2, ForwardIterator2 last2);
692
 
693
  template<class InputIterator1, class InputIterator2, class Compare>
694
- bool includes(InputIterator1 first1, InputIterator1 last1,
695
  InputIterator2 first2, InputIterator2 last2,
696
  Compare comp);
697
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Compare>
698
  bool includes(ExecutionPolicy&& exec,
699
  ForwardIterator1 first1, ForwardIterator1 last1,
700
  ForwardIterator2 first2, ForwardIterator2 last2,
701
  Compare comp);
 
 
 
 
 
 
 
 
 
 
 
 
 
702
  ```
703
 
704
- *Returns:* `true` if \[`first2`, `last2`) is empty or if every element
705
- in the range \[`first2`, `last2`) is contained in the range \[`first1`,
706
- `last1`). Returns `false` otherwise.
 
 
 
 
 
 
 
 
 
 
707
 
708
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
709
- comparisons.
710
 
711
  #### `set_union` <a id="set.union">[[set.union]]</a>
712
 
713
  ``` cpp
714
  template<class InputIterator1, class InputIterator2,
715
  class OutputIterator>
716
- OutputIterator
717
  set_union(InputIterator1 first1, InputIterator1 last1,
718
  InputIterator2 first2, InputIterator2 last2,
719
  OutputIterator result);
720
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
721
  class ForwardIterator>
@@ -725,48 +1069,71 @@ template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
725
  ForwardIterator2 first2, ForwardIterator2 last2,
726
  ForwardIterator result);
727
 
728
  template<class InputIterator1, class InputIterator2,
729
  class OutputIterator, class Compare>
730
- OutputIterator
731
  set_union(InputIterator1 first1, InputIterator1 last1,
732
  InputIterator2 first2, InputIterator2 last2,
733
  OutputIterator result, Compare comp);
734
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
735
  class ForwardIterator, class Compare>
736
  ForwardIterator
737
  set_union(ExecutionPolicy&& exec,
738
  ForwardIterator1 first1, ForwardIterator1 last1,
739
  ForwardIterator2 first2, ForwardIterator2 last2,
740
  ForwardIterator result, Compare comp);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
741
  ```
742
 
743
- *Requires:* The resulting range shall not overlap with either of the
 
 
 
 
 
744
  original ranges.
745
 
746
  *Effects:* Constructs a sorted union of the elements from the two
747
  ranges; that is, the set of elements that are present in one or both of
748
  the ranges.
749
 
750
- *Returns:* The end of the constructed range.
 
 
 
 
751
 
752
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
753
- comparisons.
754
 
755
- *Remarks:* If \[`first1`, `last1`) contains m elements that are
756
- equivalent to each other and \[`first2`, `last2`) contains n elements
757
- that are equivalent to them, then all m elements from the first range
758
- shall be copied to the output range, in order, and then max(n - m, 0)
759
- elements from the second range shall be copied to the output range, in
760
- order.
761
 
762
  #### `set_intersection` <a id="set.intersection">[[set.intersection]]</a>
763
 
764
  ``` cpp
765
  template<class InputIterator1, class InputIterator2,
766
  class OutputIterator>
767
- OutputIterator
768
  set_intersection(InputIterator1 first1, InputIterator1 last1,
769
  InputIterator2 first2, InputIterator2 last2,
770
  OutputIterator result);
771
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
772
  class ForwardIterator>
@@ -776,46 +1143,69 @@ template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
776
  ForwardIterator2 first2, ForwardIterator2 last2,
777
  ForwardIterator result);
778
 
779
  template<class InputIterator1, class InputIterator2,
780
  class OutputIterator, class Compare>
781
- OutputIterator
782
  set_intersection(InputIterator1 first1, InputIterator1 last1,
783
  InputIterator2 first2, InputIterator2 last2,
784
  OutputIterator result, Compare comp);
785
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
786
  class ForwardIterator, class Compare>
787
  ForwardIterator
788
  set_intersection(ExecutionPolicy&& exec,
789
  ForwardIterator1 first1, ForwardIterator1 last1,
790
  ForwardIterator2 first2, ForwardIterator2 last2,
791
  ForwardIterator result, Compare comp);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
792
  ```
793
 
794
- *Requires:* The resulting range shall not overlap with either of the
 
 
 
 
 
795
  original ranges.
796
 
797
  *Effects:* Constructs a sorted intersection of the elements from the two
798
  ranges; that is, the set of elements that are present in both of the
799
  ranges.
800
 
801
- *Returns:* The end of the constructed range.
 
 
 
 
802
 
803
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
804
- comparisons.
805
 
806
- *Remarks:* If \[`first1`, `last1`) contains m elements that are
807
- equivalent to each other and \[`first2`, `last2`) contains n elements
808
- that are equivalent to them, the first min(m, n) elements shall be
809
- copied from the first range to the output range, in order.
810
 
811
  #### `set_difference` <a id="set.difference">[[set.difference]]</a>
812
 
813
  ``` cpp
814
  template<class InputIterator1, class InputIterator2,
815
  class OutputIterator>
816
- OutputIterator
817
  set_difference(InputIterator1 first1, InputIterator1 last1,
818
  InputIterator2 first2, InputIterator2 last2,
819
  OutputIterator result);
820
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
821
  class ForwardIterator>
@@ -825,46 +1215,69 @@ template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
825
  ForwardIterator2 first2, ForwardIterator2 last2,
826
  ForwardIterator result);
827
 
828
  template<class InputIterator1, class InputIterator2,
829
  class OutputIterator, class Compare>
830
- OutputIterator
831
  set_difference(InputIterator1 first1, InputIterator1 last1,
832
  InputIterator2 first2, InputIterator2 last2,
833
  OutputIterator result, Compare comp);
834
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
835
  class ForwardIterator, class Compare>
836
  ForwardIterator
837
  set_difference(ExecutionPolicy&& exec,
838
  ForwardIterator1 first1, ForwardIterator1 last1,
839
  ForwardIterator2 first2, ForwardIterator2 last2,
840
  ForwardIterator result, Compare comp);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
841
  ```
842
 
843
- *Requires:* The resulting range shall not overlap with either of the
 
 
 
 
 
844
  original ranges.
845
 
846
  *Effects:* Copies the elements of the range \[`first1`, `last1`) which
847
  are not present in the range \[`first2`, `last2`) to the range beginning
848
  at `result`. The elements in the constructed range are sorted.
849
 
850
- *Returns:* The end of the constructed range.
 
 
 
 
851
 
852
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
853
- comparisons.
854
 
855
  *Remarks:* If \[`first1`, `last1`) contains m elements that are
856
  equivalent to each other and \[`first2`, `last2`) contains n elements
857
  that are equivalent to them, the last max(m - n, 0) elements from
858
- \[`first1`, `last1`) shall be copied to the output range.
859
 
860
  #### `set_symmetric_difference` <a id="set.symmetric.difference">[[set.symmetric.difference]]</a>
861
 
862
  ``` cpp
863
  template<class InputIterator1, class InputIterator2,
864
  class OutputIterator>
865
- OutputIterator
866
  set_symmetric_difference(InputIterator1 first1, InputIterator1 last1,
867
  InputIterator2 first2, InputIterator2 last2,
868
  OutputIterator result);
869
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
870
  class ForwardIterator>
@@ -874,308 +1287,497 @@ template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
874
  ForwardIterator2 first2, ForwardIterator2 last2,
875
  ForwardIterator result);
876
 
877
  template<class InputIterator1, class InputIterator2,
878
  class OutputIterator, class Compare>
879
- OutputIterator
880
  set_symmetric_difference(InputIterator1 first1, InputIterator1 last1,
881
  InputIterator2 first2, InputIterator2 last2,
882
  OutputIterator result, Compare comp);
883
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
884
  class ForwardIterator, class Compare>
885
  ForwardIterator
886
  set_symmetric_difference(ExecutionPolicy&& exec,
887
  ForwardIterator1 first1, ForwardIterator1 last1,
888
  ForwardIterator2 first2, ForwardIterator2 last2,
889
  ForwardIterator result, Compare comp);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
890
  ```
891
 
892
- *Requires:* The resulting range shall not overlap with either of the
 
 
 
 
 
893
  original ranges.
894
 
895
  *Effects:* Copies the elements of the range \[`first1`, `last1`) that
896
  are not present in the range \[`first2`, `last2`), and the elements of
897
  the range \[`first2`, `last2`) that are not present in the range
898
  \[`first1`, `last1`) to the range beginning at `result`. The elements in
899
  the constructed range are sorted.
900
 
901
- *Returns:* The end of the constructed range.
 
 
 
 
902
 
903
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
904
- comparisons.
905
 
906
- *Remarks:* If \[`first1`, `last1`) contains m elements that are
907
- equivalent to each other and \[`first2`, `last2`) contains n elements
908
- that are equivalent to them, then |m - n| of those elements shall be
909
- copied to the output range: the last m - n of these elements from
910
- \[`first1`, `last1`) if m > n, and the last n - m of these elements from
911
- \[`first2`, `last2`) if m < n.
 
912
 
913
  ### Heap operations <a id="alg.heap.operations">[[alg.heap.operations]]</a>
914
 
915
- A *heap* is a particular organization of elements in a range between two
916
- random access iterators \[`a`, `b`) such that:
 
917
 
918
  - With `N = b - a`, for all i, 0 < i < N,
919
- `comp(a[\left \lfloor{\frac{i - 1}{2}}\right \rfloor], a[i])` is
920
- `false`.
921
- - `*a` may be removed by `pop_heap()`, or a new element added by
922
- `push_heap()`, in 𝑂(log N) time.
923
 
924
  These properties make heaps useful as priority queues.
925
 
926
- `make_heap()`
927
-
928
- converts a range into a heap and `sort_heap()` turns a heap into a
929
- sorted sequence.
930
 
931
  #### `push_heap` <a id="push.heap">[[push.heap]]</a>
932
 
933
  ``` cpp
934
  template<class RandomAccessIterator>
935
- void push_heap(RandomAccessIterator first, RandomAccessIterator last);
936
 
937
  template<class RandomAccessIterator, class Compare>
938
- void push_heap(RandomAccessIterator first, RandomAccessIterator last,
939
  Compare comp);
 
 
 
 
 
 
 
 
 
 
940
  ```
941
 
942
- *Requires:* The range \[`first`, `last - 1`) shall be a valid heap. The
943
- type of `*first` shall satisfy the `MoveConstructible` requirements
944
- (Table  [[tab:moveconstructible]]) and the `MoveAssignable` requirements
945
- (Table  [[tab:moveassignable]]).
 
 
 
 
946
 
947
  *Effects:* Places the value in the location `last - 1` into the
948
  resulting heap \[`first`, `last`).
949
 
950
- *Complexity:* At most log(`last - first`) comparisons.
 
 
 
951
 
952
  #### `pop_heap` <a id="pop.heap">[[pop.heap]]</a>
953
 
954
  ``` cpp
955
  template<class RandomAccessIterator>
956
- void pop_heap(RandomAccessIterator first, RandomAccessIterator last);
957
 
958
  template<class RandomAccessIterator, class Compare>
959
- void pop_heap(RandomAccessIterator first, RandomAccessIterator last,
960
  Compare comp);
 
 
 
 
 
 
 
 
 
 
961
  ```
962
 
963
- *Requires:* The range \[`first`, `last`) shall be a valid non-empty
964
- heap. `RandomAccessIterator` shall satisfy the requirements of
965
- `ValueSwappable` ([[swappable.requirements]]). The type of `*first`
966
- shall satisfy the requirements of `MoveConstructible`
967
- (Table  [[tab:moveconstructible]]) and of `MoveAssignable`
968
- (Table  [[tab:moveassignable]]).
 
 
 
969
 
970
  *Effects:* Swaps the value in the location `first` with the value in the
971
- location `last - 1` and makes \[`first`, `last - 1`) into a heap.
 
972
 
973
- *Complexity:* At most 2 log(`last - first`) comparisons.
 
 
 
974
 
975
  #### `make_heap` <a id="make.heap">[[make.heap]]</a>
976
 
977
  ``` cpp
978
  template<class RandomAccessIterator>
979
- void make_heap(RandomAccessIterator first, RandomAccessIterator last);
980
 
981
  template<class RandomAccessIterator, class Compare>
982
- void make_heap(RandomAccessIterator first, RandomAccessIterator last,
983
  Compare comp);
 
 
 
 
 
 
 
 
 
 
984
  ```
985
 
986
- *Requires:* The type of `*first` shall satisfy the `MoveConstructible`
987
- requirements (Table  [[tab:moveconstructible]]) and the `MoveAssignable`
988
- requirements (Table  [[tab:moveassignable]]).
989
 
990
- *Effects:* Constructs a heap out of the range \[`first`, `last`).
 
 
 
991
 
992
- *Complexity:* At most 3(`last - first`) comparisons.
 
 
 
 
 
 
993
 
994
  #### `sort_heap` <a id="sort.heap">[[sort.heap]]</a>
995
 
996
  ``` cpp
997
  template<class RandomAccessIterator>
998
- void sort_heap(RandomAccessIterator first, RandomAccessIterator last);
999
 
1000
  template<class RandomAccessIterator, class Compare>
1001
- void sort_heap(RandomAccessIterator first, RandomAccessIterator last,
1002
  Compare comp);
 
 
 
 
 
 
 
 
 
 
1003
  ```
1004
 
1005
- *Requires:* The range \[`first`, `last`) shall be a valid heap.
1006
- `RandomAccessIterator` shall satisfy the requirements of
1007
- `ValueSwappable` ([[swappable.requirements]]). The type of `*first`
1008
- shall satisfy the requirements of `MoveConstructible`
1009
- (Table  [[tab:moveconstructible]]) and of `MoveAssignable`
1010
- (Table  [[tab:moveassignable]]).
1011
 
1012
- *Effects:* Sorts elements in the heap \[`first`, `last`).
 
 
 
 
 
1013
 
1014
- *Complexity:* At most N log N comparisons, where N = `last - first`.
 
 
 
 
 
 
1015
 
1016
  #### `is_heap` <a id="is.heap">[[is.heap]]</a>
1017
 
1018
  ``` cpp
1019
  template<class RandomAccessIterator>
1020
- bool is_heap(RandomAccessIterator first, RandomAccessIterator last);
1021
  ```
1022
 
1023
- *Returns:* `is_heap_until(first, last) == last`
1024
 
1025
  ``` cpp
1026
  template<class ExecutionPolicy, class RandomAccessIterator>
1027
  bool is_heap(ExecutionPolicy&& exec,
1028
  RandomAccessIterator first, RandomAccessIterator last);
1029
  ```
1030
 
1031
- *Returns:*
1032
- `is_heap_until(std::forward<ExecutionPolicy>(exec), first, last) == last`
 
 
 
1033
 
1034
  ``` cpp
1035
  template<class RandomAccessIterator, class Compare>
1036
- bool is_heap(RandomAccessIterator first, RandomAccessIterator last, Compare comp);
 
1037
  ```
1038
 
1039
- *Returns:* `is_heap_until(first, last, comp) == last`
 
1040
 
1041
  ``` cpp
1042
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
1043
  bool is_heap(ExecutionPolicy&& exec,
1044
- RandomAccessIterator first, RandomAccessIterator last, Compare comp);
 
1045
  ```
1046
 
1047
- *Returns:*
1048
 
1049
  ``` cpp
1050
- is_heap_until(std::forward<ExecutionPolicy>(exec), first, last, comp) == last
1051
  ```
1052
 
 
 
 
 
 
 
 
 
 
 
 
 
1053
  ``` cpp
1054
  template<class RandomAccessIterator>
1055
- RandomAccessIterator is_heap_until(RandomAccessIterator first, RandomAccessIterator last);
 
1056
  template<class ExecutionPolicy, class RandomAccessIterator>
1057
- RandomAccessIterator is_heap_until(ExecutionPolicy&& exec,
 
1058
  RandomAccessIterator first, RandomAccessIterator last);
1059
 
1060
  template<class RandomAccessIterator, class Compare>
1061
- RandomAccessIterator is_heap_until(RandomAccessIterator first, RandomAccessIterator last,
 
1062
  Compare comp);
1063
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
1064
- RandomAccessIterator is_heap_until(ExecutionPolicy&& exec,
 
1065
  RandomAccessIterator first, RandomAccessIterator last,
1066
  Compare comp);
 
 
 
 
 
 
 
 
1067
  ```
1068
 
1069
- *Returns:* If `(last - first) < 2`, returns `last`. Otherwise, returns
1070
- the last iterator `i` in \[`first`, `last`\] for which the range
1071
- \[`first`, `i`) is a heap.
 
 
1072
 
1073
  *Complexity:* Linear.
1074
 
1075
  ### Minimum and maximum <a id="alg.min.max">[[alg.min.max]]</a>
1076
 
1077
  ``` cpp
1078
- template<class T> constexpr const T& min(const T& a, const T& b);
 
1079
  template<class T, class Compare>
1080
  constexpr const T& min(const T& a, const T& b, Compare comp);
 
 
 
 
1081
  ```
1082
 
1083
- *Requires:* For the first form, type `T` shall be `LessThanComparable`
1084
- (Table  [[tab:lessthancomparable]]).
1085
 
1086
  *Returns:* The smaller value.
1087
 
1088
  *Remarks:* Returns the first argument when the arguments are equivalent.
 
 
1089
 
1090
- *Complexity:* Exactly one comparison.
 
1091
 
1092
  ``` cpp
1093
  template<class T>
1094
- constexpr T min(initializer_list<T> t);
1095
  template<class T, class Compare>
1096
- constexpr T min(initializer_list<T> t, Compare comp);
 
 
 
 
 
 
 
 
 
1097
  ```
1098
 
1099
- *Requires:* `T` shall be `CopyConstructible` and `t.size() > 0`. For the
1100
- first form, type `T` shall be `LessThanComparable`.
 
 
1101
 
1102
- *Returns:* The smallest value in the initializer_list.
1103
 
1104
- *Remarks:* Returns a copy of the leftmost argument when several
1105
- arguments are equivalent to the smallest. 
 
 
1106
 
1107
- *Complexity:* Exactly `t.size() - 1` comparisons.
 
1108
 
1109
  ``` cpp
1110
- template<class T> constexpr const T& max(const T& a, const T& b);
 
1111
  template<class T, class Compare>
1112
  constexpr const T& max(const T& a, const T& b, Compare comp);
 
 
 
 
1113
  ```
1114
 
1115
- *Requires:* For the first form, type `T` shall be `LessThanComparable`
1116
- (Table  [[tab:lessthancomparable]]).
1117
 
1118
  *Returns:* The larger value.
1119
 
1120
  *Remarks:* Returns the first argument when the arguments are equivalent.
 
 
1121
 
1122
- *Complexity:* Exactly one comparison.
 
1123
 
1124
  ``` cpp
1125
  template<class T>
1126
- constexpr T max(initializer_list<T> t);
1127
  template<class T, class Compare>
1128
- constexpr T max(initializer_list<T> t, Compare comp);
 
 
 
 
 
 
 
 
 
1129
  ```
1130
 
1131
- *Requires:* `T` shall be `CopyConstructible` and `t.size() > 0`. For the
1132
- first form, type `T` shall be `LessThanComparable`.
 
 
1133
 
1134
- *Returns:* The largest value in the initializer_list.
1135
 
1136
- *Remarks:* Returns a copy of the leftmost argument when several
1137
- arguments are equivalent to the largest.
 
 
1138
 
1139
- *Complexity:* Exactly `t.size() - 1` comparisons.
 
1140
 
1141
  ``` cpp
1142
- template<class T> constexpr pair<const T&, const T&> minmax(const T& a, const T& b);
 
1143
  template<class T, class Compare>
1144
  constexpr pair<const T&, const T&> minmax(const T& a, const T& b, Compare comp);
 
 
 
 
 
1145
  ```
1146
 
1147
- *Requires:* For the first form, type `T` shall be `LessThanComparable`
1148
- (Table  [[tab:lessthancomparable]]).
1149
 
1150
- *Returns:* `pair<const T&, const T&>(b, a)` if `b` is smaller than `a`,
1151
- and `pair<const T&, const T&>(a, b)` otherwise.
1152
 
1153
- *Remarks:* Returns `pair<const T&, const T&>(a, b)` when the arguments
1154
- are equivalent.
1155
 
1156
- *Complexity:* Exactly one comparison.
 
1157
 
1158
  ``` cpp
1159
  template<class T>
1160
  constexpr pair<T, T> minmax(initializer_list<T> t);
1161
  template<class T, class Compare>
1162
  constexpr pair<T, T> minmax(initializer_list<T> t, Compare comp);
 
 
 
 
 
 
 
 
 
 
1163
  ```
1164
 
1165
- *Requires:* `T` shall be `CopyConstructible` and `t.size() > 0`. For the
1166
- first form, type `T` shall be `LessThanComparable`.
 
 
1167
 
1168
- *Returns:* `pair<T, T>(x, y)`, where `x` has the smallest and `y` has
1169
- the largest value in the initializer list.
 
1170
 
1171
- *Remarks:* `x` is a copy of the leftmost argument when several arguments
1172
- are equivalent to the smallest. `y` is a copy of the rightmost argument
1173
- when several arguments are equivalent to the largest.
1174
 
1175
- *Complexity:* At most (3/2)`t.size()` applications of the corresponding
1176
- predicate.
 
1177
 
1178
  ``` cpp
1179
  template<class ForwardIterator>
1180
  constexpr ForwardIterator min_element(ForwardIterator first, ForwardIterator last);
1181
 
@@ -1188,19 +1790,34 @@ template<class ForwardIterator, class Compare>
1188
  Compare comp);
1189
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
1190
  ForwardIterator min_element(ExecutionPolicy&& exec,
1191
  ForwardIterator first, ForwardIterator last,
1192
  Compare comp);
 
 
 
 
 
 
 
 
1193
  ```
1194
 
 
 
 
1195
  *Returns:* The first iterator `i` in the range \[`first`, `last`) such
1196
- that for every iterator `j` in the range \[`first`, `last`) the
1197
- following corresponding conditions hold: `!(*j < *i)` or
1198
- `comp(*j, *i) == false`. Returns `last` if `first == last`.
1199
 
1200
- *Complexity:* Exactly max(`last - first - 1`, 0) applications of the
1201
- corresponding comparisons.
 
 
 
 
 
 
1202
 
1203
  ``` cpp
1204
  template<class ForwardIterator>
1205
  constexpr ForwardIterator max_element(ForwardIterator first, ForwardIterator last);
1206
  template<class ExecutionPolicy, class ForwardIterator>
@@ -1212,19 +1829,34 @@ template<class ForwardIterator, class Compare>
1212
  Compare comp);
1213
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
1214
  ForwardIterator max_element(ExecutionPolicy&& exec,
1215
  ForwardIterator first, ForwardIterator last,
1216
  Compare comp);
 
 
 
 
 
 
 
 
1217
  ```
1218
 
 
 
 
1219
  *Returns:* The first iterator `i` in the range \[`first`, `last`) such
1220
- that for every iterator `j` in the range \[`first`, `last`) the
1221
- following corresponding conditions hold: `!(*i < *j)` or
1222
- `comp(*i, *j) == false`. Returns `last` if `first == last`.
1223
 
1224
- *Complexity:* Exactly max(`last - first - 1`, 0) applications of the
1225
- corresponding comparisons.
 
 
 
 
 
 
1226
 
1227
  ``` cpp
1228
  template<class ForwardIterator>
1229
  constexpr pair<ForwardIterator, ForwardIterator>
1230
  minmax_element(ForwardIterator first, ForwardIterator last);
@@ -1238,147 +1870,257 @@ template<class ForwardIterator, class Compare>
1238
  minmax_element(ForwardIterator first, ForwardIterator last, Compare comp);
1239
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
1240
  pair<ForwardIterator, ForwardIterator>
1241
  minmax_element(ExecutionPolicy&& exec,
1242
  ForwardIterator first, ForwardIterator last, Compare comp);
 
 
 
 
 
 
 
 
 
1243
  ```
1244
 
1245
- *Returns:* `make_pair(first, first)` if \[`first`, `last`) is empty,
1246
- otherwise `make_pair(m, M)`, where `m` is the first iterator in
1247
- \[`first`, `last`) such that no iterator in the range refers to a
1248
- smaller element, and where `M` is the last iterator[^5] in \[`first`,
1249
- `last`) such that no iterator in the range refers to a larger element.
1250
 
1251
- *Complexity:* At most
1252
- $\max(\bigl\lfloor{\frac{3}{2}} (N-1)\bigr\rfloor, 0)$ applications of
1253
- the corresponding predicate, where N is `last - first`.
1254
 
1255
  ### Bounded value <a id="alg.clamp">[[alg.clamp]]</a>
1256
 
1257
  ``` cpp
1258
  template<class T>
1259
  constexpr const T& clamp(const T& v, const T& lo, const T& hi);
1260
  template<class T, class Compare>
1261
  constexpr const T& clamp(const T& v, const T& lo, const T& hi, Compare comp);
 
 
 
 
1262
  ```
1263
 
1264
- *Requires:* The value of `lo` shall be no greater than `hi`. For the
1265
- first form, type `T` shall be `LessThanComparable`
1266
- (Table  [[tab:lessthancomparable]]).
1267
 
1268
- *Returns:* `lo` if `v` is less than `lo`, `hi` if `hi` is less than `v`,
1269
- otherwise `v`.
 
 
 
 
1270
 
1271
  [*Note 1*: If NaN is avoided, `T` can be a floating-point
1272
  type. — *end note*]
1273
 
1274
- *Complexity:* At most two comparisons.
 
1275
 
1276
  ### Lexicographical comparison <a id="alg.lex.comparison">[[alg.lex.comparison]]</a>
1277
 
1278
  ``` cpp
1279
  template<class InputIterator1, class InputIterator2>
1280
- bool
1281
  lexicographical_compare(InputIterator1 first1, InputIterator1 last1,
1282
  InputIterator2 first2, InputIterator2 last2);
1283
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
1284
  bool
1285
  lexicographical_compare(ExecutionPolicy&& exec,
1286
  ForwardIterator1 first1, ForwardIterator1 last1,
1287
  ForwardIterator2 first2, ForwardIterator2 last2);
1288
 
1289
  template<class InputIterator1, class InputIterator2, class Compare>
1290
- bool
1291
  lexicographical_compare(InputIterator1 first1, InputIterator1 last1,
1292
  InputIterator2 first2, InputIterator2 last2,
1293
  Compare comp);
1294
- template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Compare>
 
1295
  bool
1296
  lexicographical_compare(ExecutionPolicy&& exec,
1297
  ForwardIterator1 first1, ForwardIterator1 last1,
1298
  ForwardIterator2 first2, ForwardIterator2 last2,
1299
  Compare comp);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1300
  ```
1301
 
1302
- *Returns:* `true` if the sequence of elements defined by the range
1303
- \[`first1`, `last1`) is lexicographically less than the sequence of
1304
- elements defined by the range \[`first2`, `last2`) and `false`
1305
- otherwise.
1306
 
1307
  *Complexity:* At most 2 min(`last1 - first1`, `last2 - first2`)
1308
- applications of the corresponding comparison.
 
1309
 
1310
  *Remarks:* If two sequences have the same number of elements and their
1311
  corresponding elements (if any) are equivalent, then neither sequence is
1312
- lexicographically less than the other. If one sequence is a prefix of
1313
- the other, then the shorter sequence is lexicographically less than the
1314
- longer sequence. Otherwise, the lexicographical comparison of the
1315
- sequences yields the same result as the comparison of the first
1316
  corresponding pair of elements that are not equivalent.
1317
 
1318
  [*Example 1*:
1319
 
1320
- The following sample implementation satisfies these requirements:
 
1321
 
1322
  ``` cpp
1323
  for ( ; first1 != last1 && first2 != last2 ; ++first1, (void) ++first2) {
1324
- if (*first1 < *first2) return true;
1325
- if (*first2 < *first1) return false;
1326
  }
1327
  return first1 == last1 && first2 != last2;
1328
  ```
1329
 
1330
  — *end example*]
1331
 
1332
  [*Note 1*: An empty sequence is lexicographically less than any
1333
  non-empty sequence, but not less than any empty sequence. — *end note*]
1334
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1335
  ### Permutation generators <a id="alg.permutation.generators">[[alg.permutation.generators]]</a>
1336
 
1337
  ``` cpp
1338
  template<class BidirectionalIterator>
1339
- bool next_permutation(BidirectionalIterator first,
1340
  BidirectionalIterator last);
1341
 
1342
  template<class BidirectionalIterator, class Compare>
1343
- bool next_permutation(BidirectionalIterator first,
1344
  BidirectionalIterator last, Compare comp);
 
 
 
 
 
 
 
 
 
 
 
1345
  ```
1346
 
1347
- *Requires:* `BidirectionalIterator` shall satisfy the requirements of
1348
- `ValueSwappable` ([[swappable.requirements]]).
 
 
 
 
1349
 
1350
  *Effects:* Takes a sequence defined by the range \[`first`, `last`) and
1351
  transforms it into the next permutation. The next permutation is found
1352
  by assuming that the set of all permutations is lexicographically sorted
1353
- with respect to `operator<` or `comp`.
 
 
1354
 
1355
- *Returns:* `true` if such a permutation exists. Otherwise, it transforms
1356
- the sequence into the smallest permutation, that is, the ascendingly
1357
- sorted one, and returns `false`.
 
 
1358
 
1359
  *Complexity:* At most `(last - first) / 2` swaps.
1360
 
1361
  ``` cpp
1362
  template<class BidirectionalIterator>
1363
- bool prev_permutation(BidirectionalIterator first,
1364
  BidirectionalIterator last);
1365
 
1366
  template<class BidirectionalIterator, class Compare>
1367
- bool prev_permutation(BidirectionalIterator first,
1368
  BidirectionalIterator last, Compare comp);
 
 
 
 
 
 
 
 
 
 
 
1369
  ```
1370
 
1371
- *Requires:* `BidirectionalIterator` shall satisfy the requirements of
1372
- `ValueSwappable` ([[swappable.requirements]]).
 
 
 
 
1373
 
1374
  *Effects:* Takes a sequence defined by the range \[`first`, `last`) and
1375
  transforms it into the previous permutation. The previous permutation is
1376
  found by assuming that the set of all permutations is lexicographically
1377
- sorted with respect to `operator<` or `comp`.
 
 
1378
 
1379
- *Returns:* `true` if such a permutation exists. Otherwise, it transforms
1380
- the sequence into the largest permutation, that is, the descendingly
1381
- sorted one, and returns `false`.
 
 
1382
 
1383
  *Complexity:* At most `(last - first) / 2` swaps.
1384
 
 
1
  ## Sorting and related operations <a id="alg.sorting">[[alg.sorting]]</a>
2
 
3
+ The operations in  [[alg.sorting]] defined directly in namespace `std`
4
+ have two versions: one that takes a function object of type `Compare`
5
+ and one that uses an `operator<`.
6
 
7
+ `Compare` is a function object type [[function.objects]] that meets the
8
+ requirements for a template parameter named `BinaryPredicate` 
9
+ [[algorithms.requirements]]. The return value of the function call
10
+ operation applied to an object of type `Compare`, when contextually
11
+ converted to `bool` [[conv]], yields `true` if the first argument of the
12
+ call is less than the second, and `false` otherwise. `Compare comp` is
13
+ used throughout for algorithms assuming an ordering relation.
 
 
14
 
15
  For all algorithms that take `Compare`, there is a version that uses
16
  `operator<` instead. That is, `comp(*i, *j) != false` defaults to
17
  `*i < *j != false`. For algorithms other than those described in 
18
  [[alg.binary.search]], `comp` shall induce a strict weak ordering on the
 
30
 
31
  [*Note 1*:
32
 
33
  Under these conditions, it can be shown that
34
 
35
+ - `equiv` is an equivalence relation,
36
  - `comp` induces a well-defined relation on the equivalence classes
37
+ determined by `equiv`, and
38
+ - the induced relation is a strict total ordering.
39
 
40
  — *end note*]
41
 
42
+ A sequence is *sorted with respect to a `comp` and `proj`* for a
43
+ comparator and projection `comp` and `proj` if for every iterator `i`
44
+ pointing to the sequence and every non-negative integer `n` such that
45
+ `i + n` is a valid iterator pointing to an element of the sequence,
46
+
47
+ ``` cpp
48
+ bool(invoke(comp, invoke(proj, *(i + n)), invoke(proj, *i)))
49
+ ```
50
+
51
+ is `false`.
52
 
53
  A sequence \[`start`, `finish`) is *partitioned with respect to an
54
  expression* `f(e)` if there exists an integer `n` such that for all
55
  `0 <= i < (finish - start)`, `f(*(start + i))` is `true` if and only if
56
  `i < n`.
 
66
 
67
  #### `sort` <a id="sort">[[sort]]</a>
68
 
69
  ``` cpp
70
  template<class RandomAccessIterator>
71
+ constexpr void sort(RandomAccessIterator first, RandomAccessIterator last);
72
  template<class ExecutionPolicy, class RandomAccessIterator>
73
  void sort(ExecutionPolicy&& exec,
74
  RandomAccessIterator first, RandomAccessIterator last);
75
 
76
  template<class RandomAccessIterator, class Compare>
77
+ constexpr void sort(RandomAccessIterator first, RandomAccessIterator last,
78
  Compare comp);
79
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
80
  void sort(ExecutionPolicy&& exec,
81
  RandomAccessIterator first, RandomAccessIterator last,
82
  Compare comp);
83
+
84
+ template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
85
+ class Proj = identity>
86
+ requires sortable<I, Comp, Proj>
87
+ constexpr I
88
+ ranges::sort(I first, S last, Comp comp = {}, Proj proj = {});
89
+ template<random_access_range R, class Comp = ranges::less, class Proj = identity>
90
+ requires sortable<iterator_t<R>, Comp, Proj>
91
+ constexpr borrowed_iterator_t<R>
92
+ ranges::sort(R&& r, Comp comp = {}, Proj proj = {});
93
  ```
94
 
95
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
96
+ no parameters by those names.
 
 
 
97
 
98
+ *Preconditions:* For the overloads in namespace `std`,
99
+ `RandomAccessIterator` meets the *Cpp17ValueSwappable*
100
+ requirements [[swappable.requirements]] and the type of `*first` meets
101
+ the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
102
+ *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
103
 
104
+ *Effects:* Sorts the elements in the range \[`first`, `last`) with
105
+ respect to `comp` and `proj`.
106
+
107
+ *Returns:* `last` for the overloads in namespace `ranges`.
108
+
109
+ *Complexity:* Let N be `last - first`. 𝑂(N log N) comparisons and
110
+ projections.
111
 
112
  #### `stable_sort` <a id="stable.sort">[[stable.sort]]</a>
113
 
114
  ``` cpp
115
  template<class RandomAccessIterator>
 
123
  Compare comp);
124
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
125
  void stable_sort(ExecutionPolicy&& exec,
126
  RandomAccessIterator first, RandomAccessIterator last,
127
  Compare comp);
128
+
129
+ template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
130
+ class Proj = identity>
131
+ requires sortable<I, Comp, Proj>
132
+ I ranges::stable_sort(I first, S last, Comp comp = {}, Proj proj = {});
133
+ template<random_access_range R, class Comp = ranges::less, class Proj = identity>
134
+ requires sortable<iterator_t<R>, Comp, Proj>
135
+ borrowed_iterator_t<R>
136
+ ranges::stable_sort(R&& r, Comp comp = {}, Proj proj = {});
137
  ```
138
 
139
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
140
+ no parameters by those names.
 
 
 
141
 
142
+ *Preconditions:* For the overloads in namespace `std`,
143
+ `RandomAccessIterator` meets the *Cpp17ValueSwappable*
144
+ requirements [[swappable.requirements]] and the type of `*first` meets
145
+ the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
146
+ *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
147
 
148
+ *Effects:* Sorts the elements in the range \[`first`, `last`) with
149
+ respect to `comp` and `proj`.
150
 
151
+ *Returns:* `last` for the overloads in namespace `ranges`.
152
+
153
+ *Complexity:* Let N be `last - first`. If enough extra memory is
154
+ available, N log(N) comparisons. Otherwise, at most N log²(N)
155
+ comparisons. In either case, twice as many projections as the number of
156
+ comparisons.
157
+
158
+ *Remarks:* Stable [[algorithm.stable]].
159
 
160
  #### `partial_sort` <a id="partial.sort">[[partial.sort]]</a>
161
 
162
  ``` cpp
163
  template<class RandomAccessIterator>
164
+ constexpr void partial_sort(RandomAccessIterator first,
165
  RandomAccessIterator middle,
166
  RandomAccessIterator last);
167
  template<class ExecutionPolicy, class RandomAccessIterator>
168
  void partial_sort(ExecutionPolicy&& exec,
169
  RandomAccessIterator first,
170
  RandomAccessIterator middle,
171
  RandomAccessIterator last);
172
 
173
  template<class RandomAccessIterator, class Compare>
174
+ constexpr void partial_sort(RandomAccessIterator first,
175
  RandomAccessIterator middle,
176
  RandomAccessIterator last,
177
  Compare comp);
178
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
179
  void partial_sort(ExecutionPolicy&& exec,
180
  RandomAccessIterator first,
181
  RandomAccessIterator middle,
182
  RandomAccessIterator last,
183
  Compare comp);
184
+
185
+ template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
186
+ class Proj = identity>
187
+ requires sortable<I, Comp, Proj>
188
+ constexpr I
189
+ ranges::partial_sort(I first, I middle, S last, Comp comp = {}, Proj proj = {});
190
  ```
191
 
192
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
193
+ no parameters by those names.
 
 
 
194
 
195
+ *Preconditions:* \[`first`, `middle`) and \[`middle`, `last`) are valid
196
+ ranges. For the overloads in namespace `std`, `RandomAccessIterator`
197
+ meets the *Cpp17ValueSwappable* requirements [[swappable.requirements]]
198
+ and the type of `*first` meets the *Cpp17MoveConstructible*
199
+ ([[cpp17.moveconstructible]]) and *Cpp17MoveAssignable*
200
+ ([[cpp17.moveassignable]]) requirements.
201
+
202
+ *Effects:* Places the first `middle - first` elements from the range
203
+ \[`first`, `last`) as sorted with respect to `comp` and `proj` into the
204
+ range \[`first`, `middle`). The rest of the elements in the range
205
+ \[`middle`, `last`) are placed in an unspecified order.
206
+
207
+ *Returns:* `last` for the overload in namespace `ranges`.
208
 
209
  *Complexity:* Approximately `(last - first) * log(middle - first)`
210
+ comparisons, and twice as many projections.
211
+
212
+ ``` cpp
213
+ template<random_access_range R, class Comp = ranges::less, class Proj = identity>
214
+ requires sortable<iterator_t<R>, Comp, Proj>
215
+ constexpr borrowed_iterator_t<R>
216
+ ranges::partial_sort(R&& r, iterator_t<R> middle, Comp comp = {}, Proj proj = {});
217
+ ```
218
+
219
+ *Effects:* Equivalent to:
220
+
221
+ ``` cpp
222
+ return ranges::partial_sort(ranges::begin(r), middle, ranges::end(r), comp, proj);
223
+ ```
224
 
225
  #### `partial_sort_copy` <a id="partial.sort.copy">[[partial.sort.copy]]</a>
226
 
227
  ``` cpp
228
  template<class InputIterator, class RandomAccessIterator>
229
+ constexpr RandomAccessIterator
230
  partial_sort_copy(InputIterator first, InputIterator last,
231
  RandomAccessIterator result_first,
232
  RandomAccessIterator result_last);
233
  template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterator>
234
  RandomAccessIterator
 
237
  RandomAccessIterator result_first,
238
  RandomAccessIterator result_last);
239
 
240
  template<class InputIterator, class RandomAccessIterator,
241
  class Compare>
242
+ constexpr RandomAccessIterator
243
  partial_sort_copy(InputIterator first, InputIterator last,
244
  RandomAccessIterator result_first,
245
  RandomAccessIterator result_last,
246
  Compare comp);
247
  template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterator,
 
250
  partial_sort_copy(ExecutionPolicy&& exec,
251
  ForwardIterator first, ForwardIterator last,
252
  RandomAccessIterator result_first,
253
  RandomAccessIterator result_last,
254
  Compare comp);
255
+
256
+ template<input_iterator I1, sentinel_for<I1> S1, random_access_iterator I2, sentinel_for<I2> S2,
257
+ class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity>
258
+ requires indirectly_copyable<I1, I2> && sortable<I2, Comp, Proj2> &&
259
+ indirect_strict_weak_order<Comp, projected<I1, Proj1>, projected<I2, Proj2>>
260
+ constexpr ranges::partial_sort_copy_result<I1, I2>
261
+ ranges::partial_sort_copy(I1 first, S1 last, I2 result_first, S2 result_last,
262
+ Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
263
+ template<input_range R1, random_access_range R2, class Comp = ranges::less,
264
+ class Proj1 = identity, class Proj2 = identity>
265
+ requires indirectly_copyable<iterator_t<R1>, iterator_t<R2>> &&
266
+ sortable<iterator_t<R2>, Comp, Proj2> &&
267
+ indirect_strict_weak_order<Comp, projected<iterator_t<R1>, Proj1>,
268
+ projected<iterator_t<R2>, Proj2>>
269
+ constexpr ranges::partial_sort_copy_result<borrowed_iterator_t<R1>, borrowed_iterator_t<R2>>
270
+ ranges::partial_sort_copy(R1&& r, R2&& result_r, Comp comp = {},
271
+ Proj1 proj1 = {}, Proj2 proj2 = {});
272
  ```
273
 
274
+ Let N be min(`last - first`, `result_last - result_first`). Let `comp`
275
+ be `less{}`, and `proj1` and `proj2` be `identity{}` for the overloads
276
+ with no parameters by those names.
277
+
278
+ *Mandates:* For the overloads in namespace `std`, the expression
279
+ `*first` is writable [[iterator.requirements.general]] to
280
+ `result_first`.
281
+
282
+ *Preconditions:* For the overloads in namespace `std`,
283
+ `RandomAccessIterator` meets the *Cpp17ValueSwappable*
284
+ requirements [[swappable.requirements]], the type of `*result_first`
285
+ meets the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
286
+ *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
287
+
288
+ *Preconditions:* For iterators `a1` and `b1` in \[`first`, `last`), and
289
+ iterators `x2` and `y2` in \[`result_first`, `result_last`), after
290
+ evaluating the assignment `*y2 = *b1`, let E be the value of
291
+
292
+ ``` cpp
293
+ bool(invoke(comp, invoke(proj1, *a1), invoke(proj2, *y2))).
294
+ ```
295
+
296
+ Then, after evaluating the assignment `*x2 = *a1`, E is equal to
297
+
298
+ ``` cpp
299
+ bool(invoke(comp, invoke(proj2, *x2), invoke(proj2, *y2))).
300
+ ```
301
+
302
+ [*Note 1*: Writing a value from the input range into the output range
303
+ does not affect how it is ordered by `comp` and `proj1` or
304
+ `proj2`. — *end note*]
305
+
306
+ *Effects:* Places the first N elements as sorted with respect to `comp`
307
+ and `proj2` into the range \[`result_first`, `result_first + `N).
308
 
309
+ *Returns:*
 
 
 
310
 
311
+ - `result_first + `N for the overloads in namespace `std`.
312
+ - `{last, result_first + `N`}` for the overloads in namespace `ranges`.
313
 
314
+ *Complexity:* Approximately `(last - first) * log `N comparisons, and
315
+ twice as many projections.
 
316
 
317
  #### `is_sorted` <a id="is.sorted">[[is.sorted]]</a>
318
 
319
  ``` cpp
320
  template<class ForwardIterator>
321
+ constexpr bool is_sorted(ForwardIterator first, ForwardIterator last);
322
  ```
323
 
324
+ *Effects:* Equivalent to: `return is_sorted_until(first, last) == last;`
325
 
326
  ``` cpp
327
  template<class ExecutionPolicy, class ForwardIterator>
328
  bool is_sorted(ExecutionPolicy&& exec,
329
  ForwardIterator first, ForwardIterator last);
330
  ```
331
 
332
+ *Effects:* Equivalent to:
333
+
334
+ ``` cpp
335
+ return is_sorted_until(std::forward<ExecutionPolicy>(exec), first, last) == last;
336
+ ```
337
 
338
  ``` cpp
339
  template<class ForwardIterator, class Compare>
340
+ constexpr bool is_sorted(ForwardIterator first, ForwardIterator last,
341
  Compare comp);
342
  ```
343
 
344
+ *Effects:* Equivalent to:
345
+ `return is_sorted_until(first, last, comp) == last;`
346
 
347
  ``` cpp
348
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
349
  bool is_sorted(ExecutionPolicy&& exec,
350
  ForwardIterator first, ForwardIterator last,
351
  Compare comp);
352
  ```
353
 
354
+ *Effects:* Equivalent to:
355
 
356
  ``` cpp
357
+ return is_sorted_until(std::forward<ExecutionPolicy>(exec), first, last, comp) == last;
358
  ```
359
 
360
+ ``` cpp
361
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
362
+ indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
363
+ constexpr bool ranges::is_sorted(I first, S last, Comp comp = {}, Proj proj = {});
364
+ template<forward_range R, class Proj = identity,
365
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
366
+ constexpr bool ranges::is_sorted(R&& r, Comp comp = {}, Proj proj = {});
367
+ ```
368
+
369
+ *Effects:* Equivalent to:
370
+ `return ranges::is_sorted_until(first, last, comp, proj) == last;`
371
+
372
  ``` cpp
373
  template<class ForwardIterator>
374
+ constexpr ForwardIterator
375
+ is_sorted_until(ForwardIterator first, ForwardIterator last);
376
  template<class ExecutionPolicy, class ForwardIterator>
377
+ ForwardIterator
378
+ is_sorted_until(ExecutionPolicy&& exec,
379
  ForwardIterator first, ForwardIterator last);
380
 
381
  template<class ForwardIterator, class Compare>
382
+ constexpr ForwardIterator
383
+ is_sorted_until(ForwardIterator first, ForwardIterator last,
384
  Compare comp);
385
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
386
+ ForwardIterator
387
+ is_sorted_until(ExecutionPolicy&& exec,
388
  ForwardIterator first, ForwardIterator last,
389
  Compare comp);
390
+
391
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
392
+ indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
393
+ constexpr I ranges::is_sorted_until(I first, S last, Comp comp = {}, Proj proj = {});
394
+ template<forward_range R, class Proj = identity,
395
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
396
+ constexpr borrowed_iterator_t<R>
397
+ ranges::is_sorted_until(R&& r, Comp comp = {}, Proj proj = {});
398
  ```
399
 
400
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
401
+ no parameters by those names.
402
+
403
+ *Returns:* The last iterator `i` in \[`first`, `last`\] for which the
404
+ range \[`first`, `i`) is sorted with respect to `comp` and `proj`.
405
 
406
  *Complexity:* Linear.
407
 
408
  ### Nth element <a id="alg.nth.element">[[alg.nth.element]]</a>
409
 
410
  ``` cpp
411
  template<class RandomAccessIterator>
412
+ constexpr void nth_element(RandomAccessIterator first, RandomAccessIterator nth,
413
  RandomAccessIterator last);
414
  template<class ExecutionPolicy, class RandomAccessIterator>
415
  void nth_element(ExecutionPolicy&& exec,
416
  RandomAccessIterator first, RandomAccessIterator nth,
417
  RandomAccessIterator last);
418
 
419
  template<class RandomAccessIterator, class Compare>
420
+ constexpr void nth_element(RandomAccessIterator first, RandomAccessIterator nth,
421
  RandomAccessIterator last, Compare comp);
422
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
423
  void nth_element(ExecutionPolicy&& exec,
424
  RandomAccessIterator first, RandomAccessIterator nth,
425
  RandomAccessIterator last, Compare comp);
426
+
427
+ template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
428
+ class Proj = identity>
429
+ requires sortable<I, Comp, Proj>
430
+ constexpr I
431
+ ranges::nth_element(I first, I nth, S last, Comp comp = {}, Proj proj = {});
432
  ```
433
 
434
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
435
+ no parameters by those names.
436
+
437
+ *Preconditions:* \[`first`, `nth`) and \[`nth`, `last`) are valid
438
+ ranges. For the overloads in namespace `std`, `RandomAccessIterator`
439
+ meets the *Cpp17ValueSwappable* requirements [[swappable.requirements]],
440
+ and the type of `*first` meets the *Cpp17MoveConstructible*
441
+ ([[cpp17.moveconstructible]]) and *Cpp17MoveAssignable*
442
+ ([[cpp17.moveassignable]]) requirements.
443
 
444
  *Effects:* After `nth_element` the element in the position pointed to by
445
  `nth` is the element that would be in that position if the whole range
446
+ were sorted with respect to `comp` and `proj`, unless `nth == last`.
447
+ Also for every iterator `i` in the range \[`first`, `nth`) and every
448
+ iterator `j` in the range \[`nth`, `last`) it holds that:
449
+ `bool(invoke(comp, invoke(proj, *j), invoke(proj, *i)))` is `false`.
450
+
451
+ *Returns:* `last` for the overload in namespace `ranges`.
452
 
453
  *Complexity:* For the overloads with no `ExecutionPolicy`, linear on
454
  average. For the overloads with an `ExecutionPolicy`, 𝑂(N) applications
455
  of the predicate, and 𝑂(N log N) swaps, where N = `last - first`.
456
 
457
+ ``` cpp
458
+ template<random_access_range R, class Comp = ranges::less, class Proj = identity>
459
+ requires sortable<iterator_t<R>, Comp, Proj>
460
+ constexpr borrowed_iterator_t<R>
461
+ ranges::nth_element(R&& r, iterator_t<R> nth, Comp comp = {}, Proj proj = {});
462
+ ```
463
+
464
+ *Effects:* Equivalent to:
465
+
466
+ ``` cpp
467
+ return ranges::nth_element(ranges::begin(r), nth, ranges::end(r), comp, proj);
468
+ ```
469
+
470
  ### Binary search <a id="alg.binary.search">[[alg.binary.search]]</a>
471
 
472
+ All of the algorithms in this subclause are versions of binary search
473
+ and assume that the sequence being searched is partitioned with respect
474
+ to an expression formed by binding the search key to an argument of the
475
+ comparison function. They work on non-random access iterators minimizing
476
+ the number of comparisons, which will be logarithmic for all types of
477
+ iterators. They are especially appropriate for random access iterators,
478
+ because these algorithms do a logarithmic number of steps through the
479
+ data structure. For non-random access iterators they execute a linear
480
+ number of steps.
481
 
482
  #### `lower_bound` <a id="lower.bound">[[lower.bound]]</a>
483
 
484
  ``` cpp
485
  template<class ForwardIterator, class T>
486
+ constexpr ForwardIterator
487
  lower_bound(ForwardIterator first, ForwardIterator last,
488
  const T& value);
489
 
490
  template<class ForwardIterator, class T, class Compare>
491
+ constexpr ForwardIterator
492
  lower_bound(ForwardIterator first, ForwardIterator last,
493
  const T& value, Compare comp);
494
+
495
+ template<forward_iterator I, sentinel_for<I> S, class T, class Proj = identity,
496
+ indirect_strict_weak_order<const T*, projected<I, Proj>> Comp = ranges::less>
497
+ constexpr I ranges::lower_bound(I first, S last, const T& value, Comp comp = {},
498
+ Proj proj = {});
499
+ template<forward_range R, class T, class Proj = identity,
500
+ indirect_strict_weak_order<const T*, projected<iterator_t<R>, Proj>> Comp =
501
+ ranges::less>
502
+ constexpr borrowed_iterator_t<R>
503
+ ranges::lower_bound(R&& r, const T& value, Comp comp = {}, Proj proj = {});
504
  ```
505
 
506
+ Let `comp` be `less{}` and `proj` be `identity{}` for overloads with no
507
+ parameters by those names.
508
+
509
+ *Preconditions:* The elements `e` of \[`first`, `last`) are partitioned
510
+ with respect to the expression
511
+ `bool(invoke(comp, invoke(proj, e), value))`.
512
 
513
  *Returns:* The furthermost iterator `i` in the range \[`first`, `last`\]
514
+ such that for every iterator `j` in the range \[`first`, `i`),
515
+ `bool(invoke(comp, invoke(proj, *j), value))` is `true`.
 
516
 
517
+ *Complexity:* At most log₂(`last - first`) + 𝑂(1) comparisons and
518
+ projections.
519
 
520
  #### `upper_bound` <a id="upper.bound">[[upper.bound]]</a>
521
 
522
  ``` cpp
523
  template<class ForwardIterator, class T>
524
+ constexpr ForwardIterator
525
  upper_bound(ForwardIterator first, ForwardIterator last,
526
  const T& value);
527
 
528
  template<class ForwardIterator, class T, class Compare>
529
+ constexpr ForwardIterator
530
  upper_bound(ForwardIterator first, ForwardIterator last,
531
  const T& value, Compare comp);
532
+
533
+ template<forward_iterator I, sentinel_for<I> S, class T, class Proj = identity,
534
+ indirect_strict_weak_order<const T*, projected<I, Proj>> Comp = ranges::less>
535
+ constexpr I ranges::upper_bound(I first, S last, const T& value, Comp comp = {}, Proj proj = {});
536
+ template<forward_range R, class T, class Proj = identity,
537
+ indirect_strict_weak_order<const T*, projected<iterator_t<R>, Proj>> Comp =
538
+ ranges::less>
539
+ constexpr borrowed_iterator_t<R>
540
+ ranges::upper_bound(R&& r, const T& value, Comp comp = {}, Proj proj = {});
541
  ```
542
 
543
+ Let `comp` be `less{}` and `proj` be `identity{}` for overloads with no
544
+ parameters by those names.
545
+
546
+ *Preconditions:* The elements `e` of \[`first`, `last`) are partitioned
547
+ with respect to the expression
548
+ `!bool(invoke(comp, value, invoke(proj, e)))`.
549
 
550
  *Returns:* The furthermost iterator `i` in the range \[`first`, `last`\]
551
+ such that for every iterator `j` in the range \[`first`, `i`),
552
+ `!bool(invoke(comp, value, invoke(proj, *j)))` is `true`.
 
553
 
554
+ *Complexity:* At most log₂(`last - first`) + 𝑂(1) comparisons and
555
+ projections.
556
 
557
  #### `equal_range` <a id="equal.range">[[equal.range]]</a>
558
 
559
  ``` cpp
560
  template<class ForwardIterator, class T>
561
+ constexpr pair<ForwardIterator, ForwardIterator>
562
  equal_range(ForwardIterator first,
563
  ForwardIterator last, const T& value);
564
 
565
  template<class ForwardIterator, class T, class Compare>
566
+ constexpr pair<ForwardIterator, ForwardIterator>
567
  equal_range(ForwardIterator first,
568
  ForwardIterator last, const T& value,
569
  Compare comp);
570
+
571
+ template<forward_iterator I, sentinel_for<I> S, class T, class Proj = identity,
572
+ indirect_strict_weak_order<const T*, projected<I, Proj>> Comp = ranges::less>
573
+ constexpr subrange<I>
574
+ ranges::equal_range(I first, S last, const T& value, Comp comp = {}, Proj proj = {});
575
+ template<forward_range R, class T, class Proj = identity,
576
+ indirect_strict_weak_order<const T*, projected<iterator_t<R>, Proj>> Comp =
577
+ ranges::less>
578
+ constexpr borrowed_subrange_t<R>
579
+ ranges::equal_range(R&& r, const T& value, Comp comp = {}, Proj proj = {});
580
  ```
581
 
582
+ Let `comp` be `less{}` and `proj` be `identity{}` for overloads with no
583
+ parameters by those names.
584
+
585
+ *Preconditions:* The elements `e` of \[`first`, `last`) are partitioned
586
+ with respect to the expressions
587
+ `bool(invoke(comp, invoke(proj, e), value))` and
588
+ `!bool(invoke(comp, value, invoke(proj, e)))`. Also, for all elements
589
+ `e` of `[first, last)`, `bool(comp(e, value))` implies
590
+ `!bool(comp(value, e))` for the overloads in namespace `std`.
591
 
592
  *Returns:*
593
 
594
+ - For the overloads in namespace `std`:
595
  ``` cpp
596
+ {lower_bound(first, last, value, comp),
597
+ upper_bound(first, last, value, comp)}
598
  ```
599
+ - For the overloads in namespace `ranges`:
 
 
600
  ``` cpp
601
+ {ranges::lower_bound(first, last, value, comp, proj),
602
+ ranges::upper_bound(first, last, value, comp, proj)}
603
  ```
604
 
605
+ *Complexity:* At most 2 * log₂(`last - first`) + 𝑂(1) comparisons and
606
+ projections.
607
 
608
  #### `binary_search` <a id="binary.search">[[binary.search]]</a>
609
 
610
  ``` cpp
611
  template<class ForwardIterator, class T>
612
+ constexpr bool
613
+ binary_search(ForwardIterator first, ForwardIterator last,
614
  const T& value);
615
 
616
  template<class ForwardIterator, class T, class Compare>
617
+ constexpr bool
618
+ binary_search(ForwardIterator first, ForwardIterator last,
619
  const T& value, Compare comp);
620
+
621
+ template<forward_iterator I, sentinel_for<I> S, class T, class Proj = identity,
622
+ indirect_strict_weak_order<const T*, projected<I, Proj>> Comp = ranges::less>
623
+ constexpr bool ranges::binary_search(I first, S last, const T& value, Comp comp = {},
624
+ Proj proj = {});
625
+ template<forward_range R, class T, class Proj = identity,
626
+ indirect_strict_weak_order<const T*, projected<iterator_t<R>, Proj>> Comp =
627
+ ranges::less>
628
+ constexpr bool ranges::binary_search(R&& r, const T& value, Comp comp = {},
629
+ Proj proj = {});
630
  ```
631
 
632
+ Let `comp` be `less{}` and `proj` be `identity{}` for overloads with no
633
+ parameters by those names.
 
 
 
634
 
635
+ *Preconditions:* The elements `e` of \[`first`, `last`) are partitioned
636
+ with respect to the expressions
637
+ `bool(invoke(comp, invoke(proj, e), value))` and
638
+ `!bool(invoke(comp, value, invoke(proj, e)))`. Also, for all elements
639
+ `e` of `[first, last)`, `bool(comp(e, value))` implies
640
+ `!bool(comp(value, e))` for the overloads in namespace `std`.
641
 
642
+ *Returns:* `true` if and only if for some iterator `i` in the range
643
+ \[`first`, `last`),
644
+ `!bool(invoke(comp, invoke(proj, *i), value)) && !bool(invoke(comp, value, invoke(proj, *i)))`
645
+ is `true`.
646
+
647
+ *Complexity:* At most log₂(`last - first`) + 𝑂(1) comparisons and
648
+ projections.
649
 
650
  ### Partitions <a id="alg.partitions">[[alg.partitions]]</a>
651
 
652
  ``` cpp
653
  template<class InputIterator, class Predicate>
654
+ constexpr bool is_partitioned(InputIterator first, InputIterator last, Predicate pred);
655
  template<class ExecutionPolicy, class ForwardIterator, class Predicate>
656
  bool is_partitioned(ExecutionPolicy&& exec,
657
  ForwardIterator first, ForwardIterator last, Predicate pred);
658
+
659
+ template<input_iterator I, sentinel_for<I> S, class Proj = identity,
660
+ indirect_unary_predicate<projected<I, Proj>> Pred>
661
+ constexpr bool ranges::is_partitioned(I first, S last, Pred pred, Proj proj = {});
662
+ template<input_range R, class Proj = identity,
663
+ indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
664
+ constexpr bool ranges::is_partitioned(R&& r, Pred pred, Proj proj = {});
665
  ```
666
 
667
+ Let `proj` be `identity{}` for the overloads with no parameter named
668
+ `proj`.
 
 
 
669
 
670
+ *Returns:* `true` if and only if the elements `e` of \[`first`, `last`)
671
+ are partitioned with respect to the expression
672
+ `bool(invoke(pred, invoke(proj, e)))`.
673
 
674
+ *Complexity:* Linear. At most `last - first` applications of `pred` and
675
+ `proj`.
676
 
677
  ``` cpp
678
  template<class ForwardIterator, class Predicate>
679
+ constexpr ForwardIterator
680
  partition(ForwardIterator first, ForwardIterator last, Predicate pred);
681
  template<class ExecutionPolicy, class ForwardIterator, class Predicate>
682
  ForwardIterator
683
  partition(ExecutionPolicy&& exec,
684
  ForwardIterator first, ForwardIterator last, Predicate pred);
685
+
686
+ template<permutable I, sentinel_for<I> S, class Proj = identity,
687
+ indirect_unary_predicate<projected<I, Proj>> Pred>
688
+ constexpr subrange<I>
689
+ ranges::partition(I first, S last, Pred pred, Proj proj = {});
690
+ template<forward_range R, class Proj = identity,
691
+ indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
692
+ requires permutable<iterator_t<R>>
693
+ constexpr borrowed_subrange_t<R>
694
+ ranges::partition(R&& r, Pred pred, Proj proj = {});
695
  ```
696
 
697
+ Let `proj` be `identity{}` for the overloads with no parameter named
698
+ `proj` and let E(x) be `bool(invoke(pred, invoke(proj, `x`)))`.
699
 
700
+ *Preconditions:* For the overloads in namespace `std`, `ForwardIterator`
701
+ meets the *Cpp17ValueSwappable* requirements [[swappable.requirements]].
702
 
703
+ *Effects:* Places all the elements `e` in \[`first`, `last`) that
704
+ satisfy E(`e`) before all the elements that do not.
705
+
706
+ *Returns:* Let `i` be an iterator such that E(`*j`) is `true` for every
707
+ iterator `j` in \[`first`, `i`) and `false` for every iterator `j` in
708
+ \[`i`, `last`). Returns:
709
+
710
+ - `i` for the overloads in namespace `std`.
711
+ - `{i, last}` for the overloads in namespace `ranges`.
712
 
713
  *Complexity:* Let N = `last - first`:
714
 
715
  - For the overload with no `ExecutionPolicy`, exactly N applications of
716
+ the predicate and projection. At most N / 2 swaps if the type of
717
+ `first` meets the *Cpp17BidirectionalIterator* requirements for the
718
+ overloads in namespace `std` or models `bidirectional_iterator` for
719
+ the overloads in namespace `ranges`, and at most N swaps otherwise.
720
  - For the overload with an `ExecutionPolicy`, 𝑂(N log N) swaps and 𝑂(N)
721
  applications of the predicate.
722
 
723
  ``` cpp
724
  template<class BidirectionalIterator, class Predicate>
725
  BidirectionalIterator
726
+ stable_partition(BidirectionalIterator first, BidirectionalIterator last, Predicate pred);
 
727
  template<class ExecutionPolicy, class BidirectionalIterator, class Predicate>
728
  BidirectionalIterator
729
  stable_partition(ExecutionPolicy&& exec,
730
+ BidirectionalIterator first, BidirectionalIterator last, Predicate pred);
731
+
732
+ template<bidirectional_iterator I, sentinel_for<I> S, class Proj = identity,
733
+ indirect_unary_predicate<projected<I, Proj>> Pred>
734
+ requires permutable<I>
735
+ subrange<I> ranges::stable_partition(I first, S last, Pred pred, Proj proj = {});
736
+ template<bidirectional_range R, class Proj = identity,
737
+ indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
738
+ requires permutable<iterator_t<R>>
739
+ borrowed_subrange_t<R> ranges::stable_partition(R&& r, Pred pred, Proj proj = {});
740
  ```
741
 
742
+ Let `proj` be `identity{}` for the overloads with no parameter named
743
+ `proj` and let E(x) be `bool(invoke(pred, invoke(proj, `x`)))`.
744
+
745
+ *Preconditions:* For the overloads in namespace `std`,
746
+ `BidirectionalIterator` meets the *Cpp17ValueSwappable*
747
+ requirements [[swappable.requirements]] and the type of `*first` meets
748
+ the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
749
+ *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
750
+
751
+ *Effects:* Places all the elements `e` in \[`first`, `last`) that
752
+ satisfy E(`e`) before all the elements that do not. The relative order
753
+ of the elements in both groups is preserved.
754
+
755
+ *Returns:* Let `i` be an iterator such that for every iterator `j` in
756
+ \[`first`, `i`), E(`*j`) is `true`, and for every iterator `j` in the
757
+ range \[`i`, `last`), E(`*j`) is `false`. Returns:
758
+
759
+ - `i` for the overloads in namespace `std`.
760
+ - `{i, last}` for the overloads in namespace `ranges`.
761
 
762
  *Complexity:* Let N = `last - first`:
763
 
764
+ - For the overloads with no `ExecutionPolicy`, at most N log N swaps,
765
+ but only 𝑂(N) swaps if there is enough extra memory. Exactly N
766
+ applications of the predicate and projection.
767
  - For the overload with an `ExecutionPolicy`, 𝑂(N log N) swaps and 𝑂(N)
768
  applications of the predicate.
769
 
770
  ``` cpp
771
  template<class InputIterator, class OutputIterator1,
772
  class OutputIterator2, class Predicate>
773
+ constexpr pair<OutputIterator1, OutputIterator2>
774
  partition_copy(InputIterator first, InputIterator last,
775
+ OutputIterator1 out_true, OutputIterator2 out_false, Predicate pred);
 
776
  template<class ExecutionPolicy, class ForwardIterator, class ForwardIterator1,
777
  class ForwardIterator2, class Predicate>
778
  pair<ForwardIterator1, ForwardIterator2>
779
  partition_copy(ExecutionPolicy&& exec,
780
  ForwardIterator first, ForwardIterator last,
781
+ ForwardIterator1 out_true, ForwardIterator2 out_false, Predicate pred);
782
+
783
+ template<input_iterator I, sentinel_for<I> S, weakly_incrementable O1, weakly_incrementable O2,
784
+ class Proj = identity, indirect_unary_predicate<projected<I, Proj>> Pred>
785
+ requires indirectly_copyable<I, O1> && indirectly_copyable<I, O2>
786
+ constexpr ranges::partition_copy_result<I, O1, O2>
787
+ ranges::partition_copy(I first, S last, O1 out_true, O2 out_false, Pred pred,
788
+ Proj proj = {});
789
+ template<input_range R, weakly_incrementable O1, weakly_incrementable O2,
790
+ class Proj = identity,
791
+ indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
792
+ requires indirectly_copyable<iterator_t<R>, O1> &&
793
+ indirectly_copyable<iterator_t<R>, O2>
794
+ constexpr ranges::partition_copy_result<borrowed_iterator_t<R>, O1, O2>
795
+ ranges::partition_copy(R&& r, O1 out_true, O2 out_false, Pred pred, Proj proj = {});
796
  ```
797
 
798
+ Let `proj` be `identity{}` for the overloads with no parameter named
799
+ `proj` and let E(x) be `bool(invoke(pred, invoke(proj, `x`)))`.
800
 
801
+ *Mandates:* For the overloads in namespace `std`, the expression
802
+ `*first` is writable [[iterator.requirements.general]] to `out_true` and
803
+ `out_false`.
804
+
805
+ *Preconditions:* The input range and output ranges do not overlap.
806
+
807
+ [*Note 1*: For the overload with an `ExecutionPolicy`, there may be a
808
+ performance cost if `first`s value type does not meet the
809
+ *Cpp17CopyConstructible* requirements. *end note*]
 
 
 
 
810
 
811
  *Effects:* For each iterator `i` in \[`first`, `last`), copies `*i` to
812
+ the output range beginning with `out_true` if E(`*i`) is `true`, or to
813
+ the output range beginning with `out_false` otherwise.
814
 
815
+ *Returns:* Let `o1` be the end of the output range beginning at
816
+ `out_true`, and `o2` the end of the output range beginning at
817
+ `out_false`. Returns
818
 
819
+ - `{o1, o2}` for the overloads in namespace `std`.
820
+ - `{last, o1, o2}` for the overloads in namespace `ranges`.
821
+
822
+ *Complexity:* Exactly `last - first` applications of `pred` and `proj`.
823
 
824
  ``` cpp
825
  template<class ForwardIterator, class Predicate>
826
+ constexpr ForwardIterator
827
+ partition_point(ForwardIterator first, ForwardIterator last, Predicate pred);
828
+
829
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
830
+ indirect_unary_predicate<projected<I, Proj>> Pred>
831
+ constexpr I ranges::partition_point(I first, S last, Pred pred, Proj proj = {});
832
+ template<forward_range R, class Proj = identity,
833
+ indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
834
+ constexpr borrowed_iterator_t<R>
835
+ ranges::partition_point(R&& r, Pred pred, Proj proj = {});
836
  ```
837
 
838
+ Let `proj` be `identity{}` for the overloads with no parameter named
839
+ `proj` and let E(x) be `bool(invoke(pred, invoke(proj, `x`)))`.
 
 
840
 
841
+ *Preconditions:* The elements `e` of \[`first`, `last`) are partitioned
842
+ with respect to E(`e`).
843
 
844
+ *Returns:* An iterator `mid` such that E(`*i`) is `true` for all
845
+ iterators `i` in \[`first`, `mid`), and `false` for all iterators `i` in
846
+ \[`mid`, `last`).
847
+
848
+ *Complexity:* 𝑂(log(`last - first`)) applications of `pred` and `proj`.
849
 
850
  ### Merge <a id="alg.merge">[[alg.merge]]</a>
851
 
852
  ``` cpp
853
  template<class InputIterator1, class InputIterator2,
854
  class OutputIterator>
855
+ constexpr OutputIterator
856
  merge(InputIterator1 first1, InputIterator1 last1,
857
  InputIterator2 first2, InputIterator2 last2,
858
  OutputIterator result);
859
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
860
  class ForwardIterator>
 
864
  ForwardIterator2 first2, ForwardIterator2 last2,
865
  ForwardIterator result);
866
 
867
  template<class InputIterator1, class InputIterator2,
868
  class OutputIterator, class Compare>
869
+ constexpr OutputIterator
870
  merge(InputIterator1 first1, InputIterator1 last1,
871
  InputIterator2 first2, InputIterator2 last2,
872
  OutputIterator result, Compare comp);
873
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
874
  class ForwardIterator, class Compare>
875
  ForwardIterator
876
  merge(ExecutionPolicy&& exec,
877
  ForwardIterator1 first1, ForwardIterator1 last1,
878
  ForwardIterator2 first2, ForwardIterator2 last2,
879
  ForwardIterator result, Compare comp);
880
+
881
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
882
+ weakly_incrementable O, class Comp = ranges::less, class Proj1 = identity,
883
+ class Proj2 = identity>
884
+ requires mergeable<I1, I2, O, Comp, Proj1, Proj2>
885
+ constexpr ranges::merge_result<I1, I2, O>
886
+ ranges::merge(I1 first1, S1 last1, I2 first2, S2 last2, O result,
887
+ Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
888
+ template<input_range R1, input_range R2, weakly_incrementable O, class Comp = ranges::less,
889
+ class Proj1 = identity, class Proj2 = identity>
890
+ requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2>
891
+ constexpr ranges::merge_result<borrowed_iterator_t<R1>, borrowed_iterator_t<R2>, O>
892
+ ranges::merge(R1&& r1, R2&& r2, O result,
893
+ Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
894
  ```
895
 
896
+ Let N be `(last1 - first1) + (last2 - first2)`. Let `comp` be `less{}`,
897
+ `proj1` be `identity{}`, and `proj2` be `identity{}`, for the overloads
898
+ with no parameters by those names.
899
 
900
+ *Preconditions:* The ranges \[`first1`, `last1`) and \[`first2`,
901
+ `last2`) are sorted with respect to `comp` and `proj1` or `proj2`,
902
+ respectively. The resulting range does not overlap with either of the
903
+ original ranges.
904
+
905
+ *Effects:* Copies all the elements of the two ranges \[`first1`,
906
  `last1`) and \[`first2`, `last2`) into the range \[`result`,
907
+ `result_last`), where `result_last` is `result + `N. If an element `a`
908
+ precedes `b` in an input range, `a` is copied into the output range
909
+ before `b`. If `e1` is an element of \[`first1`, `last1`) and `e2` of
910
+ \[`first2`, `last2`), `e2` is copied into the output range before `e1`
911
+ if and only if
912
+ `bool(invoke(comp, invoke(proj2, e2), invoke(proj1, e1)))` is `true`.
913
 
914
+ *Returns:*
915
 
916
+ - `result_last` for the overloads in namespace `std`.
917
+ - `{last1, last2, result_last}` for the overloads in namespace `ranges`.
918
 
919
+ *Complexity:*
920
+
921
+ - For the overloads with no `ExecutionPolicy`, at most N - 1 comparisons
922
+ and applications of each projection.
923
  - For the overloads with an `ExecutionPolicy`, 𝑂(N) comparisons.
924
 
925
+ *Remarks:* Stable [[algorithm.stable]].
926
 
927
  ``` cpp
928
  template<class BidirectionalIterator>
929
  void inplace_merge(BidirectionalIterator first,
930
  BidirectionalIterator middle,
 
942
  template<class ExecutionPolicy, class BidirectionalIterator, class Compare>
943
  void inplace_merge(ExecutionPolicy&& exec,
944
  BidirectionalIterator first,
945
  BidirectionalIterator middle,
946
  BidirectionalIterator last, Compare comp);
947
+
948
+ template<bidirectional_iterator I, sentinel_for<I> S, class Comp = ranges::less,
949
+ class Proj = identity>
950
+ requires sortable<I, Comp, Proj>
951
+ I ranges::inplace_merge(I first, I middle, S last, Comp comp = {}, Proj proj = {});
952
  ```
953
 
954
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
955
+ no parameters by those names.
956
+
957
+ *Preconditions:* \[`first`, `middle`) and \[`middle`, `last`) are valid
958
+ ranges sorted with respect to `comp` and `proj`. For the overloads in
959
+ namespace `std`, `BidirectionalIterator` meets the *Cpp17ValueSwappable*
960
+ requirements [[swappable.requirements]] and the type of `*first` meets
961
+ the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
962
+ *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
963
 
964
  *Effects:* Merges two sorted consecutive ranges \[`first`, `middle`) and
965
  \[`middle`, `last`), putting the result of the merge into the range
966
+ \[`first`, `last`). The resulting range is sorted with respect to `comp`
967
+ and `proj`.
968
+
969
+ *Returns:* `last` for the overload in namespace `ranges`.
970
 
971
  *Complexity:* Let N = `last - first`:
972
 
973
+ - For the overloads with no `ExecutionPolicy`, and if enough additional
974
  memory is available, exactly N - 1 comparisons.
975
+ - Otherwise, 𝑂(N log N) comparisons.
 
 
976
 
977
+ In either case, twice as many projections as comparisons.
978
+
979
+ *Remarks:* Stable [[algorithm.stable]].
980
+
981
+ ``` cpp
982
+ template<bidirectional_range R, class Comp = ranges::less, class Proj = identity>
983
+ requires sortable<iterator_t<R>, Comp, Proj>
984
+ borrowed_iterator_t<R>
985
+ ranges::inplace_merge(R&& r, iterator_t<R> middle, Comp comp = {}, Proj proj = {});
986
+ ```
987
+
988
+ *Effects:* Equivalent to:
989
+
990
+ ``` cpp
991
+ return ranges::inplace_merge(ranges::begin(r), middle, ranges::end(r), comp, proj);
992
+ ```
993
 
994
  ### Set operations on sorted structures <a id="alg.set.operations">[[alg.set.operations]]</a>
995
 
996
+ This subclause defines all the basic set operations on sorted
997
+ structures. They also work with `multiset`s [[multiset]] containing
998
+ multiple copies of equivalent elements. The semantics of the set
999
+ operations are generalized to `multiset`s in a standard way by defining
1000
+ `set_union` to contain the maximum number of occurrences of every
1001
+ element, `set_intersection` to contain the minimum, and so on.
1002
 
1003
  #### `includes` <a id="includes">[[includes]]</a>
1004
 
1005
  ``` cpp
1006
  template<class InputIterator1, class InputIterator2>
1007
+ constexpr bool includes(InputIterator1 first1, InputIterator1 last1,
1008
  InputIterator2 first2, InputIterator2 last2);
1009
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
1010
  bool includes(ExecutionPolicy&& exec,
1011
  ForwardIterator1 first1, ForwardIterator1 last1,
1012
  ForwardIterator2 first2, ForwardIterator2 last2);
1013
 
1014
  template<class InputIterator1, class InputIterator2, class Compare>
1015
+ constexpr bool includes(InputIterator1 first1, InputIterator1 last1,
1016
  InputIterator2 first2, InputIterator2 last2,
1017
  Compare comp);
1018
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Compare>
1019
  bool includes(ExecutionPolicy&& exec,
1020
  ForwardIterator1 first1, ForwardIterator1 last1,
1021
  ForwardIterator2 first2, ForwardIterator2 last2,
1022
  Compare comp);
1023
+
1024
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
1025
+ class Proj1 = identity, class Proj2 = identity,
1026
+ indirect_strict_weak_order<projected<I1, Proj1>,
1027
+ projected<I2, Proj2>> Comp = ranges::less>
1028
+ constexpr bool ranges::includes(I1 first1, S1 last1, I2 first2, S2 last2, Comp comp = {},
1029
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1030
+ template<input_range R1, input_range R2, class Proj1 = identity,
1031
+ class Proj2 = identity,
1032
+ indirect_strict_weak_order<projected<iterator_t<R1>, Proj1>,
1033
+ projected<iterator_t<R2>, Proj2>> Comp = ranges::less>
1034
+ constexpr bool ranges::includes(R1&& r1, R2&& r2, Comp comp = {},
1035
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1036
  ```
1037
 
1038
+ Let `comp` be `less{}`, `proj1` be `identity{}`, and `proj2` be
1039
+ `identity{}`, for the overloads with no parameters by those names.
1040
+
1041
+ *Preconditions:* The ranges \[`first1`, `last1`) and \[`first2`,
1042
+ `last2`) are sorted with respect to `comp` and `proj1` or `proj2`,
1043
+ respectively.
1044
+
1045
+ *Returns:* `true` if and only if \[`first2`, `last2`) is a subsequence
1046
+ of \[`first1`, `last1`).
1047
+
1048
+ [*Note 1*: A sequence S is a subsequence of another sequence T if S can
1049
+ be obtained from T by removing some, all, or none of T’s elements and
1050
+ keeping the remaining elements in the same order. — *end note*]
1051
 
1052
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
1053
+ comparisons and applications of each projection.
1054
 
1055
  #### `set_union` <a id="set.union">[[set.union]]</a>
1056
 
1057
  ``` cpp
1058
  template<class InputIterator1, class InputIterator2,
1059
  class OutputIterator>
1060
+ constexpr OutputIterator
1061
  set_union(InputIterator1 first1, InputIterator1 last1,
1062
  InputIterator2 first2, InputIterator2 last2,
1063
  OutputIterator result);
1064
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
1065
  class ForwardIterator>
 
1069
  ForwardIterator2 first2, ForwardIterator2 last2,
1070
  ForwardIterator result);
1071
 
1072
  template<class InputIterator1, class InputIterator2,
1073
  class OutputIterator, class Compare>
1074
+ constexpr OutputIterator
1075
  set_union(InputIterator1 first1, InputIterator1 last1,
1076
  InputIterator2 first2, InputIterator2 last2,
1077
  OutputIterator result, Compare comp);
1078
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
1079
  class ForwardIterator, class Compare>
1080
  ForwardIterator
1081
  set_union(ExecutionPolicy&& exec,
1082
  ForwardIterator1 first1, ForwardIterator1 last1,
1083
  ForwardIterator2 first2, ForwardIterator2 last2,
1084
  ForwardIterator result, Compare comp);
1085
+
1086
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
1087
+ weakly_incrementable O, class Comp = ranges::less,
1088
+ class Proj1 = identity, class Proj2 = identity>
1089
+ requires mergeable<I1, I2, O, Comp, Proj1, Proj2>
1090
+ constexpr ranges::set_union_result<I1, I2, O>
1091
+ ranges::set_union(I1 first1, S1 last1, I2 first2, S2 last2, O result, Comp comp = {},
1092
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1093
+ template<input_range R1, input_range R2, weakly_incrementable O,
1094
+ class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity>
1095
+ requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2>
1096
+ constexpr ranges::set_union_result<borrowed_iterator_t<R1>, borrowed_iterator_t<R2>, O>
1097
+ ranges::set_union(R1&& r1, R2&& r2, O result, Comp comp = {},
1098
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1099
  ```
1100
 
1101
+ Let `comp` be `less{}`, and `proj1` and `proj2` be `identity{}` for the
1102
+ overloads with no parameters by those names.
1103
+
1104
+ *Preconditions:* The ranges \[`first1`, `last1`) and \[`first2`,
1105
+ `last2`) are sorted with respect to `comp` and `proj1` or `proj2`,
1106
+ respectively. The resulting range does not overlap with either of the
1107
  original ranges.
1108
 
1109
  *Effects:* Constructs a sorted union of the elements from the two
1110
  ranges; that is, the set of elements that are present in one or both of
1111
  the ranges.
1112
 
1113
+ *Returns:* Let `result_last` be the end of the constructed range.
1114
+ Returns
1115
+
1116
+ - `result_last` for the overloads in namespace `std`.
1117
+ - `{last1, last2, result_last}` for the overloads in namespace `ranges`.
1118
 
1119
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
1120
+ comparisons and applications of each projection.
1121
 
1122
+ *Remarks:* Stable [[algorithm.stable]]. If \[`first1`, `last1`) contains
1123
+ m elements that are equivalent to each other and \[`first2`, `last2`)
1124
+ contains n elements that are equivalent to them, then all m elements
1125
+ from the first range are copied to the output range, in order, and then
1126
+ the final max(n - m, 0) elements from the second range are copied to the
1127
+ output range, in order.
1128
 
1129
  #### `set_intersection` <a id="set.intersection">[[set.intersection]]</a>
1130
 
1131
  ``` cpp
1132
  template<class InputIterator1, class InputIterator2,
1133
  class OutputIterator>
1134
+ constexpr OutputIterator
1135
  set_intersection(InputIterator1 first1, InputIterator1 last1,
1136
  InputIterator2 first2, InputIterator2 last2,
1137
  OutputIterator result);
1138
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
1139
  class ForwardIterator>
 
1143
  ForwardIterator2 first2, ForwardIterator2 last2,
1144
  ForwardIterator result);
1145
 
1146
  template<class InputIterator1, class InputIterator2,
1147
  class OutputIterator, class Compare>
1148
+ constexpr OutputIterator
1149
  set_intersection(InputIterator1 first1, InputIterator1 last1,
1150
  InputIterator2 first2, InputIterator2 last2,
1151
  OutputIterator result, Compare comp);
1152
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
1153
  class ForwardIterator, class Compare>
1154
  ForwardIterator
1155
  set_intersection(ExecutionPolicy&& exec,
1156
  ForwardIterator1 first1, ForwardIterator1 last1,
1157
  ForwardIterator2 first2, ForwardIterator2 last2,
1158
  ForwardIterator result, Compare comp);
1159
+
1160
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
1161
+ weakly_incrementable O, class Comp = ranges::less,
1162
+ class Proj1 = identity, class Proj2 = identity>
1163
+ requires mergeable<I1, I2, O, Comp, Proj1, Proj2>
1164
+ constexpr ranges::set_intersection_result<I1, I2, O>
1165
+ ranges::set_intersection(I1 first1, S1 last1, I2 first2, S2 last2, O result,
1166
+ Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1167
+ template<input_range R1, input_range R2, weakly_incrementable O,
1168
+ class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity>
1169
+ requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2>
1170
+ constexpr ranges::set_intersection_result<borrowed_iterator_t<R1>, borrowed_iterator_t<R2>, O>
1171
+ ranges::set_intersection(R1&& r1, R2&& r2, O result,
1172
+ Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1173
  ```
1174
 
1175
+ Let `comp` be `less{}`, and `proj1` and `proj2` be `identity{}` for the
1176
+ overloads with no parameters by those names.
1177
+
1178
+ *Preconditions:* The ranges \[`first1`, `last1`) and \[`first2`,
1179
+ `last2`) are sorted with respect to `comp` and `proj1` or `proj2`,
1180
+ respectively. The resulting range does not overlap with either of the
1181
  original ranges.
1182
 
1183
  *Effects:* Constructs a sorted intersection of the elements from the two
1184
  ranges; that is, the set of elements that are present in both of the
1185
  ranges.
1186
 
1187
+ *Returns:* Let `result_last` be the end of the constructed range.
1188
+ Returns
1189
+
1190
+ - `result_last` for the overloads in namespace `std`.
1191
+ - `{last1, last2, result_last}` for the overloads in namespace `ranges`.
1192
 
1193
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
1194
+ comparisons and applications of each projection.
1195
 
1196
+ *Remarks:* Stable [[algorithm.stable]]. If \[`first1`, `last1`) contains
1197
+ m elements that are equivalent to each other and \[`first2`, `last2`)
1198
+ contains n elements that are equivalent to them, the first min(m, n)
1199
+ elements are copied from the first range to the output range, in order.
1200
 
1201
  #### `set_difference` <a id="set.difference">[[set.difference]]</a>
1202
 
1203
  ``` cpp
1204
  template<class InputIterator1, class InputIterator2,
1205
  class OutputIterator>
1206
+ constexpr OutputIterator
1207
  set_difference(InputIterator1 first1, InputIterator1 last1,
1208
  InputIterator2 first2, InputIterator2 last2,
1209
  OutputIterator result);
1210
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
1211
  class ForwardIterator>
 
1215
  ForwardIterator2 first2, ForwardIterator2 last2,
1216
  ForwardIterator result);
1217
 
1218
  template<class InputIterator1, class InputIterator2,
1219
  class OutputIterator, class Compare>
1220
+ constexpr OutputIterator
1221
  set_difference(InputIterator1 first1, InputIterator1 last1,
1222
  InputIterator2 first2, InputIterator2 last2,
1223
  OutputIterator result, Compare comp);
1224
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
1225
  class ForwardIterator, class Compare>
1226
  ForwardIterator
1227
  set_difference(ExecutionPolicy&& exec,
1228
  ForwardIterator1 first1, ForwardIterator1 last1,
1229
  ForwardIterator2 first2, ForwardIterator2 last2,
1230
  ForwardIterator result, Compare comp);
1231
+
1232
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
1233
+ weakly_incrementable O, class Comp = ranges::less,
1234
+ class Proj1 = identity, class Proj2 = identity>
1235
+ requires mergeable<I1, I2, O, Comp, Proj1, Proj2>
1236
+ constexpr ranges::set_difference_result<I1, O>
1237
+ ranges::set_difference(I1 first1, S1 last1, I2 first2, S2 last2, O result,
1238
+ Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1239
+ template<input_range R1, input_range R2, weakly_incrementable O,
1240
+ class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity>
1241
+ requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2>
1242
+ constexpr ranges::set_difference_result<borrowed_iterator_t<R1>, O>
1243
+ ranges::set_difference(R1&& r1, R2&& r2, O result,
1244
+ Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1245
  ```
1246
 
1247
+ Let `comp` be `less{}`, and `proj1` and `proj2` be `identity{}` for the
1248
+ overloads with no parameters by those names.
1249
+
1250
+ *Preconditions:* The ranges \[`first1`, `last1`) and \[`first2`,
1251
+ `last2`) are sorted with respect to `comp` and `proj1` or `proj2`,
1252
+ respectively. The resulting range does not overlap with either of the
1253
  original ranges.
1254
 
1255
  *Effects:* Copies the elements of the range \[`first1`, `last1`) which
1256
  are not present in the range \[`first2`, `last2`) to the range beginning
1257
  at `result`. The elements in the constructed range are sorted.
1258
 
1259
+ *Returns:* Let `result_last` be the end of the constructed range.
1260
+ Returns
1261
+
1262
+ - `result_last` for the overloads in namespace `std`.
1263
+ - `{last1, result_last}` for the overloads in namespace `ranges`.
1264
 
1265
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
1266
+ comparisons and applications of each projection.
1267
 
1268
  *Remarks:* If \[`first1`, `last1`) contains m elements that are
1269
  equivalent to each other and \[`first2`, `last2`) contains n elements
1270
  that are equivalent to them, the last max(m - n, 0) elements from
1271
+ \[`first1`, `last1`) is copied to the output range, in order.
1272
 
1273
  #### `set_symmetric_difference` <a id="set.symmetric.difference">[[set.symmetric.difference]]</a>
1274
 
1275
  ``` cpp
1276
  template<class InputIterator1, class InputIterator2,
1277
  class OutputIterator>
1278
+ constexpr OutputIterator
1279
  set_symmetric_difference(InputIterator1 first1, InputIterator1 last1,
1280
  InputIterator2 first2, InputIterator2 last2,
1281
  OutputIterator result);
1282
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
1283
  class ForwardIterator>
 
1287
  ForwardIterator2 first2, ForwardIterator2 last2,
1288
  ForwardIterator result);
1289
 
1290
  template<class InputIterator1, class InputIterator2,
1291
  class OutputIterator, class Compare>
1292
+ constexpr OutputIterator
1293
  set_symmetric_difference(InputIterator1 first1, InputIterator1 last1,
1294
  InputIterator2 first2, InputIterator2 last2,
1295
  OutputIterator result, Compare comp);
1296
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
1297
  class ForwardIterator, class Compare>
1298
  ForwardIterator
1299
  set_symmetric_difference(ExecutionPolicy&& exec,
1300
  ForwardIterator1 first1, ForwardIterator1 last1,
1301
  ForwardIterator2 first2, ForwardIterator2 last2,
1302
  ForwardIterator result, Compare comp);
1303
+
1304
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
1305
+ weakly_incrementable O, class Comp = ranges::less,
1306
+ class Proj1 = identity, class Proj2 = identity>
1307
+ requires mergeable<I1, I2, O, Comp, Proj1, Proj2>
1308
+ constexpr ranges::set_symmetric_difference_result<I1, I2, O>
1309
+ ranges::set_symmetric_difference(I1 first1, S1 last1, I2 first2, S2 last2, O result,
1310
+ Comp comp = {}, Proj1 proj1 = {},
1311
+ Proj2 proj2 = {});
1312
+ template<input_range R1, input_range R2, weakly_incrementable O,
1313
+ class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity>
1314
+ requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2>
1315
+ constexpr ranges::set_symmetric_difference_result<borrowed_iterator_t<R1>,
1316
+ borrowed_iterator_t<R2>, O>
1317
+ ranges::set_symmetric_difference(R1&& r1, R2&& r2, O result, Comp comp = {},
1318
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1319
  ```
1320
 
1321
+ Let `comp` be `less{}`, and `proj1` and `proj2` be `identity{}` for the
1322
+ overloads with no parameters by those names.
1323
+
1324
+ *Preconditions:* The ranges \[`first1`, `last1`) and \[`first2`,
1325
+ `last2`) are sorted with respect to `comp` and `proj1` or `proj2`,
1326
+ respectively. The resulting range does not overlap with either of the
1327
  original ranges.
1328
 
1329
  *Effects:* Copies the elements of the range \[`first1`, `last1`) that
1330
  are not present in the range \[`first2`, `last2`), and the elements of
1331
  the range \[`first2`, `last2`) that are not present in the range
1332
  \[`first1`, `last1`) to the range beginning at `result`. The elements in
1333
  the constructed range are sorted.
1334
 
1335
+ *Returns:* Let `result_last` be the end of the constructed range.
1336
+ Returns
1337
+
1338
+ - `result_last` for the overloads in namespace `std`.
1339
+ - `{last1, last2, result_last}` for the overloads in namespace `ranges`.
1340
 
1341
  *Complexity:* At most `2 * ((last1 - first1) + (last2 - first2)) - 1`
1342
+ comparisons and applications of each projection.
1343
 
1344
+ *Remarks:* Stable [[algorithm.stable]]. If \[`first1`, `last1`) contains
1345
+ m elements that are equivalent to each other and \[`first2`, `last2`)
1346
+ contains n elements that are equivalent to them, then |m - n| of those
1347
+ elements shall be copied to the output range: the last m - n of these
1348
+ elements from \[`first1`, `last1`) if m > n, and the last n - m of these
1349
+ elements from \[`first2`, `last2`) if m < n. In either case, the
1350
+ elements are copied in order.
1351
 
1352
  ### Heap operations <a id="alg.heap.operations">[[alg.heap.operations]]</a>
1353
 
1354
+ A random access range \[`a`, `b`) is a *heap with respect to `comp` and
1355
+ `proj`* for a comparator and projection `comp` and `proj` if its
1356
+ elements are organized such that:
1357
 
1358
  - With `N = b - a`, for all i, 0 < i < N,
1359
+ `bool(invoke(comp, invoke(proj, a[\left \lfloor{\frac{i - 1}{2}}\right \rfloor]), invoke({}proj, a[i])))`
1360
+ is `false`.
1361
+ - `*a` may be removed by `pop_heap`, or a new element added by
1362
+ `push_heap`, in 𝑂(log N) time.
1363
 
1364
  These properties make heaps useful as priority queues.
1365
 
1366
+ `make_heap` converts a range into a heap and `sort_heap` turns a heap
1367
+ into a sorted sequence.
 
 
1368
 
1369
  #### `push_heap` <a id="push.heap">[[push.heap]]</a>
1370
 
1371
  ``` cpp
1372
  template<class RandomAccessIterator>
1373
+ constexpr void push_heap(RandomAccessIterator first, RandomAccessIterator last);
1374
 
1375
  template<class RandomAccessIterator, class Compare>
1376
+ constexpr void push_heap(RandomAccessIterator first, RandomAccessIterator last,
1377
  Compare comp);
1378
+
1379
+ template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
1380
+ class Proj = identity>
1381
+ requires sortable<I, Comp, Proj>
1382
+ constexpr I
1383
+ ranges::push_heap(I first, S last, Comp comp = {}, Proj proj = {});
1384
+ template<random_access_range R, class Comp = ranges::less, class Proj = identity>
1385
+ requires sortable<iterator_t<R>, Comp, Proj>
1386
+ constexpr borrowed_iterator_t<R>
1387
+ ranges::push_heap(R&& r, Comp comp = {}, Proj proj = {});
1388
  ```
1389
 
1390
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
1391
+ no parameters by those names.
1392
+
1393
+ *Preconditions:* The range \[`first`, `last - 1`) is a valid heap with
1394
+ respect to `comp` and `proj`. For the overloads in namespace `std`, the
1395
+ type of `*first` meets the *Cpp17MoveConstructible* requirements
1396
+ ([[cpp17.moveconstructible]]) and the *Cpp17MoveAssignable*
1397
+ requirements ([[cpp17.moveassignable]]).
1398
 
1399
  *Effects:* Places the value in the location `last - 1` into the
1400
  resulting heap \[`first`, `last`).
1401
 
1402
+ *Returns:* `last` for the overloads in namespace `ranges`.
1403
+
1404
+ *Complexity:* At most log(`last - first`) comparisons and twice as many
1405
+ projections.
1406
 
1407
  #### `pop_heap` <a id="pop.heap">[[pop.heap]]</a>
1408
 
1409
  ``` cpp
1410
  template<class RandomAccessIterator>
1411
+ constexpr void pop_heap(RandomAccessIterator first, RandomAccessIterator last);
1412
 
1413
  template<class RandomAccessIterator, class Compare>
1414
+ constexpr void pop_heap(RandomAccessIterator first, RandomAccessIterator last,
1415
  Compare comp);
1416
+
1417
+ template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
1418
+ class Proj = identity>
1419
+ requires sortable<I, Comp, Proj>
1420
+ constexpr I
1421
+ ranges::pop_heap(I first, S last, Comp comp = {}, Proj proj = {});
1422
+ template<random_access_range R, class Comp = ranges::less, class Proj = identity>
1423
+ requires sortable<iterator_t<R>, Comp, Proj>
1424
+ constexpr borrowed_iterator_t<R>
1425
+ ranges::pop_heap(R&& r, Comp comp = {}, Proj proj = {});
1426
  ```
1427
 
1428
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
1429
+ no parameters by those names.
1430
+
1431
+ *Preconditions:* The range \[`first`, `last`) is a valid non-empty heap
1432
+ with respect to `comp` and `proj`. For the overloads in namespace `std`,
1433
+ `RandomAccessIterator` meets the *Cpp17ValueSwappable*
1434
+ requirements [[swappable.requirements]] and the type of `*first` meets
1435
+ the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
1436
+ *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
1437
 
1438
  *Effects:* Swaps the value in the location `first` with the value in the
1439
+ location `last - 1` and makes \[`first`, `last - 1`) into a heap with
1440
+ respect to `comp` and `proj`.
1441
 
1442
+ *Returns:* `last` for the overloads in namespace `ranges`.
1443
+
1444
+ *Complexity:* At most 2 log(`last - first`) comparisons and twice as
1445
+ many projections.
1446
 
1447
  #### `make_heap` <a id="make.heap">[[make.heap]]</a>
1448
 
1449
  ``` cpp
1450
  template<class RandomAccessIterator>
1451
+ constexpr void make_heap(RandomAccessIterator first, RandomAccessIterator last);
1452
 
1453
  template<class RandomAccessIterator, class Compare>
1454
+ constexpr void make_heap(RandomAccessIterator first, RandomAccessIterator last,
1455
  Compare comp);
1456
+
1457
+ template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
1458
+ class Proj = identity>
1459
+ requires sortable<I, Comp, Proj>
1460
+ constexpr I
1461
+ ranges::make_heap(I first, S last, Comp comp = {}, Proj proj = {});
1462
+ template<random_access_range R, class Comp = ranges::less, class Proj = identity>
1463
+ requires sortable<iterator_t<R>, Comp, Proj>
1464
+ constexpr borrowed_iterator_t<R>
1465
+ ranges::make_heap(R&& r, Comp comp = {}, Proj proj = {});
1466
  ```
1467
 
1468
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
1469
+ no parameters by those names.
 
1470
 
1471
+ *Preconditions:* For the overloads in namespace `std`, the type of
1472
+ `*first` meets the *Cpp17MoveConstructible*
1473
+ ([[cpp17.moveconstructible]]) and *Cpp17MoveAssignable*
1474
+ ([[cpp17.moveassignable]]) requirements.
1475
 
1476
+ *Effects:* Constructs a heap with respect to `comp` and `proj` out of
1477
+ the range \[`first`, `last`).
1478
+
1479
+ *Returns:* `last` for the overloads in namespace `ranges`.
1480
+
1481
+ *Complexity:* At most 3(`last - first`) comparisons and twice as many
1482
+ projections.
1483
 
1484
  #### `sort_heap` <a id="sort.heap">[[sort.heap]]</a>
1485
 
1486
  ``` cpp
1487
  template<class RandomAccessIterator>
1488
+ constexpr void sort_heap(RandomAccessIterator first, RandomAccessIterator last);
1489
 
1490
  template<class RandomAccessIterator, class Compare>
1491
+ constexpr void sort_heap(RandomAccessIterator first, RandomAccessIterator last,
1492
  Compare comp);
1493
+
1494
+ template<random_access_iterator I, sentinel_for<I> S, class Comp = ranges::less,
1495
+ class Proj = identity>
1496
+ requires sortable<I, Comp, Proj>
1497
+ constexpr I
1498
+ ranges::sort_heap(I first, S last, Comp comp = {}, Proj proj = {});
1499
+ template<random_access_range R, class Comp = ranges::less, class Proj = identity>
1500
+ requires sortable<iterator_t<R>, Comp, Proj>
1501
+ constexpr borrowed_iterator_t<R>
1502
+ ranges::sort_heap(R&& r, Comp comp = {}, Proj proj = {});
1503
  ```
1504
 
1505
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
1506
+ no parameters by those names.
 
 
 
 
1507
 
1508
+ *Preconditions:* The range \[`first`, `last`) is a valid heap with
1509
+ respect to `comp` and `proj`. For the overloads in namespace `std`,
1510
+ `RandomAccessIterator` meets the *Cpp17ValueSwappable*
1511
+ requirements [[swappable.requirements]] and the type of `*first` meets
1512
+ the *Cpp17MoveConstructible* ([[cpp17.moveconstructible]]) and
1513
+ *Cpp17MoveAssignable* ([[cpp17.moveassignable]]) requirements.
1514
 
1515
+ *Effects:* Sorts elements in the heap \[`first`, `last`) with respect to
1516
+ `comp` and `proj`.
1517
+
1518
+ *Returns:* `last` for the overloads in namespace `ranges`.
1519
+
1520
+ *Complexity:* At most 2N log N comparisons, where N = `last - first`,
1521
+ and twice as many projections.
1522
 
1523
  #### `is_heap` <a id="is.heap">[[is.heap]]</a>
1524
 
1525
  ``` cpp
1526
  template<class RandomAccessIterator>
1527
+ constexpr bool is_heap(RandomAccessIterator first, RandomAccessIterator last);
1528
  ```
1529
 
1530
+ *Effects:* Equivalent to: `return is_heap_until(first, last) == last;`
1531
 
1532
  ``` cpp
1533
  template<class ExecutionPolicy, class RandomAccessIterator>
1534
  bool is_heap(ExecutionPolicy&& exec,
1535
  RandomAccessIterator first, RandomAccessIterator last);
1536
  ```
1537
 
1538
+ *Effects:* Equivalent to:
1539
+
1540
+ ``` cpp
1541
+ return is_heap_until(std::forward<ExecutionPolicy>(exec), first, last) == last;
1542
+ ```
1543
 
1544
  ``` cpp
1545
  template<class RandomAccessIterator, class Compare>
1546
+ constexpr bool is_heap(RandomAccessIterator first, RandomAccessIterator last,
1547
+ Compare comp);
1548
  ```
1549
 
1550
+ *Effects:* Equivalent to:
1551
+ `return is_heap_until(first, last, comp) == last;`
1552
 
1553
  ``` cpp
1554
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
1555
  bool is_heap(ExecutionPolicy&& exec,
1556
+ RandomAccessIterator first, RandomAccessIterator last,
1557
+ Compare comp);
1558
  ```
1559
 
1560
+ *Effects:* Equivalent to:
1561
 
1562
  ``` cpp
1563
+ return is_heap_until(std::forward<ExecutionPolicy>(exec), first, last, comp) == last;
1564
  ```
1565
 
1566
+ ``` cpp
1567
+ template<random_access_iterator I, sentinel_for<I> S, class Proj = identity,
1568
+ indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
1569
+ constexpr bool ranges::is_heap(I first, S last, Comp comp = {}, Proj proj = {});
1570
+ template<random_access_range R, class Proj = identity,
1571
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
1572
+ constexpr bool ranges::is_heap(R&& r, Comp comp = {}, Proj proj = {});
1573
+ ```
1574
+
1575
+ *Effects:* Equivalent to:
1576
+ `return ranges::is_heap_until(first, last, comp, proj) == last;`
1577
+
1578
  ``` cpp
1579
  template<class RandomAccessIterator>
1580
+ constexpr RandomAccessIterator
1581
+ is_heap_until(RandomAccessIterator first, RandomAccessIterator last);
1582
  template<class ExecutionPolicy, class RandomAccessIterator>
1583
+ RandomAccessIterator
1584
+ is_heap_until(ExecutionPolicy&& exec,
1585
  RandomAccessIterator first, RandomAccessIterator last);
1586
 
1587
  template<class RandomAccessIterator, class Compare>
1588
+ constexpr RandomAccessIterator
1589
+ is_heap_until(RandomAccessIterator first, RandomAccessIterator last,
1590
  Compare comp);
1591
  template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
1592
+ RandomAccessIterator
1593
+ is_heap_until(ExecutionPolicy&& exec,
1594
  RandomAccessIterator first, RandomAccessIterator last,
1595
  Compare comp);
1596
+
1597
+ template<random_access_iterator I, sentinel_for<I> S, class Proj = identity,
1598
+ indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
1599
+ constexpr I ranges::is_heap_until(I first, S last, Comp comp = {}, Proj proj = {});
1600
+ template<random_access_range R, class Proj = identity,
1601
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
1602
+ constexpr borrowed_iterator_t<R>
1603
+ ranges::is_heap_until(R&& r, Comp comp = {}, Proj proj = {});
1604
  ```
1605
 
1606
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
1607
+ no parameters by those names.
1608
+
1609
+ *Returns:* The last iterator `i` in \[`first`, `last`\] for which the
1610
+ range \[`first`, `i`) is a heap with respect to `comp` and `proj`.
1611
 
1612
  *Complexity:* Linear.
1613
 
1614
  ### Minimum and maximum <a id="alg.min.max">[[alg.min.max]]</a>
1615
 
1616
  ``` cpp
1617
+ template<class T>
1618
+ constexpr const T& min(const T& a, const T& b);
1619
  template<class T, class Compare>
1620
  constexpr const T& min(const T& a, const T& b, Compare comp);
1621
+
1622
+ template<class T, class Proj = identity,
1623
+ indirect_strict_weak_order<projected<const T*, Proj>> Comp = ranges::less>
1624
+ constexpr const T& ranges::min(const T& a, const T& b, Comp comp = {}, Proj proj = {});
1625
  ```
1626
 
1627
+ *Preconditions:* For the first form, `T` meets the
1628
+ *Cpp17LessThanComparable* requirements ([[cpp17.lessthancomparable]]).
1629
 
1630
  *Returns:* The smaller value.
1631
 
1632
  *Remarks:* Returns the first argument when the arguments are equivalent.
1633
+ An invocation may explicitly specify an argument for the template
1634
+ parameter `T` of the overloads in namespace `std`.
1635
 
1636
+ *Complexity:* Exactly one comparison and two applications of the
1637
+ projection, if any.
1638
 
1639
  ``` cpp
1640
  template<class T>
1641
+ constexpr T min(initializer_list<T> r);
1642
  template<class T, class Compare>
1643
+ constexpr T min(initializer_list<T> r, Compare comp);
1644
+
1645
+ template<copyable T, class Proj = identity,
1646
+ indirect_strict_weak_order<projected<const T*, Proj>> Comp = ranges::less>
1647
+ constexpr T ranges::min(initializer_list<T> r, Comp comp = {}, Proj proj = {});
1648
+ template<input_range R, class Proj = identity,
1649
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
1650
+ requires indirectly_copyable_storable<iterator_t<R>, range_value_t<R>*>
1651
+ constexpr range_value_t<R>
1652
+ ranges::min(R&& r, Comp comp = {}, Proj proj = {});
1653
  ```
1654
 
1655
+ *Preconditions:* `ranges::distance(r) > 0`. For the overloads in
1656
+ namespace `std`, `T` meets the *Cpp17CopyConstructible* requirements.
1657
+ For the first form, `T` meets the *Cpp17LessThanComparable* requirements
1658
+ ([[cpp17.lessthancomparable]]).
1659
 
1660
+ *Returns:* The smallest value in the input range.
1661
 
1662
+ *Remarks:* Returns a copy of the leftmost element when several elements
1663
+ are equivalent to the smallest. An invocation may explicitly specify an
1664
+ argument for the template parameter `T` of the overloads in namespace
1665
+ `std`.
1666
 
1667
+ *Complexity:* Exactly `ranges::distance(r) - 1` comparisons and twice as
1668
+ many applications of the projection, if any.
1669
 
1670
  ``` cpp
1671
+ template<class T>
1672
+ constexpr const T& max(const T& a, const T& b);
1673
  template<class T, class Compare>
1674
  constexpr const T& max(const T& a, const T& b, Compare comp);
1675
+
1676
+ template<class T, class Proj = identity,
1677
+ indirect_strict_weak_order<projected<const T*, Proj>> Comp = ranges::less>
1678
+ constexpr const T& ranges::max(const T& a, const T& b, Comp comp = {}, Proj proj = {});
1679
  ```
1680
 
1681
+ *Preconditions:* For the first form, `T` meets the
1682
+ *Cpp17LessThanComparable* requirements ([[cpp17.lessthancomparable]]).
1683
 
1684
  *Returns:* The larger value.
1685
 
1686
  *Remarks:* Returns the first argument when the arguments are equivalent.
1687
+ An invocation may explicitly specify an argument for the template
1688
+ parameter `T` of the overloads in namespace `std`.
1689
 
1690
+ *Complexity:* Exactly one comparison and two applications of the
1691
+ projection, if any.
1692
 
1693
  ``` cpp
1694
  template<class T>
1695
+ constexpr T max(initializer_list<T> r);
1696
  template<class T, class Compare>
1697
+ constexpr T max(initializer_list<T> r, Compare comp);
1698
+
1699
+ template<copyable T, class Proj = identity,
1700
+ indirect_strict_weak_order<projected<const T*, Proj>> Comp = ranges::less>
1701
+ constexpr T ranges::max(initializer_list<T> r, Comp comp = {}, Proj proj = {});
1702
+ template<input_range R, class Proj = identity,
1703
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
1704
+ requires indirectly_copyable_storable<iterator_t<R>, range_value_t<R>*>
1705
+ constexpr range_value_t<R>
1706
+ ranges::max(R&& r, Comp comp = {}, Proj proj = {});
1707
  ```
1708
 
1709
+ *Preconditions:* `ranges::distance(r) > 0`. For the overloads in
1710
+ namespace `std`, `T` meets the *Cpp17CopyConstructible* requirements.
1711
+ For the first form, `T` meets the *Cpp17LessThanComparable* requirements
1712
+ ([[cpp17.lessthancomparable]]).
1713
 
1714
+ *Returns:* The largest value in the input range.
1715
 
1716
+ *Remarks:* Returns a copy of the leftmost element when several elements
1717
+ are equivalent to the largest. An invocation may explicitly specify an
1718
+ argument for the template parameter `T` of the overloads in namespace
1719
+ `std`.
1720
 
1721
+ *Complexity:* Exactly `ranges::distance(r) - 1` comparisons and twice as
1722
+ many applications of the projection, if any.
1723
 
1724
  ``` cpp
1725
+ template<class T>
1726
+ constexpr pair<const T&, const T&> minmax(const T& a, const T& b);
1727
  template<class T, class Compare>
1728
  constexpr pair<const T&, const T&> minmax(const T& a, const T& b, Compare comp);
1729
+
1730
+ template<class T, class Proj = identity,
1731
+ indirect_strict_weak_order<projected<const T*, Proj>> Comp = ranges::less>
1732
+ constexpr ranges::minmax_result<const T&>
1733
+ ranges::minmax(const T& a, const T& b, Comp comp = {}, Proj proj = {});
1734
  ```
1735
 
1736
+ *Preconditions:* For the first form, `T` meets the
1737
+ *Cpp17LessThanComparable* requirements ([[cpp17.lessthancomparable]]).
1738
 
1739
+ *Returns:* `{b, a}` if `b` is smaller than `a`, and `{a, b}` otherwise.
 
1740
 
1741
+ *Remarks:* An invocation may explicitly specify an argument for the
1742
+ template parameter `T` of the overloads in namespace `std`.
1743
 
1744
+ *Complexity:* Exactly one comparison and two applications of the
1745
+ projection, if any.
1746
 
1747
  ``` cpp
1748
  template<class T>
1749
  constexpr pair<T, T> minmax(initializer_list<T> t);
1750
  template<class T, class Compare>
1751
  constexpr pair<T, T> minmax(initializer_list<T> t, Compare comp);
1752
+
1753
+ template<copyable T, class Proj = identity,
1754
+ indirect_strict_weak_order<projected<const T*, Proj>> Comp = ranges::less>
1755
+ constexpr ranges::minmax_result<T>
1756
+ ranges::minmax(initializer_list<T> r, Comp comp = {}, Proj proj = {});
1757
+ template<input_range R, class Proj = identity,
1758
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
1759
+ requires indirectly_copyable_storable<iterator_t<R>, range_value_t<R>*>
1760
+ constexpr ranges::minmax_result<range_value_t<R>>
1761
+ ranges::minmax(R&& r, Comp comp = {}, Proj proj = {});
1762
  ```
1763
 
1764
+ *Preconditions:* `ranges::distance(r) > 0`. For the overloads in
1765
+ namespace `std`, `T` meets the *Cpp17CopyConstructible* requirements.
1766
+ For the first form, type `T` meets the *Cpp17LessThanComparable*
1767
+ requirements ([[cpp17.lessthancomparable]]).
1768
 
1769
+ *Returns:* Let `X` be the return type. Returns `X{x, y}`, where `x` is a
1770
+ copy of the leftmost element with the smallest value and `y` a copy of
1771
+ the rightmost element with the largest value in the input range.
1772
 
1773
+ *Remarks:* An invocation may explicitly specify an argument for the
1774
+ template parameter `T` of the overloads in namespace `std`.
 
1775
 
1776
+ *Complexity:* At most (3/2)`ranges::distance(r)` applications of the
1777
+ corresponding predicate and twice as many applications of the
1778
+ projection, if any.
1779
 
1780
  ``` cpp
1781
  template<class ForwardIterator>
1782
  constexpr ForwardIterator min_element(ForwardIterator first, ForwardIterator last);
1783
 
 
1790
  Compare comp);
1791
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
1792
  ForwardIterator min_element(ExecutionPolicy&& exec,
1793
  ForwardIterator first, ForwardIterator last,
1794
  Compare comp);
1795
+
1796
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
1797
+ indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
1798
+ constexpr I ranges::min_element(I first, S last, Comp comp = {}, Proj proj = {});
1799
+ template<forward_range R, class Proj = identity,
1800
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
1801
+ constexpr borrowed_iterator_t<R>
1802
+ ranges::min_element(R&& r, Comp comp = {}, Proj proj = {});
1803
  ```
1804
 
1805
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
1806
+ no parameters by those names.
1807
+
1808
  *Returns:* The first iterator `i` in the range \[`first`, `last`) such
1809
+ that for every iterator `j` in the range \[`first`, `last`),
 
 
1810
 
1811
+ ``` cpp
1812
+ bool(invoke(comp, invoke(proj, *j), invoke(proj, *i)))
1813
+ ```
1814
+
1815
+ is `false`. Returns `last` if `first == last`.
1816
+
1817
+ *Complexity:* Exactly max(`last - first - 1`, 0) comparisons and twice
1818
+ as many projections.
1819
 
1820
  ``` cpp
1821
  template<class ForwardIterator>
1822
  constexpr ForwardIterator max_element(ForwardIterator first, ForwardIterator last);
1823
  template<class ExecutionPolicy, class ForwardIterator>
 
1829
  Compare comp);
1830
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
1831
  ForwardIterator max_element(ExecutionPolicy&& exec,
1832
  ForwardIterator first, ForwardIterator last,
1833
  Compare comp);
1834
+
1835
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
1836
+ indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
1837
+ constexpr I ranges::max_element(I first, S last, Comp comp = {}, Proj proj = {});
1838
+ template<forward_range R, class Proj = identity,
1839
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
1840
+ constexpr borrowed_iterator_t<R>
1841
+ ranges::max_element(R&& r, Comp comp = {}, Proj proj = {});
1842
  ```
1843
 
1844
+ Let `comp` be `less{}` and `proj` be `identity{}` for the overloads with
1845
+ no parameters by those names.
1846
+
1847
  *Returns:* The first iterator `i` in the range \[`first`, `last`) such
1848
+ that for every iterator `j` in the range \[`first`, `last`),
 
 
1849
 
1850
+ ``` cpp
1851
+ bool(invoke(comp, invoke(proj, *i), invoke(proj, *j)))
1852
+ ```
1853
+
1854
+ is `false`. Returns `last` if `first == last`.
1855
+
1856
+ *Complexity:* Exactly max(`last - first - 1`, 0) comparisons and twice
1857
+ as many projections.
1858
 
1859
  ``` cpp
1860
  template<class ForwardIterator>
1861
  constexpr pair<ForwardIterator, ForwardIterator>
1862
  minmax_element(ForwardIterator first, ForwardIterator last);
 
1870
  minmax_element(ForwardIterator first, ForwardIterator last, Compare comp);
1871
  template<class ExecutionPolicy, class ForwardIterator, class Compare>
1872
  pair<ForwardIterator, ForwardIterator>
1873
  minmax_element(ExecutionPolicy&& exec,
1874
  ForwardIterator first, ForwardIterator last, Compare comp);
1875
+
1876
+ template<forward_iterator I, sentinel_for<I> S, class Proj = identity,
1877
+ indirect_strict_weak_order<projected<I, Proj>> Comp = ranges::less>
1878
+ constexpr ranges::minmax_result<I>
1879
+ ranges::minmax_element(I first, S last, Comp comp = {}, Proj proj = {});
1880
+ template<forward_range R, class Proj = identity,
1881
+ indirect_strict_weak_order<projected<iterator_t<R>, Proj>> Comp = ranges::less>
1882
+ constexpr ranges::minmax_result<borrowed_iterator_t<R>>
1883
+ ranges::minmax_element(R&& r, Comp comp = {}, Proj proj = {});
1884
  ```
1885
 
1886
+ *Returns:* `{first, first}` if \[`first`, `last`) is empty, otherwise
1887
+ `{m, M}`, where `m` is the first iterator in \[`first`, `last`) such
1888
+ that no iterator in the range refers to a smaller element, and where `M`
1889
+ is the last iterator[^5] in \[`first`, `last`) such that no iterator in
1890
+ the range refers to a larger element.
1891
 
1892
+ *Complexity:* Let N be `last - first`. At most
1893
+ $\max(\bigl\lfloor{\frac{3}{2}} (N-1)\bigr\rfloor, 0)$ comparisons and
1894
+ twice as many applications of the projection, if any.
1895
 
1896
  ### Bounded value <a id="alg.clamp">[[alg.clamp]]</a>
1897
 
1898
  ``` cpp
1899
  template<class T>
1900
  constexpr const T& clamp(const T& v, const T& lo, const T& hi);
1901
  template<class T, class Compare>
1902
  constexpr const T& clamp(const T& v, const T& lo, const T& hi, Compare comp);
1903
+ template<class T, class Proj = identity,
1904
+ indirect_strict_weak_order<projected<const T*, Proj>> Comp = ranges::less>
1905
+ constexpr const T&
1906
+ ranges::clamp(const T& v, const T& lo, const T& hi, Comp comp = {}, Proj proj = {});
1907
  ```
1908
 
1909
+ Let `comp` be `less{}` for the overloads with no parameter `comp`, and
1910
+ let `proj` be `identity{}` for the overloads with no parameter `proj`.
 
1911
 
1912
+ *Preconditions:* `bool(comp(proj(hi), proj(lo)))` is `false`. For the
1913
+ first form, type `T` meets the *Cpp17LessThanComparable* requirements
1914
+ ([[cpp17.lessthancomparable]]).
1915
+
1916
+ *Returns:* `lo` if `bool(comp(proj(v), proj(lo)))` is `true`, `hi` if
1917
+ `bool(comp(proj(hi), proj(v)))` is `true`, otherwise `v`.
1918
 
1919
  [*Note 1*: If NaN is avoided, `T` can be a floating-point
1920
  type. — *end note*]
1921
 
1922
+ *Complexity:* At most two comparisons and three applications of the
1923
+ projection.
1924
 
1925
  ### Lexicographical comparison <a id="alg.lex.comparison">[[alg.lex.comparison]]</a>
1926
 
1927
  ``` cpp
1928
  template<class InputIterator1, class InputIterator2>
1929
+ constexpr bool
1930
  lexicographical_compare(InputIterator1 first1, InputIterator1 last1,
1931
  InputIterator2 first2, InputIterator2 last2);
1932
  template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
1933
  bool
1934
  lexicographical_compare(ExecutionPolicy&& exec,
1935
  ForwardIterator1 first1, ForwardIterator1 last1,
1936
  ForwardIterator2 first2, ForwardIterator2 last2);
1937
 
1938
  template<class InputIterator1, class InputIterator2, class Compare>
1939
+ constexpr bool
1940
  lexicographical_compare(InputIterator1 first1, InputIterator1 last1,
1941
  InputIterator2 first2, InputIterator2 last2,
1942
  Compare comp);
1943
+ template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
1944
+ class Compare>
1945
  bool
1946
  lexicographical_compare(ExecutionPolicy&& exec,
1947
  ForwardIterator1 first1, ForwardIterator1 last1,
1948
  ForwardIterator2 first2, ForwardIterator2 last2,
1949
  Compare comp);
1950
+
1951
+ template<input_iterator I1, sentinel_for<I1> S1, input_iterator I2, sentinel_for<I2> S2,
1952
+ class Proj1 = identity, class Proj2 = identity,
1953
+ indirect_strict_weak_order<projected<I1, Proj1>,
1954
+ projected<I2, Proj2>> Comp = ranges::less>
1955
+ constexpr bool
1956
+ ranges::lexicographical_compare(I1 first1, S1 last1, I2 first2, S2 last2,
1957
+ Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1958
+ template<input_range R1, input_range R2, class Proj1 = identity,
1959
+ class Proj2 = identity,
1960
+ indirect_strict_weak_order<projected<iterator_t<R1>, Proj1>,
1961
+ projected<iterator_t<R2>, Proj2>> Comp = ranges::less>
1962
+ constexpr bool
1963
+ ranges::lexicographical_compare(R1&& r1, R2&& r2, Comp comp = {},
1964
+ Proj1 proj1 = {}, Proj2 proj2 = {});
1965
  ```
1966
 
1967
+ *Returns:* `true` if and only if the sequence of elements defined by the
1968
+ range \[`first1`, `last1`) is lexicographically less than the sequence
1969
+ of elements defined by the range \[`first2`, `last2`).
 
1970
 
1971
  *Complexity:* At most 2 min(`last1 - first1`, `last2 - first2`)
1972
+ applications of the corresponding comparison and each projection, if
1973
+ any.
1974
 
1975
  *Remarks:* If two sequences have the same number of elements and their
1976
  corresponding elements (if any) are equivalent, then neither sequence is
1977
+ lexicographically less than the other. If one sequence is a proper
1978
+ prefix of the other, then the shorter sequence is lexicographically less
1979
+ than the longer sequence. Otherwise, the lexicographical comparison of
1980
+ the sequences yields the same result as the comparison of the first
1981
  corresponding pair of elements that are not equivalent.
1982
 
1983
  [*Example 1*:
1984
 
1985
+ `ranges::lexicographical_compare(I1, S1, I2, S2, Comp, Proj1, Proj2)`
1986
+ could be implemented as:
1987
 
1988
  ``` cpp
1989
  for ( ; first1 != last1 && first2 != last2 ; ++first1, (void) ++first2) {
1990
+ if (invoke(comp, invoke(proj1, *first1), invoke(proj2, *first2))) return true;
1991
+ if (invoke(comp, invoke(proj2, *first2), invoke(proj1, *first1))) return false;
1992
  }
1993
  return first1 == last1 && first2 != last2;
1994
  ```
1995
 
1996
  — *end example*]
1997
 
1998
  [*Note 1*: An empty sequence is lexicographically less than any
1999
  non-empty sequence, but not less than any empty sequence. — *end note*]
2000
 
2001
+ ### Three-way comparison algorithms <a id="alg.three.way">[[alg.three.way]]</a>
2002
+
2003
+ ``` cpp
2004
+ template<class InputIterator1, class InputIterator2, class Cmp>
2005
+ constexpr auto
2006
+ lexicographical_compare_three_way(InputIterator1 b1, InputIterator1 e1,
2007
+ InputIterator2 b2, InputIterator2 e2,
2008
+ Cmp comp)
2009
+ -> decltype(comp(*b1, *b2));
2010
+ ```
2011
+
2012
+ *Mandates:* `decltype(comp(*b1, *b2))` is a comparison category type.
2013
+
2014
+ *Effects:* Lexicographically compares two ranges and produces a result
2015
+ of the strongest applicable comparison category type. Equivalent to:
2016
+
2017
+ ``` cpp
2018
+ for ( ; b1 != e1 && b2 != e2; void(++b1), void(++b2) )
2019
+ if (auto cmp = comp(*b1,*b2); cmp != 0)
2020
+ return cmp;
2021
+ return b1 != e1 ? strong_ordering::greater :
2022
+ b2 != e2 ? strong_ordering::less :
2023
+ strong_ordering::equal;
2024
+ ```
2025
+
2026
+ ``` cpp
2027
+ template<class InputIterator1, class InputIterator2>
2028
+ constexpr auto
2029
+ lexicographical_compare_three_way(InputIterator1 b1, InputIterator1 e1,
2030
+ InputIterator2 b2, InputIterator2 e2);
2031
+ ```
2032
+
2033
+ *Effects:* Equivalent to:
2034
+
2035
+ ``` cpp
2036
+ return lexicographical_compare_three_way(b1, e1, b2, e2, compare_three_way());
2037
+ ```
2038
+
2039
  ### Permutation generators <a id="alg.permutation.generators">[[alg.permutation.generators]]</a>
2040
 
2041
  ``` cpp
2042
  template<class BidirectionalIterator>
2043
+ constexpr bool next_permutation(BidirectionalIterator first,
2044
  BidirectionalIterator last);
2045
 
2046
  template<class BidirectionalIterator, class Compare>
2047
+ constexpr bool next_permutation(BidirectionalIterator first,
2048
  BidirectionalIterator last, Compare comp);
2049
+
2050
+ template<bidirectional_iterator I, sentinel_for<I> S, class Comp = ranges::less,
2051
+ class Proj = identity>
2052
+ requires sortable<I, Comp, Proj>
2053
+ constexpr ranges::next_permutation_result<I>
2054
+ ranges::next_permutation(I first, S last, Comp comp = {}, Proj proj = {});
2055
+ template<bidirectional_range R, class Comp = ranges::less,
2056
+ class Proj = identity>
2057
+ requires sortable<iterator_t<R>, Comp, Proj>
2058
+ constexpr ranges::next_permutation_result<borrowed_iterator_t<R>>
2059
+ ranges::next_permutation(R&& r, Comp comp = {}, Proj proj = {});
2060
  ```
2061
 
2062
+ Let `comp` be `less{}` and `proj` be `identity{}` for overloads with no
2063
+ parameters by those names.
2064
+
2065
+ *Preconditions:* For the overloads in namespace `std`,
2066
+ `BidirectionalIterator` meets the *Cpp17ValueSwappable*
2067
+ requirements [[swappable.requirements]].
2068
 
2069
  *Effects:* Takes a sequence defined by the range \[`first`, `last`) and
2070
  transforms it into the next permutation. The next permutation is found
2071
  by assuming that the set of all permutations is lexicographically sorted
2072
+ with respect to `comp` and `proj`. If no such permutation exists,
2073
+ transforms the sequence into the first permutation; that is, the
2074
+ ascendingly-sorted one.
2075
 
2076
+ *Returns:* Let `B` be `true` if a next permutation was found and
2077
+ otherwise `false`. Returns:
2078
+
2079
+ - `B` for the overloads in namespace `std`.
2080
+ - `{ last, B }` for the overloads in namespace `ranges`.
2081
 
2082
  *Complexity:* At most `(last - first) / 2` swaps.
2083
 
2084
  ``` cpp
2085
  template<class BidirectionalIterator>
2086
+ constexpr bool prev_permutation(BidirectionalIterator first,
2087
  BidirectionalIterator last);
2088
 
2089
  template<class BidirectionalIterator, class Compare>
2090
+ constexpr bool prev_permutation(BidirectionalIterator first,
2091
  BidirectionalIterator last, Compare comp);
2092
+
2093
+ template<bidirectional_iterator I, sentinel_for<I> S, class Comp = ranges::less,
2094
+ class Proj = identity>
2095
+ requires sortable<I, Comp, Proj>
2096
+ constexpr ranges::prev_permutation_result<I>
2097
+ ranges::prev_permutation(I first, S last, Comp comp = {}, Proj proj = {});
2098
+ template<bidirectional_range R, class Comp = ranges::less,
2099
+ class Proj = identity>
2100
+ requires sortable<iterator_t<R>, Comp, Proj>
2101
+ constexpr ranges::prev_permutation_result<borrowed_iterator_t<R>>
2102
+ ranges::prev_permutation(R&& r, Comp comp = {}, Proj proj = {});
2103
  ```
2104
 
2105
+ Let `comp` be `less{}` and `proj` be `identity{}` for overloads with no
2106
+ parameters by those names.
2107
+
2108
+ *Preconditions:* For the overloads in namespace `std`,
2109
+ `BidirectionalIterator` meets the *Cpp17ValueSwappable*
2110
+ requirements [[swappable.requirements]].
2111
 
2112
  *Effects:* Takes a sequence defined by the range \[`first`, `last`) and
2113
  transforms it into the previous permutation. The previous permutation is
2114
  found by assuming that the set of all permutations is lexicographically
2115
+ sorted with respect to `comp` and `proj`. If no such permutation exists,
2116
+ transforms the sequence into the last permutation; that is, the
2117
+ descendingly-sorted one.
2118
 
2119
+ *Returns:* Let `B` be `true` if a previous permutation was found and
2120
+ otherwise `false`. Returns:
2121
+
2122
+ - `B` for the overloads in namespace `std`.
2123
+ - `{ last, B }` for the overloads in namespace `ranges`.
2124
 
2125
  *Complexity:* At most `(last - first) / 2` swaps.
2126