25 Algorithms library [algorithms]

25.8 Sorting and related operations [alg.sorting]

1
#
The operations in [alg.sorting] defined directly in namespace std have two versions: one that takes a function object of type Compare and one that uses an operator<.
2
#
Compare is a function object type ([function.objects]) that meets the requirements for a template parameter named BinaryPredicate ([algorithms.requirements]).
The return value of the function call operation applied to an object of type Compare, when contextually converted to bool ([conv]), yields true if the first argument of the call is less than the second, and false otherwise.
Compare comp is used throughout for algorithms assuming an ordering relation.
3
#
For all algorithms that take Compare, there is a version that uses operator< instead.
That is, comp(*i, *j) != false defaults to *i < *j != false.
For algorithms other than those described in [alg.binary.search], comp shall induce a strict weak ordering on the values.
4
#
The term strict refers to the requirement of an irreflexive relation (!comp(x, x) for all x), and the term weak to requirements that are not as strong as those for a total ordering, but stronger than those for a partial ordering.
If we define equiv(a, b) as !comp(a, b) && !comp(b, a), then the requirements are that comp and equiv both be transitive relations:
  • (4.1)
    comp(a, b) && comp(b, c) implies comp(a, c)
  • (4.2)
    equiv(a, b) && equiv(b, c) implies equiv(a, c)
[Note
: Under these conditions, it can be shown that
  • (4.3)
    equiv is an equivalence relation,
  • (4.4)
    comp induces a well-defined relation on the equivalence classes determined by equiv, and
  • (4.5)
    the induced relation is a strict total ordering.
— end note
]
5
#
A sequence is sorted with respect to a comp and proj for a comparator and projection comp and proj if for every iterator i pointing to the sequence and every non-negative integer n such that i + n is a valid iterator pointing to an element of the sequence, 
bool(invoke(comp, invoke(proj, *(i + n)), invoke(proj, *i)))
is false.
6
#
A sequence [start, finish) is partitioned with respect to an expression f(e) if there exists an integer n such that for all 0 <= i < (finish - start), f(*(start + i)) is true if and only if i < n.
7
#
In the descriptions of the functions that deal with ordering relationships we frequently use a notion of equivalence to describe concepts such as stability.
The equivalence to which we refer is not necessarily an operator==, but an equivalence relation induced by the strict weak ordering.
That is, two elements a and b are considered equivalent if and only if !(a < b) && !(b < a).

25.8.1 Sorting [alg.sort]

25.8.1.1 sort [sort]

🔗
template<class RandomAccessIterator> constexpr void sort(RandomAccessIterator first, RandomAccessIterator last); template<class ExecutionPolicy, class RandomAccessIterator> void sort(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator last); template<class RandomAccessIterator, class Compare> constexpr void sort(RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<class ExecutionPolicy, class RandomAccessIterator, class Compare> void sort(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<random_­access_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> constexpr I ranges::sort(I first, S last, Comp comp = {}, Proj proj = {}); template<random_­access_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> constexpr borrowed_iterator_t<R> ranges::sort(R&& r, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: For the overloads in namespace std, RandomAccessIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]) and the type of *first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
3
#
Effects: Sorts the elements in the range [first, last) with respect to comp and proj.
4
#
Returns: last for the overloads in namespace ranges.
5
#
Complexity: Let N be last - first.
comparisons and projections.

25.8.1.2 stable_­sort [stable.sort]

🔗
template<class RandomAccessIterator> void stable_sort(RandomAccessIterator first, RandomAccessIterator last); template<class ExecutionPolicy, class RandomAccessIterator> void stable_sort(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator last); template<class RandomAccessIterator, class Compare> void stable_sort(RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<class ExecutionPolicy, class RandomAccessIterator, class Compare> void stable_sort(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<random_­access_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> I ranges::stable_sort(I first, S last, Comp comp = {}, Proj proj = {}); template<random_­access_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> borrowed_iterator_t<R> ranges::stable_sort(R&& r, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: For the overloads in namespace std, RandomAccessIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]) and the type of *first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
3
#
Effects: Sorts the elements in the range [first, last) with respect to comp and proj.
4
#
Returns: last for the overloads in namespace ranges.
5
#
Complexity: Let N be last - first.
If enough extra memory is available, comparisons.
Otherwise, at most comparisons.
In either case, twice as many projections as the number of comparisons.
6
#
Remarks: Stable ([algorithm.stable]).

25.8.1.3 partial_­sort [partial.sort]

🔗
template<class RandomAccessIterator> constexpr void partial_sort(RandomAccessIterator first, RandomAccessIterator middle, RandomAccessIterator last); template<class ExecutionPolicy, class RandomAccessIterator> void partial_sort(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator middle, RandomAccessIterator last); template<class RandomAccessIterator, class Compare> constexpr void partial_sort(RandomAccessIterator first, RandomAccessIterator middle, RandomAccessIterator last, Compare comp); template<class ExecutionPolicy, class RandomAccessIterator, class Compare> void partial_sort(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator middle, RandomAccessIterator last, Compare comp); template<random_­access_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> constexpr I ranges::partial_sort(I first, I middle, S last, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: [first, middle) and [middle, last) are valid ranges.
For the overloads in namespace std, RandomAccessIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]) and the type of *first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
3
#
Effects: Places the first middle - first elements from the range [first, last) as sorted with respect to comp and proj into the range [first, middle).
The rest of the elements in the range [middle, last) are placed in an unspecified order.
4
#
Returns: last for the overload in namespace ranges.
5
#
Complexity: Approximately (last - first) * log(middle - first) comparisons, and twice as many projections.
🔗
template<random_­access_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> constexpr borrowed_iterator_t<R> ranges::partial_sort(R&& r, iterator_t<R> middle, Comp comp = {}, Proj proj = {});
6
#
Effects: Equivalent to: 
return ranges::partial_sort(ranges::begin(r), middle, ranges::end(r), comp, proj);

25.8.1.4 partial_­sort_­copy [partial.sort.copy]

🔗
template<class InputIterator, class RandomAccessIterator> constexpr RandomAccessIterator partial_sort_copy(InputIterator first, InputIterator last, RandomAccessIterator result_first, RandomAccessIterator result_last); template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterator> RandomAccessIterator partial_sort_copy(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, RandomAccessIterator result_first, RandomAccessIterator result_last); template<class InputIterator, class RandomAccessIterator, class Compare> constexpr RandomAccessIterator partial_sort_copy(InputIterator first, InputIterator last, RandomAccessIterator result_first, RandomAccessIterator result_last, Compare comp); template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterator, class Compare> RandomAccessIterator partial_sort_copy(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, RandomAccessIterator result_first, RandomAccessIterator result_last, Compare comp); template<input_­iterator I1, sentinel_­for<I1> S1, random_­access_­iterator I2, sentinel_­for<I2> S2, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires indirectly_­copyable<I1, I2> && sortable<I2, Comp, Proj2> && indirect_­strict_­weak_­order<Comp, projected<I1, Proj1>, projected<I2, Proj2>> constexpr ranges::partial_sort_copy_result<I1, I2> ranges::partial_sort_copy(I1 first, S1 last, I2 result_first, S2 result_last, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}); template<input_­range R1, random_­access_­range R2, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires indirectly_­copyable<iterator_t<R1>, iterator_t<R2>> && sortable<iterator_t<R2>, Comp, Proj2> && indirect_­strict_­weak_­order<Comp, projected<iterator_t<R1>, Proj1>, projected<iterator_t<R2>, Proj2>> constexpr ranges::partial_sort_copy_result<borrowed_iterator_t<R1>, borrowed_iterator_t<R2>> ranges::partial_sort_copy(R1&& r, R2&& result_r, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1
#
Let N be .
Let comp be less{}, and proj1 and proj2 be identity{} for the overloads with no parameters by those names.
2
#
Mandates: For the overloads in namespace std, the expression *first is writable ([iterator.requirements.general]) to result_­first.
3
#
Preconditions: For the overloads in namespace std, RandomAccessIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]), the type of *result_­first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
4
#
Preconditions: For iterators a1 and b1 in [first, last), and iterators x2 and y2 in [result_­first, result_­last), after evaluating the assignment *y2 = *b1, let E be the value of 
bool(invoke(comp, invoke(proj1, *a1), invoke(proj2, *y2))).
Then, after evaluating the assignment *x2 = *a1, E is equal to 
bool(invoke(comp, invoke(proj2, *x2), invoke(proj2, *y2))).
[Note
: Writing a value from the input range into the output range does not affect how it is ordered by comp and proj1 or proj2. — end note
]
5
#
Effects: Places the first N elements as sorted with respect to comp and proj2 into the range [result_­first, result_­first + N).
6
#
Returns:
  • (6.1)
    result_­first + N for the overloads in namespace std.
  • (6.2)
    {last, result_­first + N} for the overloads in namespace ranges.
