17 Language support library [support]

17.11 Comparisons [cmp]

17.11.1 Header <compare> synopsis [compare.syn]

1
#
The header <compare> specifies types, objects, and functions for use primarily in connection with the three-way comparison operator.
namespace std { // [cmp.categories], comparison category types class partial_ordering; class weak_ordering; class strong_ordering; // named comparison functions constexpr bool is_eq (partial_ordering cmp) noexcept { return cmp == 0; } constexpr bool is_neq (partial_ordering cmp) noexcept { return cmp != 0; } constexpr bool is_lt (partial_ordering cmp) noexcept { return cmp < 0; } constexpr bool is_lteq(partial_ordering cmp) noexcept { return cmp <= 0; } constexpr bool is_gt (partial_ordering cmp) noexcept { return cmp > 0; } constexpr bool is_gteq(partial_ordering cmp) noexcept { return cmp >= 0; } // [cmp.common], common comparison category type template<class... Ts> struct common_comparison_category { using type = see below; }; template<class... Ts> using common_comparison_category_t = typename common_comparison_category<Ts...>::type; // [cmp.concept], concept three_­way_­comparable template<class T, class Cat = partial_ordering> concept three_way_comparable = see below; template<class T, class U, class Cat = partial_ordering> concept three_way_comparable_with = see below; // [cmp.result], result of three-way comparison template<class T, class U = T> struct compare_three_way_result; template<class T, class U = T> using compare_three_way_result_t = typename compare_three_way_result<T, U>::type; // [comparisons.three.way], class compare_­three_­way struct compare_three_way; // [cmp.alg], comparison algorithms inline namespace unspecified { inline constexpr unspecified strong_order = unspecified; inline constexpr unspecified weak_order = unspecified; inline constexpr unspecified partial_order = unspecified; inline constexpr unspecified compare_strong_order_fallback = unspecified; inline constexpr unspecified compare_weak_order_fallback = unspecified; inline constexpr unspecified compare_partial_order_fallback = unspecified; } }

17.11.2 Comparison category types [cmp.categories]

17.11.2.1 Preamble [cmp.categories.pre]

1
#
The types partial_­ordering, weak_­ordering, and strong_­ordering are collectively termed the comparison category types.
Each is specified in terms of an exposition-only data member named value whose value typically corresponds to that of an enumerator from one of the following exposition-only enumerations: enum class ord { equal = 0, equivalent = equal, less = -1, greater = 1 }; // exposition only enum class ncmp { unordered = -127 }; // exposition only
2
#
[Note 1:
The type strong_­ordering corresponds to the term total ordering in mathematics.
— end note]
3
#
The relational and equality operators for the comparison category types are specified with an anonymous parameter of unspecified type.
This type shall be selected by the implementation such that these parameters can accept literal 0 as a corresponding argument.
[Example 1:
nullptr_­t meets this requirement.
— end example]
In this context, the behavior of a program that supplies an argument other than a literal 0 is undefined.
4
#
For the purposes of subclause [cmp.categories], substitutability is the property that f(a) == f(b) is true whenever a == b is true, where f denotes a function that reads only comparison-salient state that is accessible via the argument's public const members.

17.11.2.2 Class partial_­ordering [cmp.partialord]

1
#
The partial_­ordering type is typically used as the result type of a three-way comparison operator that (a) admits all of the six two-way comparison operators ([expr.rel], [expr.eq]), (b) does not imply substitutability, and (c) permits two values to be incomparable.220
namespace std { class partial_ordering { int value; // exposition only bool is_ordered; // exposition only // exposition-only constructors constexpr explicit partial_ordering(ord v) noexcept : value(int(v)), is_ordered(true) {} // exposition only constexpr explicit partial_ordering(ncmp v) noexcept : value(int(v)), is_ordered(false) {} // exposition only public: // valid values static const partial_ordering less; static const partial_ordering equivalent; static const partial_ordering greater; static const partial_ordering unordered; // comparisons friend constexpr bool operator==(partial_ordering v, unspecified) noexcept; friend constexpr bool operator==(partial_ordering v, partial_ordering w) noexcept = default; friend constexpr bool operator< (partial_ordering v, unspecified) noexcept; friend constexpr bool operator> (partial_ordering v, unspecified) noexcept; friend constexpr bool operator<=(partial_ordering v, unspecified) noexcept; friend constexpr bool operator>=(partial_ordering v, unspecified) noexcept; friend constexpr bool operator< (unspecified, partial_ordering v) noexcept; friend constexpr bool operator> (unspecified, partial_ordering v) noexcept; friend constexpr bool operator<=(unspecified, partial_ordering v) noexcept; friend constexpr bool operator>=(unspecified, partial_ordering v) noexcept; friend constexpr partial_ordering operator<=>(partial_ordering v, unspecified) noexcept; friend constexpr partial_ordering operator<=>(unspecified, partial_ordering v) noexcept; }; // valid values' definitions inline constexpr partial_ordering partial_ordering::less(ord::less); inline constexpr partial_ordering partial_ordering::equivalent(ord::equivalent); inline constexpr partial_ordering partial_ordering::greater(ord::greater); inline constexpr partial_ordering partial_ordering::unordered(ncmp::unordered); }
🔗
constexpr bool operator==(partial_ordering v, unspecified) noexcept; constexpr bool operator< (partial_ordering v, unspecified) noexcept; constexpr bool operator> (partial_ordering v, unspecified) noexcept; constexpr bool operator<=(partial_ordering v, unspecified) noexcept; constexpr bool operator>=(partial_ordering v, unspecified) noexcept;
2
#
Returns: For operator@, v.is_­ordered && v.value @ 0.
🔗
constexpr bool operator< (unspecified, partial_ordering v) noexcept; constexpr bool operator> (unspecified, partial_ordering v) noexcept; constexpr bool operator<=(unspecified, partial_ordering v) noexcept; constexpr bool operator>=(unspecified, partial_ordering v) noexcept;
3
#
Returns: For operator@, v.is_­ordered && 0 @ v.value.
🔗
constexpr partial_ordering operator<=>(partial_ordering v, unspecified) noexcept;
4
#
Returns: v.
🔗
constexpr partial_ordering operator<=>(unspecified, partial_ordering v) noexcept;
5
#
Returns: v < 0 ? partial_­ordering​::​greater : v > 0 ? partial_­ordering​::​less : v.
220)
That is, a < b, a == b, and a > b might all be false.
 ⮥

17.11.2.3 Class weak_­ordering [cmp.weakord]

1
#
The weak_­ordering type is typically used as the result type of a three-way comparison operator that (a) admits all of the six two-way comparison operators ([expr.rel], [expr.eq]), and (b) does not imply substitutability.
namespace std { class weak_ordering { int value; // exposition only // exposition-only constructors constexpr explicit weak_ordering(ord v) noexcept : value(int(v)) {} // exposition only public: // valid values static const weak_ordering less; static const weak_ordering equivalent; static const weak_ordering greater; // conversions constexpr operator partial_ordering() const noexcept; // comparisons friend constexpr bool operator==(weak_ordering v, unspecified) noexcept; friend constexpr bool operator==(weak_ordering v, weak_ordering w) noexcept = default; friend constexpr bool operator< (weak_ordering v, unspecified) noexcept; friend constexpr bool operator> (weak_ordering v, unspecified) noexcept; friend constexpr bool operator<=(weak_ordering v, unspecified) noexcept; friend constexpr bool operator>=(weak_ordering v, unspecified) noexcept; friend constexpr bool operator< (unspecified, weak_ordering v) noexcept; friend constexpr bool operator> (unspecified, weak_ordering v) noexcept; friend constexpr bool operator<=(unspecified, weak_ordering v) noexcept; friend constexpr bool operator>=(unspecified, weak_ordering v) noexcept; friend constexpr weak_ordering operator<=>(weak_ordering v, unspecified) noexcept; friend constexpr weak_ordering operator<=>(unspecified, weak_ordering v) noexcept; }; // valid values' definitions inline constexpr weak_ordering weak_ordering::less(ord::less); inline constexpr weak_ordering weak_ordering::equivalent(ord::equivalent); inline constexpr weak_ordering weak_ordering::greater(ord::greater); }
🔗
constexpr operator partial_ordering() const noexcept;
2
#
Returns: value == 0 ? partial_ordering::equivalent : value < 0 ? partial_ordering::less : partial_ordering::greater
🔗
constexpr bool operator==(weak_ordering v, unspecified) noexcept; constexpr bool operator< (weak_ordering v, unspecified) noexcept; constexpr bool operator> (weak_ordering v, unspecified) noexcept; constexpr bool operator<=(weak_ordering v, unspecified) noexcept; constexpr bool operator>=(weak_ordering v, unspecified) noexcept;
3
#
Returns: v.value @ 0 for operator@.
🔗
constexpr bool operator< (unspecified, weak_ordering v) noexcept; constexpr bool operator> (unspecified, weak_ordering v) noexcept; constexpr bool operator<=(unspecified, weak_ordering v) noexcept; constexpr bool operator>=(unspecified, weak_ordering v) noexcept;
4
#
Returns: 0 @ v.value for operator@.
🔗
constexpr weak_ordering operator<=>(weak_ordering v, unspecified) noexcept;
5
#
Returns: v.
🔗
constexpr weak_ordering operator<=>(unspecified, weak_ordering v) noexcept;
6
#
Returns: v < 0 ? weak_­ordering​::​greater : v > 0 ? weak_­ordering​::​less : v.

17.11.2.4 Class strong_­ordering [cmp.strongord]

1
#
The strong_­ordering type is typically used as the result type of a three-way comparison operator that (a) admits all of the six two-way comparison operators ([expr.rel], [expr.eq]), and (b) does imply substitutability.
namespace std { class strong_ordering { int value; // exposition only // exposition-only constructors constexpr explicit strong_ordering(ord v) noexcept : value(int(v)) {} // exposition only public: // valid values static const strong_ordering less; static const strong_ordering equal; static const strong_ordering equivalent; static const strong_ordering greater; // conversions constexpr operator partial_ordering() const noexcept; constexpr operator weak_ordering() const noexcept; // comparisons friend constexpr bool operator==(strong_ordering v, unspecified) noexcept; friend constexpr bool operator==(strong_ordering v, strong_ordering w) noexcept = default; friend constexpr bool operator< (strong_ordering v, unspecified) noexcept; friend constexpr bool operator> (strong_ordering v, unspecified) noexcept; friend constexpr bool operator<=(strong_ordering v, unspecified) noexcept; friend constexpr bool operator>=(strong_ordering v, unspecified) noexcept; friend constexpr bool operator< (unspecified, strong_ordering v) noexcept; friend constexpr bool operator> (unspecified, strong_ordering v) noexcept; friend constexpr bool operator<=(unspecified, strong_ordering v) noexcept; friend constexpr bool operator>=(unspecified, strong_ordering v) noexcept; friend constexpr strong_ordering operator<=>(strong_ordering v, unspecified) noexcept; friend constexpr strong_ordering operator<=>(unspecified, strong_ordering v) noexcept; }; // valid values' definitions inline constexpr strong_ordering strong_ordering::less(ord::less); inline constexpr strong_ordering strong_ordering::equal(ord::equal); inline constexpr strong_ordering strong_ordering::equivalent(ord::equivalent); inline constexpr strong_ordering strong_ordering::greater(ord::greater); }
🔗
constexpr operator partial_ordering() const noexcept;
2
#
Returns: value == 0 ? partial_ordering::equivalent : value < 0 ? partial_ordering::less : partial_ordering::greater
🔗
constexpr operator weak_ordering() const noexcept;
3
#
Returns: value == 0 ? weak_ordering::equivalent : value < 0 ? weak_ordering::less : weak_ordering::greater
🔗
constexpr bool operator==(strong_ordering v, unspecified) noexcept; constexpr bool operator< (strong_ordering v, unspecified) noexcept; constexpr bool operator> (strong_ordering v, unspecified) noexcept; constexpr bool operator<=(strong_ordering v, unspecified) noexcept; constexpr bool operator>=(strong_ordering v, unspecified) noexcept;
4
#
Returns: v.value @ 0 for operator@.
🔗
constexpr bool operator< (unspecified, strong_ordering v) noexcept; constexpr bool operator> (unspecified, strong_ordering v) noexcept; constexpr bool operator<=(unspecified, strong_ordering v) noexcept; constexpr bool operator>=(unspecified, strong_ordering v) noexcept;
5
#
Returns: 0 @ v.value for operator@.
🔗
constexpr strong_ordering operator<=>(strong_ordering v, unspecified) noexcept;
6
#
Returns: v.
🔗
constexpr strong_ordering operator<=>(unspecified, strong_ordering v) noexcept;
7
#
Returns: v < 0 ? strong_­ordering​::​greater : v > 0 ? strong_­ordering​::​less : v.

17.11.3 Class template common_­comparison_­category [cmp.common]

1
#
The type common_­comparison_­category provides an alias for the strongest comparison category to which all of the template arguments can be converted.
[Note 1:
A comparison category type is stronger than another if they are distinct types and an instance of the former can be converted to an instance of the latter.
— end note]
🔗
template<class... Ts> struct common_comparison_category { using type = see below; };
2
#
Remarks: The member typedef-name type denotes the common comparison type ([class.spaceship]) of Ts..., the expanded parameter pack, or void if any element of Ts is not a comparison category type.
[Note 2:
This is std​::​strong_­ordering if the expansion is empty.
— end note]

17.11.4 Concept three_­way_­comparable [cmp.concept]

template<class T, class Cat> concept compares-as = // exposition only same_­as<common_comparison_category_t<T, Cat>, Cat>; template<class T, class U> concept partially-ordered-with = // exposition only requires(const remove_reference_t<T>& t, const remove_reference_t<U>& u) { { t < u } -> boolean-testable; { t > u } -> boolean-testable; { t <= u } -> boolean-testable; { t >= u } -> boolean-testable; { u < t } -> boolean-testable; { u > t } -> boolean-testable; { u <= t } -> boolean-testable; { u >= t } -> boolean-testable; };
1
#
Let t and u be lvalues of types const remove_­reference_­t<T> and const remove_­reference_­t<U>, respectively.
T and U model partially-ordered-with<T, U> only if:
  • (1.1)
    t < u, t <= u, t > u, t >= u, u < t, u <= t, u > t, and u >= t have the same domain.
  • (1.2)
    bool(t < u) == bool(u > t) is true,
  • (1.3)
    bool(u < t) == bool(t > u) is true,
  • (1.4)
    bool(t <= u) == bool(u >= t) is true, and
  • (1.5)
    bool(u <= t) == bool(t >= u) is true.
template<class T, class Cat = partial_ordering> concept three_­way_­comparable = weakly-equality-comparable-with<T, T> && partially-ordered-with<T, T> && requires(const remove_reference_t<T>& a, const remove_reference_t<T>& b) { { a <=> b } -> compares-as<Cat>; };
2
#
Let a and b be lvalues of type const remove_­reference_­t<T>.
T and Cat model three_­way_­comparable<T, Cat> only if:
  • (2.1)
    (a <=> b == 0) == bool(a == b) is true,
  • (2.2)
    (a <=> b != 0) == bool(a != b) is true,
  • (2.3)
    ((a <=> b) <=> 0) and (0 <=> (b <=> a)) are equal,
  • (2.4)
    (a <=> b < 0) == bool(a < b) is true,
  • (2.5)
    (a <=> b > 0) == bool(a > b) is true,
  • (2.6)
    (a <=> b <= 0) == bool(a <= b) is true,
  • (2.7)
    (a <=> b >= 0) == bool(a >= b) is true, and
  • (2.8)
    if Cat is convertible to strong_­ordering, T models totally_­ordered ([concept.totallyordered]).
template<class T, class U, class Cat = partial_ordering> concept three_­way_­comparable_­with = three_­way_­comparable<T, Cat> && three_­way_­comparable<U, Cat> && common_­reference_­with<const remove_reference_t<T>&, const remove_reference_t<U>&> && three_­way_­comparable< common_reference_t<const remove_reference_t<T>&, const remove_reference_t<U>&>, Cat> && weakly-equality-comparable-with<T, U> && partially-ordered-with<T, U> && requires(const remove_reference_t<T>& t, const remove_reference_t<U>& u) { { t <=> u } -> compares-as<Cat>; { u <=> t } -> compares-as<Cat>; };
3
#
Let t and u be lvalues of types const remove_­reference_­t<T> and const remove_­reference_­t<U>, respectively.
Let C be common_­reference_­t<const remove_­reference_­t<T>&, const remove_­reference_­t<U>&>.
T, U, and Cat model three_­way_­comparable_­with<T, U, Cat> only if:
  • (3.1)
    t <=> u and u <=> t have the same domain,
  • (3.2)
    ((t <=> u) <=> 0) and (0 <=> (u <=> t)) are equal,
  • (3.3)
    (t <=> u == 0) == bool(t == u) is true,
  • (3.4)
    (t <=> u != 0) == bool(t != u) is true,
  • (3.5)
    Cat(t <=> u) == Cat(C(t) <=> C(u)) is true,
  • (3.6)
    (t <=> u < 0) == bool(t < u) is true,
  • (3.7)
    (t <=> u > 0) == bool(t > u) is true,
  • (3.8)
    (t <=> u <= 0) == bool(t <= u) is true,
  • (3.9)
    (t <=> u >= 0) == bool(t >= u) is true, and
  • (3.10)
    if Cat is convertible to strong_­ordering, T and U model totally_­ordered_­with<T, U> ([concept.totallyordered]).

17.11.5 Result of three-way comparison [cmp.result]

1
#
The behavior of a program that adds specializations for the compare_­three_­way_­result template defined in this subclause is undefined.
2
#
For the compare_­three_­way_­result type trait applied to the types T and U, let t and u denote lvalues of types const remove_­reference_­t<T> and const remove_­reference_­t<U>, respectively.
If the expression t <=> u is well-formed when treated as an unevaluated operand ([expr.context]), the member typedef-name type denotes the type decltype(t <=> u).
Otherwise, there is no member type.

17.11.6 Comparison algorithms [cmp.alg]

1
#
The name strong_­order denotes a customization point object ([customization.point.object]).
Given subexpressions E and F, the expression strong_­order(E, F) is expression-equivalent ([defns.expression-equivalent]) to the following:
  • (1.1)
    If the decayed types of E and F differ, strong_­order(E, F) is ill-formed.
  • (1.2)
    Otherwise, strong_­ordering(strong_­order(E, F)) if it is a well-formed expression with overload resolution performed in a context that does not include a declaration of std​::​strong_­order.
  • (1.3)
    Otherwise, if the decayed type T of E is a floating-point type, yields a value of type strong_­ordering that is consistent with the ordering observed by T's comparison operators, and if numeric_­limits<T>​::​is_­iec559 is true, is additionally consistent with the totalOrder operation as specified in ISO/IEC/IEEE 60559.
  • (1.4)
    Otherwise, strong_­ordering(compare_­three_­way()(E, F)) if it is a well-formed expression.
  • (1.5)
    Otherwise, strong_­order(E, F) is ill-formed.
    [Note 1:
    This case can result in substitution failure when strong_­order(E, F) appears in the immediate context of a template instantiation.
    — end note]
2
#
The name weak_­order denotes a customization point object ([customization.point.object]).
Given subexpressions E and F, the expression weak_­order(E, F) is expression-equivalent ([defns.expression-equivalent]) to the following:
  • (2.1)
    If the decayed types of E and F differ, weak_­order(E, F) is ill-formed.
  • (2.2)
    Otherwise, weak_­ordering(weak_­order(E, F)) if it is a well-formed expression with overload resolution performed in a context that does not include a declaration of std​::​weak_­order.
  • (2.3)
    Otherwise, if the decayed type T of E is a floating-point type, yields a value of type weak_­ordering that is consistent with the ordering observed by T's comparison operators and strong_­order, and if numeric_­limits<T>​::​is_­iec559 is true, is additionally consistent with the following equivalence classes, ordered from lesser to greater:
  • (2.4)
    Otherwise, weak_­ordering(compare_­three_­way()(E, F)) if it is a well-formed expression.
  • (2.5)
    Otherwise, weak_­ordering(strong_­order(E, F)) if it is a well-formed expression.
  • (2.6)
    Otherwise, weak_­order(E, F) is ill-formed.
    [Note 2:
    This case can result in substitution failure when std​::​weak_­order(E, F) appears in the immediate context of a template instantiation.
    — end note]
3
#
The name partial_­order denotes a customization point object ([customization.point.object]).
Given subexpressions E and F, the expression partial_­order(E, F) is expression-equivalent ([defns.expression-equivalent]) to the following:
  • (3.1)
    If the decayed types of E and F differ, partial_­order(E, F) is ill-formed.
  • (3.2)
    Otherwise, partial_­ordering(partial_­order(E, F)) if it is a well-formed expression with overload resolution performed in a context that does not include a declaration of std​::​partial_­order.
  • (3.3)
    Otherwise, partial_­ordering(compare_­three_­way()(E, F)) if it is a well-formed expression.
  • (3.4)
    Otherwise, partial_­ordering(weak_­order(E, F)) if it is a well-formed expression.
  • (3.5)
    Otherwise, partial_­order(E, F) is ill-formed.
    [Note 3:
    This case can result in substitution failure when std​::​partial_­order(E, F) appears in the immediate context of a template instantiation.
    — end note]
4
#
The name compare_­strong_­order_­fallback denotes a customization point object ([customization.point.object]).
Given subexpressions E and F, the expression compare_­strong_­order_­fallback(E, F) is expression-equivalent ([defns.expression-equivalent]) to:
  • (4.1)
    If the decayed types of E and F differ, compare_­strong_­order_­fallback(E, F) is ill-formed.
  • (4.2)
    Otherwise, strong_­order(E, F) if it is a well-formed expression.
  • (4.3)
    Otherwise, if the expressions E == F and E < F are both well-formed and convertible to bool, E == F ? strong_ordering::equal : E < F ? strong_ordering::less : strong_ordering::greater except that E and F are evaluated only once.
  • (4.4)
    Otherwise, compare_­strong_­order_­fallback(E, F) is ill-formed.
5
#
The name compare_­weak_­order_­fallback denotes a customization point object ([customization.point.object]).
Given subexpressions E and F, the expression compare_­weak_­order_­fallback(E, F) is expression-equivalent ([defns.expression-equivalent]) to:
  • (5.1)
    If the decayed types of E and F differ, compare_­weak_­order_­fallback(E, F) is ill-formed.
  • (5.2)
    Otherwise, weak_­order(E, F) if it is a well-formed expression.
  • (5.3)
    Otherwise, if the expressions E == F and E < F are both well-formed and convertible to bool, E == F ? weak_ordering::equivalent : E < F ? weak_ordering::less : weak_ordering::greater except that E and F are evaluated only once.
  • (5.4)
    Otherwise, compare_­weak_­order_­fallback(E, F) is ill-formed.
6
#
The name compare_­partial_­order_­fallback denotes a customization point object ([customization.point.object]).
Given subexpressions E and F, the expression compare_­partial_­order_­fallback(E, F) is expression-equivalent ([defns.expression-equivalent]) to:
  • (6.1)
    If the decayed types of E and F differ, compare_­partial_­order_­fallback(E, F) is ill-formed.
  • (6.2)
    Otherwise, partial_­order(E, F) if it is a well-formed expression.
  • (6.3)
    Otherwise, if the expressions E == F and E < F are both well-formed and convertible to bool, E == F ? partial_ordering::equivalent : E < F ? partial_ordering::less : F < E ? partial_ordering::greater : partial_ordering::unordered except that E and F are evaluated only once.
  • (6.4)
    Otherwise, compare_­partial_­order_­fallback(E, F) is ill-formed.