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