7
#
Complexity: Approximately (last - first) * log N comparisons, and twice as many projections.

25.8.1.5 is_­sorted [is.sorted]

🔗
template<class ForwardIterator> constexpr bool is_sorted(ForwardIterator first, ForwardIterator last);
1
#
Effects: Equivalent to: return is_­sorted_­until(first, last) == last;
🔗
template<class ExecutionPolicy, class ForwardIterator> bool is_sorted(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last);
2
#
Effects: Equivalent to: 
return is_sorted_until(std::forward<ExecutionPolicy>(exec), first, last) == last;
🔗
template<class ForwardIterator, class Compare> constexpr bool is_sorted(ForwardIterator first, ForwardIterator last, Compare comp);
3
#
Effects: Equivalent to: return is_­sorted_­until(first, last, comp) == last;
🔗
template<class ExecutionPolicy, class ForwardIterator, class Compare> bool is_sorted(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, Compare comp);
4
#
Effects: Equivalent to: 
return is_sorted_until(std::forward<ExecutionPolicy>(exec), first, last, comp) == last;
🔗
template<forward_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­strict_­weak_­order<projected<I, Proj>> Comp = ranges::less> constexpr bool ranges::is_sorted(I first, S last, Comp comp = {}, Proj proj = {}); template<forward_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr bool ranges::is_sorted(R&& r, Comp comp = {}, Proj proj = {});
5
#
Effects: Equivalent to: return ranges​::​is_­sorted_­until(first, last, comp, proj) == last;
🔗
template<class ForwardIterator> constexpr ForwardIterator is_sorted_until(ForwardIterator first, ForwardIterator last); template<class ExecutionPolicy, class ForwardIterator> ForwardIterator is_sorted_until(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last); template<class ForwardIterator, class Compare> constexpr ForwardIterator is_sorted_until(ForwardIterator first, ForwardIterator last, Compare comp); template<class ExecutionPolicy, class ForwardIterator, class Compare> ForwardIterator is_sorted_until(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, Compare comp); template<forward_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­strict_­weak_­order<projected<I, Proj>> Comp = ranges::less> constexpr I ranges::is_sorted_until(I first, S last, Comp comp = {}, Proj proj = {}); template<forward_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_iterator_t<R> ranges::is_sorted_until(R&& r, Comp comp = {}, Proj proj = {});
6
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
7
#
Returns: The last iterator i in [first, last] for which the range [first, i) is sorted with respect to comp and proj.
8
#
Complexity: Linear.

25.8.2 Nth element [alg.nth.element]

🔗
template<class RandomAccessIterator> constexpr void nth_element(RandomAccessIterator first, RandomAccessIterator nth, RandomAccessIterator last); template<class ExecutionPolicy, class RandomAccessIterator> void nth_element(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator nth, RandomAccessIterator last); template<class RandomAccessIterator, class Compare> constexpr void nth_element(RandomAccessIterator first, RandomAccessIterator nth, RandomAccessIterator last, Compare comp); template<class ExecutionPolicy, class RandomAccessIterator, class Compare> void nth_element(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator nth, RandomAccessIterator last, Compare comp); template<random_­access_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> constexpr I ranges::nth_element(I first, I nth, S last, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: [first, nth) and [nth, last) are valid ranges.
For the overloads in namespace std, RandomAccessIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]), and the type of *first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
3
#
Effects: After nth_­element the element in the position pointed to by nth is the element that would be in that position if the whole range were sorted with respect to comp and proj, unless nth == last.
Also for every iterator i in the range [first, nth) and every iterator j in the range [nth, last) it holds that: bool(invoke(comp, invoke(proj, *j), invoke(proj, *i))) is false.
4
#
Returns: last for the overload in namespace ranges.
5
#
Complexity: For the overloads with no ExecutionPolicy, linear on average.
For the overloads with an ExecutionPolicy, applications of the predicate, and swaps, where .
🔗
template<random_­access_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> constexpr borrowed_iterator_t<R> ranges::nth_element(R&& r, iterator_t<R> nth, Comp comp = {}, Proj proj = {});
6
#
Effects: Equivalent to: 
return ranges::nth_element(ranges::begin(r), nth, ranges::end(r), comp, proj);

25.8.3 Binary search [alg.binary.search]

1
#
All of the algorithms in this subclause are versions of binary search and assume that the sequence being searched is partitioned with respect to an expression formed by binding the search key to an argument of the comparison function.
They work on non-random access iterators minimizing the number of comparisons, which will be logarithmic for all types of iterators.
They are especially appropriate for random access iterators, because these algorithms do a logarithmic number of steps through the data structure.
For non-random access iterators they execute a linear number of steps.

25.8.3.1 lower_­bound [lower.bound]

