std::three_way_comparable, std::three_way_comparable_with

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros (C++20) Dynamic memory management Program utilities Coroutine support (C++20) Variadic functions is_constant_evaluated (C++20) is_within_lifetime (C++26) initializer_list (C++11) source_location (C++20) Three-way comparison three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

General utilities Date and time Function objects Formatting library (C++20)   bitset hash (C++11) Relational operators (deprecated in C++20) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23) Elementary string conversions to_chars (C++17) from_chars (C++17) chars_format (C++17) to_chars_result (C++17) from_chars_result (C++17)

 

Defined in header <compare>
template<class T, class U>   concept __PartiallyOrderedWith =      // exposition only     requires(const std::remove_reference_t<T>& t,              const std::remove_reference_t<U>& u) {       { t <  u } -> std::boolean;       { t >  u } -> std::boolean;       { t <= u } -> std::boolean;       { t >= u } -> std::boolean;       { u <  t } -> std::boolean;       { u >  t } -> std::boolean;       { u <= t } -> std::boolean;       { u >= t } -> std::boolean;     };	(1)	(since C++20)
template<class T, class Cat>   concept __ComparesAs =                // exposition only     std::same_as<std::common_comparison_category_t<T, Cat>, Cat>;	(2)	(since C++20)
template<class T, class Cat = std::partial_ordering>   concept three_way_comparable =     __WeaklyEqualityComparableWith<T, T> &&     (!std::convertible_to<Cat, std::partial_ordering> ||     __PartiallyOrderedWith<T, T>) &&     requires(const std::remove_reference_t<T>& a,              const std::remove_reference_t<T>& b) {       { a <=> b } -> __ComparesAs<Cat>;     };	(3)	(since C++20)
template<class T, class U, class Cat = std::partial_ordering>   concept three_way_comparable_with =     __WeaklyEqualityComparableWith<T, U> &&     (!std::convertible_to<Cat, std::partial_ordering> ||     __PartiallyOrderedWith<T, U>) &&     std::three_way_comparable<T, Cat> &&     std::three_way_comparable<U, Cat> &&     std::common_reference_with<       const std::remove_reference_t<T>&,       const std::remove_reference_t<U>&> &&     three_way_comparable<       std::common_reference_t<         const std::remove_reference_t<T>&,         const std::remove_reference_t<U>&>, Cat> &&     requires(const std::remove_reference_t<T>& t,              const std::remove_reference_t<U>& u) {       { t <=> u } -> __ComparesAs<Cat>;       { u <=> t } -> __ComparesAs<Cat>;     };	(4)	(since C++20)

1) The exposition-only concept __PartiallyOrderedWith<T, U> specifies that an object of type T and an object of type U can be compared a partial order with each other (in either order) using <, >, <=, and >=, and the results of the comparisons are consistent.

More formally, T and U model __PartiallyOrderedWith<T, U> only if given

• t, an lvalue of type const std::remove_reference_t<T> and
• u, an lvalue of type const std::remove_reference_t<U>,

the following are true:

• t < u, t <= u, t > u, t >= u, u < t, u <= t, u > t, and u >= t have the same domain;
• bool(t < u) == bool(u > t);
• bool(u < t) == bool(t > u);
• bool(t <= u) == bool(u >= t); and
• bool(u <= t) == bool(t >= u).

3) The concept three_way_comparable<T, Cat> specifies that the three way comparison operator <=> on T yield results consistent with the comparison category implied by Cat.

T and Cat model three_way_comparable<T, Cat> only if, given lvalues a and b type const std::remove_reference_t<T>:

• (a <=> b == 0) == bool(a == b);
• (a <=> b != 0) == bool(a != b);
• ((a <=> b) <=> 0) and (0 <=> (b <=> a)) are equal;
• If bool(a < b) and bool(b < c) are both true, then bool(a < c) is true;
• bool(a > b) == bool(b < a);
• bool(a >= b) == !bool(a < b);
• bool(a <= b) == !bool(b < a);
• if Cat is convertible to std::strong_equality, T models equality_comparable;
• if Cat is convertible to std::partial_ordering:
  • (a <=> b < 0) == bool(a < b),
  • (a <=> b > 0) == bool(a > b),
  • (a <=> b <= 0) == bool(a <= b), and
  • (a <=> b >= 0) == bool(a >= b); and
• if Cat is convertible to std::strong_ordering, T models totally_ordered.

4) The concept three_way_comparable_with<T, U, Cat> specifies that the three way comparison operator <=> on T yield results consistent with the comparison category implied by Cat. Comparing mixed operands yields results equivalent to comparing the operands converted to their common type.

Formally, T, U, and Cat model three_way_comparable_with<T, U, Cat> only if given

• t, an lvalue of type const std::remove_reference_t<T> and
• u, an lvalue of type const std::remove_reference_t<U>,

Let C be std::common_reference_t<const std::remove_reference_t<T>&, const std::remove_reference_t<U>&>, the following are true:

• t <=> u and u <=> t have the same domain;
• ((t <=> u) <=> 0) and (0 <=> (u <=> t)) are equal;
• (t <=> u == 0) == bool(t == u);
• (t <=> u != 0) == bool(t != u);
• Cat(t <=> u) == Cat(C(t) <=> C(u));
• if Cat is convertible to std::strong_equality, T and U model std::equality_comparable_with<T, U>;
• if Cat is convertible to std::partial_ordering:
  • (t <=> u < 0) == bool(t < u),
  • (t <=> u > 0) == bool(t > u),
  • (t <=> u <= 0) == bool(t <= u),
  • (t <=> u >= 0) == bool(t >= u); and
• if Cat is convertible to std::strong_ordering, T and U model std::totally_ordered_with<T, U>.

where __WeaklyEqualityComparableWith is an exposition-only concept also used by equality_comparable.

Equality preservation

Expressions declared in requires expressions of the standard library concepts are required to be equality-preserving (except where stated otherwise).

Implicit expression variations

A requires expression that uses an expression that is non-modifying for some constant lvalue operand also requires implicit expression variations.

See also

equality_comparableequality_comparable_with (C++20)	specifies that operator == is an equivalence relation (concept)
totally_orderedtotally_ordered_with (C++20)	specifies that the comparison operators on the type yield a total order (concept)