🔗
template<class ForwardIterator, class T> constexpr ForwardIterator lower_bound(ForwardIterator first, ForwardIterator last, const T& value); template<class ForwardIterator, class T, class Compare> constexpr ForwardIterator lower_bound(ForwardIterator first, ForwardIterator last, const T& value, Compare comp); template<forward_­iterator I, sentinel_­for<I> S, class T, class Proj = identity, indirect_­strict_­weak_­order<const T*, projected<I, Proj>> Comp = ranges::less> constexpr I ranges::lower_bound(I first, S last, const T& value, Comp comp = {}, Proj proj = {}); template<forward_­range R, class T, class Proj = identity, indirect_­strict_­weak_­order<const T*, projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_iterator_t<R> ranges::lower_bound(R&& r, const T& value, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
2
#
Preconditions: The elements e of [first, last) are partitioned with respect to the expression bool(invoke(comp, invoke(proj, e), value)).
3
#
Returns: The furthermost iterator i in the range [first, last] such that for every iterator j in the range [first, i), bool(invoke(comp, invoke(proj, *j), value)) is true.
4
#
Complexity: At most comparisons and projections.

25.8.3.2 upper_­bound [upper.bound]

🔗
template<class ForwardIterator, class T> constexpr ForwardIterator upper_bound(ForwardIterator first, ForwardIterator last, const T& value); template<class ForwardIterator, class T, class Compare> constexpr ForwardIterator upper_bound(ForwardIterator first, ForwardIterator last, const T& value, Compare comp); template<forward_­iterator I, sentinel_­for<I> S, class T, class Proj = identity, indirect_­strict_­weak_­order<const T*, projected<I, Proj>> Comp = ranges::less> constexpr I ranges::upper_bound(I first, S last, const T& value, Comp comp = {}, Proj proj = {}); template<forward_­range R, class T, class Proj = identity, indirect_­strict_­weak_­order<const T*, projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_iterator_t<R> ranges::upper_bound(R&& r, const T& value, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
2
#
Preconditions: The elements e of [first, last) are partitioned with respect to the expression !bool(invoke(comp, value, invoke(proj, e))).
3
#
Returns: The furthermost iterator i in the range [first, last] such that for every iterator j in the range [first, i), !bool(invoke(comp, value, invoke(proj, *j))) is true.
4
#
Complexity: At most comparisons and projections.

25.8.3.3 equal_­range [equal.range]

🔗
template<class ForwardIterator, class T> constexpr pair<ForwardIterator, ForwardIterator> equal_range(ForwardIterator first, ForwardIterator last, const T& value); template<class ForwardIterator, class T, class Compare> constexpr pair<ForwardIterator, ForwardIterator> equal_range(ForwardIterator first, ForwardIterator last, const T& value, Compare comp); template<forward_­iterator I, sentinel_­for<I> S, class T, class Proj = identity, indirect_­strict_­weak_­order<const T*, projected<I, Proj>> Comp = ranges::less> constexpr subrange<I> ranges::equal_range(I first, S last, const T& value, Comp comp = {}, Proj proj = {}); template<forward_­range R, class T, class Proj = identity, indirect_­strict_­weak_­order<const T*, projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_subrange_t<R> ranges::equal_range(R&& r, const T& value, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
2
#
Preconditions: The elements e of [first, last) are partitioned with respect to the expressions bool(invoke(comp, invoke(proj, e), value)) and !bool(invoke(comp, value, invoke(proj, e))).
Also, for all elements e of [first, last), bool(comp(e, value)) implies !bool(comp(​value, e)) for the overloads in namespace std.
3
#
Returns:
  • (3.1)
    For the overloads in namespace std: 
    {lower_bound(first, last, value, comp),
 upper_bound(first, last, value, comp)}
  • (3.2)
    For the overloads in namespace ranges: 
    {ranges::lower_bound(first, last, value, comp, proj),
 ranges::upper_bound(first, last, value, comp, proj)}
4
#
Complexity: At most comparisons and projections.

25.8.3.4 binary_­search [binary.search]

🔗
template<class ForwardIterator, class T> constexpr bool binary_search(ForwardIterator first, ForwardIterator last, const T& value); template<class ForwardIterator, class T, class Compare> constexpr bool binary_search(ForwardIterator first, ForwardIterator last, const T& value, Compare comp); template<forward_­iterator I, sentinel_­for<I> S, class T, class Proj = identity, indirect_­strict_­weak_­order<const T*, projected<I, Proj>> Comp = ranges::less> constexpr bool ranges::binary_search(I first, S last, const T& value, Comp comp = {}, Proj proj = {}); template<forward_­range R, class T, class Proj = identity, indirect_­strict_­weak_­order<const T*, projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr bool ranges::binary_search(R&& r, const T& value, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
2
#
Preconditions: The elements e of [first, last) are partitioned with respect to the expressions bool(invoke(comp, invoke(proj, e), value)) and !bool(invoke(comp, value, invoke(proj, e))).
Also, for all elements e of [first, last), bool(comp(e, value)) implies !bool(comp(​value, e)) for the overloads in namespace std.
3
#
Returns: true if and only if for some iterator i in the range [first, last), !bool(invoke(comp, invoke(proj, *i), value)) && !bool(invoke(comp, value, invoke(proj, *i))) is true.
4
#
Complexity: At most comparisons and projections.

25.8.4 Partitions [alg.partitions]

🔗
template<class InputIterator, class Predicate> constexpr bool is_partitioned(InputIterator first, InputIterator last, Predicate pred); template<class ExecutionPolicy, class ForwardIterator, class Predicate> bool is_partitioned(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, Predicate pred); template<input_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­unary_­predicate<projected<I, Proj>> Pred> constexpr bool ranges::is_partitioned(I first, S last, Pred pred, Proj proj = {}); template<input_­range R, class Proj = identity, indirect_­unary_­predicate<projected<iterator_t<R>, Proj>> Pred> constexpr bool ranges::is_partitioned(R&& r, Pred pred, Proj proj = {});
1
#
Let proj be identity{} for the overloads with no parameter named proj.
2
#
Returns: true if and only if the elements e of [first, last) are partitioned with respect to the expression bool(invoke(pred, invoke(proj, e))).
3
#
Complexity: Linear.
At most last - first applications of pred and proj.
🔗
template<class ForwardIterator, class Predicate> constexpr ForwardIterator partition(ForwardIterator first, ForwardIterator last, Predicate pred); template<class ExecutionPolicy, class ForwardIterator, class Predicate> ForwardIterator partition(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, Predicate pred); template<permutable I, sentinel_­for<I> S, class Proj = identity, indirect_­unary_­predicate<projected<I, Proj>> Pred> constexpr subrange<I> ranges::partition(I first, S last, Pred pred, Proj proj = {}); template<forward_­range R, class Proj = identity, indirect_­unary_­predicate<projected<iterator_t<R>, Proj>> Pred> requires permutable<iterator_t<R>> constexpr borrowed_subrange_t<R> ranges::partition(R&& r, Pred pred, Proj proj = {});
4
#
Let proj be identity{} for the overloads with no parameter named proj and let E(x) be bool(invoke(​pred, invoke(proj, x))).
5
#
Preconditions: For the overloads in namespace std, ForwardIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]).
6
#
Effects: Places all the elements e in [first, last) that satisfy E(e) before all the elements that do not.
7
#
Returns: Let i be an iterator such that is true for every iterator j in [first, i) and false for every iterator j in [i, last).
Returns:
  • (7.1)
    i for the overloads in namespace std.
  • (7.2)
    {i, last} for the overloads in namespace ranges.
8
#
Complexity: Let :
  • (8.1)
    For the overload with no ExecutionPolicy, exactly N applications of the predicate and projection. At most swaps if the type of first meets the Cpp17BidirectionalIterator requirements for the overloads in namespace std or models bidirectional_­iterator for the overloads in namespace ranges, and at most N swaps otherwise.
  • (8.2)
    For the overload with an ExecutionPolicy, swaps and applications of the predicate.
🔗
template<class BidirectionalIterator, class Predicate> BidirectionalIterator stable_partition(BidirectionalIterator first, BidirectionalIterator last, Predicate pred); template<class ExecutionPolicy, class BidirectionalIterator, class Predicate> BidirectionalIterator stable_partition(ExecutionPolicy&& exec, BidirectionalIterator first, BidirectionalIterator last, Predicate pred); template<bidirectional_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­unary_­predicate<projected<I, Proj>> Pred> requires permutable<I> subrange<I> ranges::stable_partition(I first, S last, Pred pred, Proj proj = {}); template<bidirectional_­range R, class Proj = identity, indirect_­unary_­predicate<projected<iterator_t<R>, Proj>> Pred> requires permutable<iterator_t<R>> borrowed_subrange_t<R> ranges::stable_partition(R&& r, Pred pred, Proj proj = {});
9
#
Let proj be identity{} for the overloads with no parameter named proj and let E(x) be bool(invoke(​pred, invoke(proj, x))).
10
#
Preconditions: For the overloads in namespace std, BidirectionalIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]) and the type of *first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
11
#
Effects: Places all the elements e in [first, last) that satisfy E(e) before all the elements that do not.
The relative order of the elements in both groups is preserved.
12
#
Returns: Let i be an iterator such that for every iterator j in [first, i), is true, and for every iterator j in the range [i, last), is false.
Returns:
  • (12.1)
    i for the overloads in namespace std.
  • (12.2)
    {i, last} for the overloads in namespace ranges.
13
#
Complexity: Let N = last - first:
  • (13.1)
    For the overloads with no ExecutionPolicy, at most swaps, but only swaps if there is enough extra memory. Exactly N applications of the predicate and projection.
  • (13.2)
    For the overload with an ExecutionPolicy, swaps and applications of the predicate.
🔗
template<class InputIterator, class OutputIterator1, class OutputIterator2, class Predicate> constexpr pair<OutputIterator1, OutputIterator2> partition_copy(InputIterator first, InputIterator last, OutputIterator1 out_true, OutputIterator2 out_false, Predicate pred); template<class ExecutionPolicy, class ForwardIterator, class ForwardIterator1, class ForwardIterator2, class Predicate> pair<ForwardIterator1, ForwardIterator2> partition_copy(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, ForwardIterator1 out_true, ForwardIterator2 out_false, Predicate pred); template<input_­iterator I, sentinel_­for<I> S, weakly_­incrementable O1, weakly_­incrementable O2, class Proj = identity, indirect_­unary_­predicate<projected<I, Proj>> Pred> requires indirectly_­copyable<I, O1> && indirectly_­copyable<I, O2> constexpr ranges::partition_copy_result<I, O1, O2> ranges::partition_copy(I first, S last, O1 out_true, O2 out_false, Pred pred, Proj proj = {}); template<input_­range R, weakly_­incrementable O1, weakly_­incrementable O2, class Proj = identity, indirect_­unary_­predicate<projected<iterator_t<R>, Proj>> Pred> requires indirectly_­copyable<iterator_t<R>, O1> && indirectly_­copyable<iterator_t<R>, O2> constexpr ranges::partition_copy_result<borrowed_iterator_t<R>, O1, O2> ranges::partition_copy(R&& r, O1 out_true, O2 out_false, Pred pred, Proj proj = {});
14
#
Let proj be identity{} for the overloads with no parameter named proj and let E(x) be bool(invoke(​pred, invoke(proj, x))).
15
#
Mandates: For the overloads in namespace std, the expression *first is writable ([iterator.requirements.general]) to out_­true and out_­false.
16
#
Preconditions: The input range and output ranges do not overlap.
[Note
:
For the overload with an ExecutionPolicy, there may be a performance cost if first's value type does not meet the Cpp17CopyConstructible requirements.
— end note
]
17
#
Effects: For each iterator i in [first, last), copies *i to the output range beginning with out_­true if is true, or to the output range beginning with out_­false otherwise.
18
#
Returns: Let o1 be the end of the output range beginning at out_­true, and o2 the end of the output range beginning at out_­false.
Returns
  • (18.1)
    {o1, o2} for the overloads in namespace std.
  • (18.2)
    {last, o1, o2} for the overloads in namespace ranges.
19
#
Complexity: Exactly last - first applications of pred and proj.
🔗
template<class ForwardIterator, class Predicate> constexpr ForwardIterator partition_point(ForwardIterator first, ForwardIterator last, Predicate pred); template<forward_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­unary_­predicate<projected<I, Proj>> Pred> constexpr I ranges::partition_point(I first, S last, Pred pred, Proj proj = {}); template<forward_­range R, class Proj = identity, indirect_­unary_­predicate<projected<iterator_t<R>, Proj>> Pred> constexpr borrowed_iterator_t<R> ranges::partition_point(R&& r, Pred pred, Proj proj = {});
20
#
Let proj be identity{} for the overloads with no parameter named proj and let E(x) be bool(invoke(​pred, invoke(proj, x))).
21
#
Preconditions: The elements e of [first, last) are partitioned with respect to E(e).
22
#
Returns: An iterator mid such that is true for all iterators i in [first, mid), and false for all iterators i in [mid, last).
23
#
Complexity: applications of pred and proj.

25.8.5 Merge [alg.merge]

🔗
template<class InputIterator1, class InputIterator2, class OutputIterator> constexpr OutputIterator merge(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator> ForwardIterator merge(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result); template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare> constexpr OutputIterator merge(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result, Compare comp); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare> ForwardIterator merge(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result, Compare comp); template<input_­iterator I1, sentinel_­for<I1> S1, input_­iterator I2, sentinel_­for<I2> S2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<I1, I2, O, Comp, Proj1, Proj2> constexpr ranges::merge_result<I1, I2, O> ranges::merge(I1 first1, S1 last1, I2 first2, S2 last2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}); template<input_­range R1, input_­range R2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2> constexpr ranges::merge_result<borrowed_iterator_t<R1>, borrowed_iterator_t<R2>, O> ranges::merge(R1&& r1, R2&& r2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1
#
Let N be (last1 - first1) + (last2 - first2).
Let comp be less{}, proj1 be identity{}, and proj2 be identity{}, for the overloads with no parameters by those names.
2
#
Preconditions: The ranges [first1, last1) and [first2, last2) are sorted with respect to comp and proj1 or proj2, respectively.
The resulting range does not overlap with either of the original ranges.
3
#
Effects: Copies all the elements of the two ranges [first1, last1) and [first2, last2) into the range [result, result_­last), where result_­last is result + N.
If an element a precedes b in an input range, a is copied into the output range before b.
If e1 is an element of [first1, last1) and e2 of [first2, last2), e2 is copied into the output range before e1 if and only if bool(invoke(comp, invoke(proj2, e2), invoke(proj1, e1))) is true.
4
#
Returns:
  • (4.1)
    result_­last for the overloads in namespace std.
  • (4.2)
    {last1, last2, result_­last} for the overloads in namespace ranges.
5
#
Complexity:
  • (5.1)
    For the overloads with no ExecutionPolicy, at most comparisons and applications of each projection.
  • (5.2)
    For the overloads with an ExecutionPolicy, comparisons.
6
#
Remarks: Stable ([algorithm.stable]).
🔗
template<class BidirectionalIterator> void inplace_merge(BidirectionalIterator first, BidirectionalIterator middle, BidirectionalIterator last); template<class ExecutionPolicy, class BidirectionalIterator> void inplace_merge(ExecutionPolicy&& exec, BidirectionalIterator first, BidirectionalIterator middle, BidirectionalIterator last); template<class BidirectionalIterator, class Compare> void inplace_merge(BidirectionalIterator first, BidirectionalIterator middle, BidirectionalIterator last, Compare comp); template<class ExecutionPolicy, class BidirectionalIterator, class Compare> void inplace_merge(ExecutionPolicy&& exec, BidirectionalIterator first, BidirectionalIterator middle, BidirectionalIterator last, Compare comp); template<bidirectional_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> I ranges::inplace_merge(I first, I middle, S last, Comp comp = {}, Proj proj = {});
7
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
8
#
Preconditions: [first, middle) and [middle, last) are valid ranges sorted with respect to comp and proj.
For the overloads in namespace std, BidirectionalIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]) and the type of *first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
9
#
Effects: Merges two sorted consecutive ranges [first, middle) and [middle, last), putting the result of the merge into the range [first, last).
The resulting range is sorted with respect to comp and proj.
10
#
Returns: last for the overload in namespace ranges.
11
#
Complexity: Let :
  • (11.1)
    For the overloads with no ExecutionPolicy, and if enough additional memory is available, exactly comparisons.
  • (11.2)
    Otherwise, comparisons.
In either case, twice as many projections as comparisons.
12
#
Remarks: Stable.
🔗
template<bidirectional_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> borrowed_iterator_t<R> ranges::inplace_merge(R&& r, iterator_t<R> middle, Comp comp = {}, Proj proj = {});
13
#
Effects: Equivalent to: 
return ranges::inplace_merge(ranges::begin(r), middle, ranges::end(r), comp, proj);

25.8.6 Set operations on sorted structures [alg.set.operations]

1
#
This subclause defines all the basic set operations on sorted structures.
They also work with multisets ([multiset]) containing multiple copies of equivalent elements.
The semantics of the set operations are generalized to multisets in a standard way by defining set_­union to contain the maximum number of occurrences of every element, set_­intersection to contain the minimum, and so on.

25.8.6.1 includes [includes]

🔗
template<class InputIterator1, class InputIterator2> constexpr bool includes(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2> bool includes(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2); template<class InputIterator1, class InputIterator2, class Compare> constexpr bool includes(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, Compare comp); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Compare> bool includes(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, Compare comp); template<input_­iterator I1, sentinel_­for<I1> S1, input_­iterator I2, sentinel_­for<I2> S2, class Proj1 = identity, class Proj2 = identity, indirect_­strict_­weak_­order<projected<I1, Proj1>, projected<I2, Proj2>> Comp = ranges::less> constexpr bool ranges::includes(I1 first1, S1 last1, I2 first2, S2 last2, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}); template<input_­range R1, input_­range R2, class Proj1 = identity, class Proj2 = identity, indirect_­strict_­weak_­order<projected<iterator_t<R1>, Proj1>, projected<iterator_t<R2>, Proj2>> Comp = ranges::less> constexpr bool ranges::includes(R1&& r1, R2&& r2, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1
#
Let comp be less{}, proj1 be identity{}, and proj2 be identity{}, for the overloads with no parameters by those names.
2
#
Preconditions: The ranges [first1, last1) and [first2, last2) are sorted with respect to comp and proj1 or proj2, respectively.
3
#
Returns: true if and only if [first2, last2) is a subsequence of [first1, last1).
[Note
:
A sequence S is a subsequence of another sequence T if S can be obtained from T by removing some, all, or none of T's elements and keeping the remaining elements in the same order.
— end note
]
4
#
Complexity: At most 2 * ((last1 - first1) + (last2 - first2)) - 1 comparisons and applications of each projection.

25.8.6.2 set_­union [set.union]

🔗
template<class InputIterator1, class InputIterator2, class OutputIterator> constexpr OutputIterator set_union(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator> ForwardIterator set_union(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result); template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare> constexpr OutputIterator set_union(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result, Compare comp); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare> ForwardIterator set_union(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result, Compare comp); template<input_­iterator I1, sentinel_­for<I1> S1, input_­iterator I2, sentinel_­for<I2> S2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<I1, I2, O, Comp, Proj1, Proj2> constexpr ranges::set_union_result<I1, I2, O> ranges::set_union(I1 first1, S1 last1, I2 first2, S2 last2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}); template<input_­range R1, input_­range R2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2> constexpr ranges::set_union_result<borrowed_iterator_t<R1>, borrowed_iterator_t<R2>, O> ranges::set_union(R1&& r1, R2&& r2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1
#
Let comp be less{}, and proj1 and proj2 be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: The ranges [first1, last1) and [first2, last2) are sorted with respect to comp and proj1 or proj2, respectively.
The resulting range does not overlap with either of the original ranges.
3
#
Effects: Constructs a sorted union of the elements from the two ranges; that is, the set of elements that are present in one or both of the ranges.
4
#
Returns: Let result_­last be the end of the constructed range.
Returns
  • (4.1)
    result_­last for the overloads in namespace std.
  • (4.2)
    {last1, last2, result_­last} for the overloads in namespace ranges.
5
#
Complexity: At most 2 * ((last1 - first1) + (last2 - first2)) - 1 comparisons and applications of each projection.
6
#
Remarks: Stable ([algorithm.stable]).
If [first1, last1) contains m elements that are equivalent to each other and [first2, last2) contains n elements that are equivalent to them, then all m elements from the first range are copied to the output range, in order, and then the final elements from the second range are copied to the output range, in order.

25.8.6.3 set_­intersection [set.intersection]

🔗
template<class InputIterator1, class InputIterator2, class OutputIterator> constexpr OutputIterator set_intersection(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator> ForwardIterator set_intersection(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result); template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare> constexpr OutputIterator set_intersection(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result, Compare comp); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare> ForwardIterator set_intersection(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result, Compare comp); template<input_­iterator I1, sentinel_­for<I1> S1, input_­iterator I2, sentinel_­for<I2> S2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<I1, I2, O, Comp, Proj1, Proj2> constexpr ranges::set_intersection_result<I1, I2, O> ranges::set_intersection(I1 first1, S1 last1, I2 first2, S2 last2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}); template<input_­range R1, input_­range R2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2> constexpr ranges::set_intersection_result<borrowed_iterator_t<R1>, borrowed_iterator_t<R2>, O> ranges::set_intersection(R1&& r1, R2&& r2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1
#
Let comp be less{}, and proj1 and proj2 be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: The ranges [first1, last1) and [first2, last2) are sorted with respect to comp and proj1 or proj2, respectively.
The resulting range does not overlap with either of the original ranges.
3
#
Effects: Constructs a sorted intersection of the elements from the two ranges; that is, the set of elements that are present in both of the ranges.
4
#
Returns: Let result_­last be the end of the constructed range.
Returns
  • (4.1)
    result_­last for the overloads in namespace std.
  • (4.2)
    {last1, last2, result_­last} for the overloads in namespace ranges.
5
#
Complexity: At most 2 * ((last1 - first1) + (last2 - first2)) - 1 comparisons and applications of each projection.
6
#
Remarks: Stable ([algorithm.stable]).
If [first1, last1) contains m elements that are equivalent to each other and [first2, last2) contains n elements that are equivalent to them, the first elements are copied from the first range to the output range, in order.

25.8.6.4 set_­difference [set.difference]

🔗
template<class InputIterator1, class InputIterator2, class OutputIterator> constexpr OutputIterator set_difference(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator> ForwardIterator set_difference(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result); template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare> constexpr OutputIterator set_difference(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result, Compare comp); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare> ForwardIterator set_difference(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result, Compare comp); template<input_­iterator I1, sentinel_­for<I1> S1, input_­iterator I2, sentinel_­for<I2> S2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<I1, I2, O, Comp, Proj1, Proj2> constexpr ranges::set_difference_result<I1, O> ranges::set_difference(I1 first1, S1 last1, I2 first2, S2 last2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}); template<input_­range R1, input_­range R2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2> constexpr ranges::set_difference_result<borrowed_iterator_t<R1>, O> ranges::set_difference(R1&& r1, R2&& r2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1
#
Let comp be less{}, and proj1 and proj2 be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: The ranges [first1, last1) and [first2, last2) are sorted with respect to comp and proj1 or proj2, respectively.
The resulting range does not overlap with either of the original ranges.
3
#
Effects: Copies the elements of the range [first1, last1) which are not present in the range [first2, last2) to the range beginning at result.
The elements in the constructed range are sorted.
4
#
Returns: Let result_­last be the end of the constructed range.
Returns
  • (4.1)
    result_­last for the overloads in namespace std.
  • (4.2)
    {last1, result_­last} for the overloads in namespace ranges.
5
#
Complexity: At most 2 * ((last1 - first1) + (last2 - first2)) - 1 comparisons and applications of each projection.
6
#
Remarks: If [first1, last1) contains m elements that are equivalent to each other and [first2, last2) contains n elements that are equivalent to them, the last elements from [first1, last1) is copied to the output range, in order.

25.8.6.5 set_­symmetric_­difference [set.symmetric.difference]

🔗
template<class InputIterator1, class InputIterator2, class OutputIterator> constexpr OutputIterator set_symmetric_difference(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator> ForwardIterator set_symmetric_difference(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result); template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare> constexpr OutputIterator set_symmetric_difference(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result, Compare comp); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare> ForwardIterator set_symmetric_difference(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, ForwardIterator result, Compare comp); template<input_­iterator I1, sentinel_­for<I1> S1, input_­iterator I2, sentinel_­for<I2> S2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<I1, I2, O, Comp, Proj1, Proj2> constexpr ranges::set_symmetric_difference_result<I1, I2, O> ranges::set_symmetric_difference(I1 first1, S1 last1, I2 first2, S2 last2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}); template<input_­range R1, input_­range R2, weakly_­incrementable O, class Comp = ranges::less, class Proj1 = identity, class Proj2 = identity> requires mergeable<iterator_t<R1>, iterator_t<R2>, O, Comp, Proj1, Proj2> constexpr ranges::set_symmetric_difference_result<borrowed_iterator_t<R1>, borrowed_iterator_t<R2>, O> ranges::set_symmetric_difference(R1&& r1, R2&& r2, O result, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1
#
Let comp be less{}, and proj1 and proj2 be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: The ranges [first1, last1) and [first2, last2) are sorted with respect to comp and proj1 or proj2, respectively.
The resulting range does not overlap with either of the original ranges.
3
#
Effects: Copies the elements of the range [first1, last1) that are not present in the range [first2, last2), and the elements of the range [first2, last2) that are not present in the range [first1, last1) to the range beginning at result.
The elements in the constructed range are sorted.
4
#
Returns: Let result_­last be the end of the constructed range.
Returns
  • (4.1)
    result_­last for the overloads in namespace std.
  • (4.2)
    {last1, last2, result_­last} for the overloads in namespace ranges.
5
#
Complexity: At most 2 * ((last1 - first1) + (last2 - first2)) - 1 comparisons and applications of each projection.
6
#
Remarks: Stable ([algorithm.stable]).
If [first1, last1) contains m elements that are equivalent to each other and [first2, last2) contains n elements that are equivalent to them, then of those elements shall be copied to the output range: the last of these elements from [first1, last1) if , and the last of these elements from [first2, last2) if .
In either case, the elements are copied in order.

25.8.7 Heap operations [alg.heap.operations]

1
#
A random access range [a, b) is a heap with respect to comp and proj for a comparator and projection comp and proj if its elements are organized such that:
  • (1.1)
    With N = b - a, for all i, , bool(invoke(comp, invoke(proj, a[]), invoke(​proj, a[i]))) is false.
  • (1.2)
    *a may be removed by pop_­heap, or a new element added by push_­heap, in time.
2
#
These properties make heaps useful as priority queues.
3
#
make_­heap converts a range into a heap and sort_­heap turns a heap into a sorted sequence.

25.8.7.1 push_­heap [push.heap]

🔗
template<class RandomAccessIterator> constexpr void push_heap(RandomAccessIterator first, RandomAccessIterator last); template<class RandomAccessIterator, class Compare> constexpr void push_heap(RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<random_­access_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> constexpr I ranges::push_heap(I first, S last, Comp comp = {}, Proj proj = {}); template<random_­access_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> constexpr borrowed_iterator_t<R> ranges::push_heap(R&& r, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: The range [first, last - 1) is a valid heap with respect to comp and proj.
For the overloads in namespace std, the type of *first meets the Cpp17MoveConstructible requirements (Table 28) and the Cpp17MoveAssignable requirements (Table 30).
3
#
Effects: Places the value in the location last - 1 into the resulting heap [first, last).
4
#
Returns: last for the overloads in namespace ranges.
5
#
Complexity: At most comparisons and twice as many projections.

25.8.7.2 pop_­heap [pop.heap]

🔗
template<class RandomAccessIterator> constexpr void pop_heap(RandomAccessIterator first, RandomAccessIterator last); template<class RandomAccessIterator, class Compare> constexpr void pop_heap(RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<random_­access_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> constexpr I ranges::pop_heap(I first, S last, Comp comp = {}, Proj proj = {}); template<random_­access_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> constexpr borrowed_iterator_t<R> ranges::pop_heap(R&& r, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: The range [first, last) is a valid non-empty heap with respect to comp and proj.
For the overloads in namespace std, RandomAccessIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]) and the type of *first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
3
#
Effects: Swaps the value in the location first with the value in the location last - 1 and makes [first, last - 1) into a heap with respect to comp and proj.
4
#
Returns: last for the overloads in namespace ranges.
5
#
Complexity: At most comparisons and twice as many projections.

25.8.7.3 make_­heap [make.heap]

🔗
template<class RandomAccessIterator> constexpr void make_heap(RandomAccessIterator first, RandomAccessIterator last); template<class RandomAccessIterator, class Compare> constexpr void make_heap(RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<random_­access_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> constexpr I ranges::make_heap(I first, S last, Comp comp = {}, Proj proj = {}); template<random_­access_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> constexpr borrowed_iterator_t<R> ranges::make_heap(R&& r, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: For the overloads in namespace std, the type of *first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
3
#
Effects: Constructs a heap with respect to comp and proj out of the range [first, last).
4
#
Returns: last for the overloads in namespace ranges.
5
#
Complexity: At most comparisons and twice as many projections.

25.8.7.4 sort_­heap [sort.heap]

🔗
template<class RandomAccessIterator> constexpr void sort_heap(RandomAccessIterator first, RandomAccessIterator last); template<class RandomAccessIterator, class Compare> constexpr void sort_heap(RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<random_­access_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> constexpr I ranges::sort_heap(I first, S last, Comp comp = {}, Proj proj = {}); template<random_­access_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> constexpr borrowed_iterator_t<R> ranges::sort_heap(R&& r, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
2
#
Preconditions: The range [first, last) is a valid heap with respect to comp and proj.
For the overloads in namespace std, RandomAccessIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]) and the type of *first meets the Cpp17MoveConstructible (Table 28) and Cpp17MoveAssignable (Table 30) requirements.
3
#
Effects: Sorts elements in the heap [first, last) with respect to comp and proj.
4
#
Returns: last for the overloads in namespace ranges.
5
#
Complexity: At most comparisons, where , and twice as many projections.

25.8.7.5 is_­heap [is.heap]

🔗
template<class RandomAccessIterator> constexpr bool is_heap(RandomAccessIterator first, RandomAccessIterator last);
1
#
Effects: Equivalent to: return is_­heap_­until(first, last) == last;
🔗
template<class ExecutionPolicy, class RandomAccessIterator> bool is_heap(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator last);
2
#
Effects: Equivalent to: 
return is_heap_until(std::forward<ExecutionPolicy>(exec), first, last) == last;
🔗
template<class RandomAccessIterator, class Compare> constexpr bool is_heap(RandomAccessIterator first, RandomAccessIterator last, Compare comp);
3
#
Effects: Equivalent to: return is_­heap_­until(first, last, comp) == last;
🔗
template<class ExecutionPolicy, class RandomAccessIterator, class Compare> bool is_heap(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator last, Compare comp);
4
#
Effects: Equivalent to: 
return is_heap_until(std::forward<ExecutionPolicy>(exec), first, last, comp) == last;
🔗
template<random_­access_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­strict_­weak_­order<projected<I, Proj>> Comp = ranges::less> constexpr bool ranges::is_heap(I first, S last, Comp comp = {}, Proj proj = {}); template<random_­access_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr bool ranges::is_heap(R&& r, Comp comp = {}, Proj proj = {});
5
#
Effects: Equivalent to: return ranges​::​is_­heap_­until(first, last, comp, proj) == last;
🔗
template<class RandomAccessIterator> constexpr RandomAccessIterator is_heap_until(RandomAccessIterator first, RandomAccessIterator last); template<class ExecutionPolicy, class RandomAccessIterator> RandomAccessIterator is_heap_until(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator last); template<class RandomAccessIterator, class Compare> constexpr RandomAccessIterator is_heap_until(RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<class ExecutionPolicy, class RandomAccessIterator, class Compare> RandomAccessIterator is_heap_until(ExecutionPolicy&& exec, RandomAccessIterator first, RandomAccessIterator last, Compare comp); template<random_­access_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­strict_­weak_­order<projected<I, Proj>> Comp = ranges::less> constexpr I ranges::is_heap_until(I first, S last, Comp comp = {}, Proj proj = {}); template<random_­access_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_iterator_t<R> ranges::is_heap_until(R&& r, Comp comp = {}, Proj proj = {});
6
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
7
#
Returns: The last iterator i in [first, last] for which the range [first, i) is a heap with respect to comp and proj.
8
#
Complexity: Linear.

25.8.8 Minimum and maximum [alg.min.max]

🔗
template<class T> constexpr const T& min(const T& a, const T& b); template<class T, class Compare> constexpr const T& min(const T& a, const T& b, Compare comp); template<class T, class Proj = identity, indirect_­strict_­weak_­order<projected<const T*, Proj>> Comp = ranges::less> constexpr const T& ranges::min(const T& a, const T& b, Comp comp = {}, Proj proj = {});
1
#
Preconditions: For the first form, T meets the Cpp17LessThanComparable requirements (Table 26).
2
#
Returns: The smaller value.
3
#
Remarks: Returns the first argument when the arguments are equivalent.
An invocation may explicitly specify an argument for the template parameter T of the overloads in namespace std.
4
#
Complexity: Exactly one comparison and two applications of the projection, if any.
🔗
template<class T> constexpr T min(initializer_list<T> r); template<class T, class Compare> constexpr T min(initializer_list<T> r, Compare comp); template<copyable T, class Proj = identity, indirect_­strict_­weak_­order<projected<const T*, Proj>> Comp = ranges::less> constexpr T ranges::min(initializer_list<T> r, Comp comp = {}, Proj proj = {}); template<input_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> requires indirectly_­copyable_storable<iterator_t<R>, range_value_t<R>*> constexpr range_value_t<R> ranges::min(R&& r, Comp comp = {}, Proj proj = {});
5
#
Preconditions: ranges​::​distance(r) > 0.
For the overloads in namespace std, T meets the Cpp17CopyConstructible requirements.
For the first form, T meets the Cpp17LessThanComparable requirements (Table 26).
6
#
Returns: The smallest value in the input range.
7
#
Remarks: Returns a copy of the leftmost element when several elements are equivalent to the smallest.
An invocation may explicitly specify an argument for the template parameter T of the overloads in namespace std.
8
#
Complexity: Exactly ranges​::​distance(r) - 1 comparisons and twice as many applications of the projection, if any.
🔗
template<class T> constexpr const T& max(const T& a, const T& b); template<class T, class Compare> constexpr const T& max(const T& a, const T& b, Compare comp); template<class T, class Proj = identity, indirect_­strict_­weak_­order<projected<const T*, Proj>> Comp = ranges::less> constexpr const T& ranges::max(const T& a, const T& b, Comp comp = {}, Proj proj = {});
9
#
Preconditions: For the first form, T meets the Cpp17LessThanComparable requirements (Table 26).
10
#
Returns: The larger value.
11
#
Remarks: Returns the first argument when the arguments are equivalent.
An invocation may explicitly specify an argument for the template parameter T of the overloads in namespace std.
12
#
Complexity: Exactly one comparison and two applications of the projection, if any.
🔗
template<class T> constexpr T max(initializer_list<T> r); template<class T, class Compare> constexpr T max(initializer_list<T> r, Compare comp); template<copyable T, class Proj = identity, indirect_­strict_­weak_­order<projected<const T*, Proj>> Comp = ranges::less> constexpr T ranges::max(initializer_list<T> r, Comp comp = {}, Proj proj = {}); template<input_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> requires indirectly_­copyable_­storable<iterator_t<R>, range_value_t<R>*> constexpr range_value_t<R> ranges::max(R&& r, Comp comp = {}, Proj proj = {});
13
#
Preconditions: ranges​::​distance(r) > 0.
For the overloads in namespace std, T meets the Cpp17CopyConstructible requirements.
For the first form, T meets the Cpp17LessThanComparable requirements (Table 26).
14
#
Returns: The largest value in the input range.
15
#
Remarks: Returns a copy of the leftmost element when several elements are equivalent to the largest.
An invocation may explicitly specify an argument for the template parameter T of the overloads in namespace std.
16
#
Complexity: Exactly ranges​::​distance(r) - 1 comparisons and twice as many applications of the projection, if any.
🔗
template<class T> constexpr pair<const T&, const T&> minmax(const T& a, const T& b); template<class T, class Compare> constexpr pair<const T&, const T&> minmax(const T& a, const T& b, Compare comp); template<class T, class Proj = identity, indirect_­strict_­weak_­order<projected<const T*, Proj>> Comp = ranges::less> constexpr ranges::minmax_result<const T&> ranges::minmax(const T& a, const T& b, Comp comp = {}, Proj proj = {});
17
#
Preconditions: For the first form, T meets the Cpp17LessThanComparable requirements (Table 26).
18
#
Returns: {b, a} if b is smaller than a, and {a, b} otherwise.
19
#
Remarks: An invocation may explicitly specify an argument for the template parameter T of the overloads in namespace std.
20
#
Complexity: Exactly one comparison and two applications of the projection, if any.
🔗
template<class T> constexpr pair<T, T> minmax(initializer_list<T> t); template<class T, class Compare> constexpr pair<T, T> minmax(initializer_list<T> t, Compare comp); template<copyable T, class Proj = identity, indirect_­strict_­weak_­order<projected<const T*, Proj>> Comp = ranges::less> constexpr ranges::minmax_result<T> ranges::minmax(initializer_list<T> r, Comp comp = {}, Proj proj = {}); template<input_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> requires indirectly_­copyable_­storable<iterator_t<R>, range_value_t<R>*> constexpr ranges::minmax_result<range_value_t<R>> ranges::minmax(R&& r, Comp comp = {}, Proj proj = {});
21
#
Preconditions: ranges​::​distance(r) > 0.
For the overloads in namespace std, T meets the Cpp17CopyConstructible requirements.
For the first form, type T meets the Cpp17LessThanComparable requirements (Table 26).
22
#
Returns: Let X be the return type.
Returns X{x, y}, where x is a copy of the leftmost element with the smallest value and y a copy of the rightmost element with the largest value in the input range.
23
#
Remarks: An invocation may explicitly specify an argument for the template parameter T of the overloads in namespace std.
24
#
Complexity: At most applications of the corresponding predicate and twice as many applications of the projection, if any.
🔗
template<class ForwardIterator> constexpr ForwardIterator min_element(ForwardIterator first, ForwardIterator last); template<class ExecutionPolicy, class ForwardIterator> ForwardIterator min_element(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last); template<class ForwardIterator, class Compare> constexpr ForwardIterator min_element(ForwardIterator first, ForwardIterator last, Compare comp); template<class ExecutionPolicy, class ForwardIterator, class Compare> ForwardIterator min_element(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, Compare comp); template<forward_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­strict_­weak_­order<projected<I, Proj>> Comp = ranges::less> constexpr I ranges::min_element(I first, S last, Comp comp = {}, Proj proj = {}); template<forward_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_iterator_t<R> ranges::min_element(R&& r, Comp comp = {}, Proj proj = {});
25
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
26
#
Returns: The first iterator i in the range [first, last) such that for every iterator j in the range [first, last), 
bool(invoke(comp, invoke(proj, *j), invoke(proj, *i)))
is false.
Returns last if first == last.
27
#
Complexity: Exactly comparisons and twice as many projections.
🔗
template<class ForwardIterator> constexpr ForwardIterator max_element(ForwardIterator first, ForwardIterator last); template<class ExecutionPolicy, class ForwardIterator> ForwardIterator max_element(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last); template<class ForwardIterator, class Compare> constexpr ForwardIterator max_element(ForwardIterator first, ForwardIterator last, Compare comp); template<class ExecutionPolicy, class ForwardIterator, class Compare> ForwardIterator max_element(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, Compare comp); template<forward_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­strict_­weak_­order<projected<I, Proj>> Comp = ranges::less> constexpr I ranges::max_element(I first, S last, Comp comp = {}, Proj proj = {}); template<forward_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_iterator_t<R> ranges::max_element(R&& r, Comp comp = {}, Proj proj = {});
28
#
Let comp be less{} and proj be identity{} for the overloads with no parameters by those names.
29
#
Returns: The first iterator i in the range [first, last) such that for every iterator j in the range [first, last), 
bool(invoke(comp, invoke(proj, *i), invoke(proj, *j)))
is false.
Returns last if first == last.
30
#
Complexity: Exactly comparisons and twice as many projections.
🔗
template<class ForwardIterator> constexpr pair<ForwardIterator, ForwardIterator> minmax_element(ForwardIterator first, ForwardIterator last); template<class ExecutionPolicy, class ForwardIterator> pair<ForwardIterator, ForwardIterator> minmax_element(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last); template<class ForwardIterator, class Compare> constexpr pair<ForwardIterator, ForwardIterator> minmax_element(ForwardIterator first, ForwardIterator last, Compare comp); template<class ExecutionPolicy, class ForwardIterator, class Compare> pair<ForwardIterator, ForwardIterator> minmax_element(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, Compare comp); template<forward_­iterator I, sentinel_­for<I> S, class Proj = identity, indirect_­strict_­weak_­order<projected<I, Proj>> Comp = ranges::less> constexpr ranges::minmax_result<I> ranges::minmax_element(I first, S last, Comp comp = {}, Proj proj = {}); template<forward_­range R, class Proj = identity, indirect_­strict_­weak_­order<projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr ranges::minmax_result<borrowed_iterator_t<R>> ranges::minmax_element(R&& r, Comp comp = {}, Proj proj = {});
31
#
Returns: {first, first} if [first, last) is empty, otherwise {m, M}, where m is the first iterator in [first, last) such that no iterator in the range refers to a smaller element, and where M is the last iterator234 in [first, last) such that no iterator in the range refers to a larger element.
32
#
Complexity: Let N be last - first.
At most comparisons and twice as many applications of the projection, if any.
234)
This behavior intentionally differs from max_­element.
⮥

25.8.9 Bounded value [alg.clamp]

🔗
template<class T> constexpr const T& clamp(const T& v, const T& lo, const T& hi); template<class T, class Compare> constexpr const T& clamp(const T& v, const T& lo, const T& hi, Compare comp); template<class T, class Proj = identity, indirect_­strict_­weak_­order<projected<const T*, Proj>> Comp = ranges::less> constexpr const T& ranges::clamp(const T& v, const T& lo, const T& hi, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} for the overloads with no parameter comp, and let proj be identity{} for the overloads with no parameter proj.
2
#
Preconditions: bool(invoke(comp, invoke(proj, hi), invoke(proj, lo))) is false.
For the first form, type T meets the Cpp17LessThanComparable requirements (Table 26).
3
#
Returns: lo if bool(invoke(comp, invoke(proj, v), invoke(proj, lo))) is true, hi if bool(​invoke(comp, invoke(proj, hi), invoke(proj, v))) is true, otherwise v.
4
#
[Note
:
If NaN is avoided, T can be a floating-point type.
— end note
]
5
#
Complexity: At most two comparisons and three applications of the projection.

25.8.10 Lexicographical comparison [alg.lex.comparison]

🔗
template<class InputIterator1, class InputIterator2> constexpr bool lexicographical_compare(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2> bool lexicographical_compare(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2); template<class InputIterator1, class InputIterator2, class Compare> constexpr bool lexicographical_compare(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, Compare comp); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Compare> bool lexicographical_compare(ExecutionPolicy&& exec, ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, Compare comp); template<input_­iterator I1, sentinel_­for<I1> S1, input_­iterator I2, sentinel_­for<I2> S2, class Proj1 = identity, class Proj2 = identity, indirect_­strict_­weak_­order<projected<I1, Proj1>, projected<I2, Proj2>> Comp = ranges::less> constexpr bool ranges::lexicographical_compare(I1 first1, S1 last1, I2 first2, S2 last2, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}); template<input_­range R1, input_­range R2, class Proj1 = identity, class Proj2 = identity, indirect_­strict_­weak_­order<projected<iterator_t<R1>, Proj1>, projected<iterator_t<R2>, Proj2>> Comp = ranges::less> constexpr bool ranges::lexicographical_compare(R1&& r1, R2&& r2, Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {});
1
#
Returns: true if and only if the sequence of elements defined by the range [first1, last1) is lexicographically less than the sequence of elements defined by the range [first2, last2).
2
#
Complexity: At most applications of the corresponding comparison and each projection, if any.
3
#
Remarks: If two sequences have the same number of elements and their corresponding elements (if any) are equivalent, then neither sequence is lexicographically less than the other.
If one sequence is a proper prefix of the other, then the shorter sequence is lexicographically less than the longer sequence.
Otherwise, the lexicographical comparison of the sequences yields the same result as the comparison of the first corresponding pair of elements that are not equivalent.
4
#
[Example
:
ranges​::​lexicographical_­compare(I1, S1, I2, S2, Comp, Proj1, Proj2) could be implemented as: 
for ( ; first1 != last1 && first2 != last2 ; ++first1, (void) ++first2) {
  if (invoke(comp, invoke(proj1, *first1), invoke(proj2, *first2))) return true;
  if (invoke(comp, invoke(proj2, *first2), invoke(proj1, *first1))) return false;
}
return first1 == last1 && first2 != last2;
— end example
]
5
#
[Note
:
An empty sequence is lexicographically less than any non-empty sequence, but not less than any empty sequence.
— end note
]

25.8.11 Three-way comparison algorithms [alg.three.way]

🔗
template<class InputIterator1, class InputIterator2, class Cmp> constexpr auto lexicographical_compare_three_way(InputIterator1 b1, InputIterator1 e1, InputIterator2 b2, InputIterator2 e2, Cmp comp) -> decltype(comp(*b1, *b2));
1
#
Mandates: decltype(comp(*b1, *b2)) is a comparison category type.
2
#
Effects: Lexicographically compares two ranges and produces a result of the strongest applicable comparison category type.
Equivalent to: 
for ( ; b1 != e1 && b2 != e2; void(++b1), void(++b2) )
  if (auto cmp = comp(*b1,*b2); cmp != 0)
    return cmp;
return b1 != e1 ? strong_ordering::greater :
       b2 != e2 ? strong_ordering::less :
                  strong_ordering::equal;
🔗
template<class InputIterator1, class InputIterator2> constexpr auto lexicographical_compare_three_way(InputIterator1 b1, InputIterator1 e1, InputIterator2 b2, InputIterator2 e2);
3
#
Effects: Equivalent to: 
return lexicographical_compare_three_way(b1, e1, b2, e2, compare_three_way());

25.8.12 Permutation generators [alg.permutation.generators]

🔗
template<class BidirectionalIterator> constexpr bool next_permutation(BidirectionalIterator first, BidirectionalIterator last); template<class BidirectionalIterator, class Compare> constexpr bool next_permutation(BidirectionalIterator first, BidirectionalIterator last, Compare comp); template<bidirectional_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> constexpr ranges::next_permutation_result<I> ranges::next_permutation(I first, S last, Comp comp = {}, Proj proj = {}); template<bidirectional_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> constexpr ranges::next_permutation_result<borrowed_iterator_t<R>> ranges::next_permutation(R&& r, Comp comp = {}, Proj proj = {});
1
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
2
#
Preconditions: For the overloads in namespace std, BidirectionalIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]).
3
#
Effects: Takes a sequence defined by the range [first, last) and transforms it into the next permutation.
The next permutation is found by assuming that the set of all permutations is lexicographically sorted with respect to comp and proj.
If no such permutation exists, transforms the sequence into the first permutation; that is, the ascendingly-sorted one.
4
#
Returns: Let B be true if a next permutation was found and otherwise false.
Returns:
  • (4.1)
    B for the overloads in namespace std.
  • (4.2)
    { last, B } for the overloads in namespace ranges.
5
#
Complexity: At most (last - first) / 2 swaps.
🔗
template<class BidirectionalIterator> constexpr bool prev_permutation(BidirectionalIterator first, BidirectionalIterator last); template<class BidirectionalIterator, class Compare> constexpr bool prev_permutation(BidirectionalIterator first, BidirectionalIterator last, Compare comp); template<bidirectional_­iterator I, sentinel_­for<I> S, class Comp = ranges::less, class Proj = identity> requires sortable<I, Comp, Proj> constexpr ranges::prev_permutation_result<I> ranges::prev_permutation(I first, S last, Comp comp = {}, Proj proj = {}); template<bidirectional_­range R, class Comp = ranges::less, class Proj = identity> requires sortable<iterator_t<R>, Comp, Proj> constexpr ranges::prev_permutation_result<borrowed_iterator_t<R>> ranges::prev_permutation(R&& r, Comp comp = {}, Proj proj = {});
6
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
7
#
Preconditions: For the overloads in namespace std, BidirectionalIterator meets the Cpp17ValueSwappable requirements ([swappable.requirements]).
8
#
Effects: Takes a sequence defined by the range [first, last) and transforms it into the previous permutation.
The previous permutation is found by assuming that the set of all permutations is lexicographically sorted with respect to comp and proj.
If no such permutation exists, transforms the sequence into the last permutation; that is, the descendingly-sorted one.
9
#
Returns: Let B be true if a previous permutation was found and otherwise false.
Returns:
  • (9.1)
    B for the overloads in namespace std.
  • (9.2)
    { last, B } for the overloads in namespace ranges.
10
#
Complexity: At most (last - first) / 2 swaps.