17 Language support library [support] (original) (raw)

17.12 Comparisons [cmp]

17.12.1 Header synopsis [compare.syn]

17.12.2 Comparison category types [cmp.categories]

17.12.2.1 Preamble [cmp.categories.pre]

17.12.2.2 Class partial_ordering [cmp.partialord]

17.12.2.3 Class weak_ordering [cmp.weakord]

17.12.2.4 Class strong_ordering [cmp.strongord]

17.12.3 Class template common_comparison_category [cmp.common]

17.12.4 Concept three_way_comparable [cmp.concept]

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

17.12.6 Comparison algorithms [cmp.alg]

17.12.7 Type Ordering [compare.type]

17.12.1 Header synopsis [compare.syn]

namespace std { class partial_ordering;class weak_ordering;class strong_ordering;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; } template<class... Ts> struct common_comparison_category { using type = see below;};template<class... Ts> using common_comparison_category_t = common_comparison_category<Ts...>::type;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;template<class T, class U = T> struct compare_three_way_result;template<class T, class U = T> using compare_three_way_result_t = compare_three_way_result<T, U>::type;struct compare_three_way;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;} template<class T, class U> struct type_order;template<class T, class U> constexpr strong_ordering type_order_v = type_order<T, U>::value;}

17.12.2 Comparison category types [cmp.categories]

17.12.2.1 Preamble [cmp.categories.pre]

The typespartial_ordering,weak_ordering, andstrong_orderingare collectively termed the comparison category types.

Each is specified in terms of an exposition-only data member named valuewhose 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 }; enum class ncmp { unordered = -127 };

[Note 1:

The type strong_orderingcorresponds to the term total ordering in mathematics.

— _end note_]

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_tmeets this requirement.

— _end example_]

In this context, the behavior of a program that supplies an argument other than a literal 0 is undefined.

For the purposes of [cmp.categories],substitutability is the property that f(a) == f(b) is truewhenever 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.12.2.2 Class partial_ordering [cmp.partialord]

The partial_ordering type is typically used as the result type of a three-way comparison operator ([expr.spaceship]) for a type that admits all of the six two-way comparison operators ([expr.rel], [expr.eq]), for which equality need not imply substitutability, and that permits two values to be incomparable.190

namespace std { class partial_ordering { int value; bool is-ordered; constexpr explicit partial_ordering(ord v) noexcept : value(int(v)), is-ordered(true) {} constexpr explicit partial_ordering(ncmp v) noexcept : value(int(v)), is-ordered(false) {} public: static const partial_ordering less;static const partial_ordering equivalent;static const partial_ordering greater;static const partial_ordering unordered;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;};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;

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;

Returns: For operator@, v.is-ordered && 0 @ v.value.

constexpr partial_ordering operator<=>(partial_ordering v, _unspecified_) noexcept;

constexpr partial_ordering operator<=>(_unspecified_, partial_ordering v) noexcept;

Returns: v < 0 ? partial_ordering​::​greater : v > 0 ? partial_ordering​::​less : v.

17.12.2.3 Class weak_ordering [cmp.weakord]

The weak_ordering type is typically used as the result type of a three-way comparison operator ([expr.spaceship]) for a type that admits all of the six two-way comparison operators ([expr.rel], [expr.eq]) and for which equality need not imply substitutability.

namespace std { class weak_ordering { int value; constexpr explicit weak_ordering(ord v) noexcept : value(int(v)) {} public: static const weak_ordering less;static const weak_ordering equivalent;static const weak_ordering greater;constexpr operator partial_ordering() const noexcept;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;};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;

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;

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;

Returns: 0 @ v.value for operator@.

constexpr weak_ordering operator<=>(weak_ordering v, _unspecified_) noexcept;

constexpr weak_ordering operator<=>(_unspecified_, weak_ordering v) noexcept;

Returns: v < 0 ? weak_ordering​::​greater : v > 0 ? weak_ordering​::​less : v.

17.12.2.4 Class strong_ordering [cmp.strongord]

The strong_ordering type is typically used as the result type of a three-way comparison operator ([expr.spaceship]) for a type that admits all of the six two-way comparison operators ([expr.rel], [expr.eq]) and for which equality does imply substitutability.

namespace std { class strong_ordering { int value; constexpr explicit strong_ordering(ord v) noexcept : value(int(v)) {} public: static const strong_ordering less;static const strong_ordering equal;static const strong_ordering equivalent;static const strong_ordering greater;constexpr operator partial_ordering() const noexcept;constexpr operator weak_ordering() const noexcept;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;};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;

Returns: value == 0 ? partial_ordering::equivalent : value < 0 ? partial_ordering::less : partial_ordering::greater

constexpr operator weak_ordering() const noexcept;

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;

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;

Returns: 0 @ v.value for operator@.

constexpr strong_ordering operator<=>(strong_ordering v, _unspecified_) noexcept;

constexpr strong_ordering operator<=>(_unspecified_, strong_ordering v) noexcept;

Returns: v < 0 ? strong_ordering​::​greater : v > 0 ? strong_ordering​::​less : v.

17.12.3 Class template common_comparison_category [cmp.common]

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_;};

Remarks: The member typedef-name type denotes the common comparison type ([class.spaceship]) of Ts..., the expanded parameter pack, orvoid if any element of Tsis not a comparison category type.

[Note 2:

This is std​::​strong_ordering if the expansion is empty.

— _end note_]

17.12.4 Concept three_way_comparable [cmp.concept]

Let t and u be lvalues of types const remove_reference_t<T> andconst remove_reference_t<U>, respectively.

T and U modelpartially-ordered-with<T, U> only if

• t < u,t <= u,t > u,t >= u,u < t,u <= t,u > t, andu >= t have the same domain,
• bool(t < u) == bool(u > t) is true,
• bool(u < t) == bool(t > u) is true,
• bool(t <= u) == bool(u >= t) is true, and
• 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>;};

Let a and b be lvalues of type const remove_reference_t<T>.

T and Catmodel three_way_comparable<T, Cat> only if

• (a <=> b == 0) == bool(a == b) is true,
• (a <=> b != 0) == bool(a != b) is true,
• ((a <=> b) <=> 0) and (0 <=> (b <=> a)) are equal,
• (a <=> b < 0) == bool(a < b) is true,
• (a <=> b > 0) == bool(a > b) is true,
• (a <=> b <= 0) == bool(a <= b) is true,
• (a <=> b >= 0) == bool(a >= b) is true, and
• if Cat is convertible to strong_ordering, T modelstotally_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> && comparison-common-type-with<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>;};

Let t and t2 be lvalues denoting distinct equal objects of types const remove_reference_t<T> andremove_cvref_t<T>, respectively, and let u and u2 be lvalues denoting distinct equal objects of types const remove_reference_t<U> andremove_cvref_t<U>, respectively.

Let C becommon_reference_t<const remove_reference_t<T>&, const remove_reference_t<U>&>.

T, U, and Catmodel three_way_comparable_with<T, U, Cat> only if

• t <=> u and u <=> t have the same domain,
• ((t <=> u) <=> 0) and (0 <=> (u <=> t)) are equal,
• (t <=> u == 0) == bool(t == u) is true,
• (t <=> u != 0) == bool(t != u) is true,
• Cat(t <=> u) == Cat(CONVERT_TO_LVALUE<C>(t2) <=> CONVERT_TO_LVALUE<C>(u2)) is true,
• (t <=> u < 0) == bool(t < u) is true,
• (t <=> u > 0) == bool(t > u) is true,
• (t <=> u <= 0) == bool(t <= u) is true,
• (t <=> u >= 0) == bool(t >= u) is true, and
• if Cat is convertible to strong_ordering,T and U modeltotally_ordered_with<T, U> ([concept.totallyordered]).

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

The behavior of a program that adds specializations for the compare_three_way_result template defined in this subclause is undefined.

For the compare_three_way_result type trait applied to the types T and U, let t and u denote lvalues of typesconst 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 typedenotes the type decltype(t <=> u).

Otherwise, there is no member type.

17.12.6 Comparison algorithms [cmp.alg]

Given subexpressions E and F, the expression strong_order(E, F)is expression-equivalent ([defns.expression.equivalent]) to the following:

• If the decayed types of E and F differ,strong_order(E, F) is ill-formed.
• Otherwise, strong_ordering(strong_order(E, F)) if it is a well-formed expression where the meaning of strong_order is established as-if by performing argument-dependent lookup only ([basic.lookup.argdep]).
• 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 60559.
• Otherwise, strong_ordering(compare_three_way()(E, F)) if it is a well-formed expression.
• Otherwise, strong_order(E, F) is ill-formed.

[Note 1:

Ill-formed cases above result in substitution failure when strong_order(E, F) appears in the immediate context of a template instantiation.

— _end note_]

Given subexpressions E and F, the expression weak_order(E, F)is expression-equivalent ([defns.expression.equivalent]) to the following:

• If the decayed types of E and F differ,weak_order(E, F) is ill-formed.
• Otherwise, weak_ordering(weak_order(E, F)) if it is a well-formed expression where the meaning of weak_order is established as-if by performing argument-dependent lookup only ([basic.lookup.argdep]).
• 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:
  • together, all negative NaN values;
  • negative infinity;
  • each normal negative value;
  • each subnormal negative value;
  • together, both zero values;
  • each subnormal positive value;
  • each normal positive value;
  • positive infinity;
  • together, all positive NaN values.
• Otherwise, weak_ordering(compare_three_way()(E, F)) if it is a well-formed expression.
• Otherwise, weak_ordering(strong_order(E, F)) if it is a well-formed expression.
• Otherwise, weak_order(E, F) is ill-formed.

[Note 2:

Ill-formed cases above result in substitution failure when weak_order(E, F) appears in the immediate context of a template instantiation.

— _end note_]

Given subexpressions E and F, the expression partial_order(E, F)is expression-equivalent ([defns.expression.equivalent]) to the following:

• If the decayed types of E and F differ,partial_order(E, F) is ill-formed.
• Otherwise, partial_ordering(partial_order(E, F)) if it is a well-formed expression where the meaning of partial_order is established as-if by performing argument-dependent lookup only ([basic.lookup.argdep]).
• Otherwise, partial_ordering(compare_three_way()(E, F)) if it is a well-formed expression.
• Otherwise, partial_ordering(weak_order(E, F)) if it is a well-formed expression.
• Otherwise, partial_order(E, F) is ill-formed.

[Note 3:

Ill-formed cases above result in substitution failure when partial_order(E, F) appears in the immediate context of a template instantiation.

— _end note_]

Given subexpressions E and F, the expression compare_strong_order_fallback(E, F)is expression-equivalent ([defns.expression.equivalent]) to:

• If the decayed types of E and F differ,compare_strong_order_fallback(E, F) is ill-formed.
• Otherwise, strong_order(E, F) if it is a well-formed expression.
• Otherwise, if the expressions E == F and E < F are both well-formed and each of decltype(E == F) and decltype(E < F) modelsboolean-testable,E == F ? strong_ordering::equal :E < F ? strong_ordering::less : strong_ordering::greaterexcept that E and F are evaluated only once.
• Otherwise, compare_strong_order_fallback(E, F) is ill-formed.

[Note 4:

Ill-formed cases above result in substitution failure when compare_strong_order_fallback(E, F) appears in the immediate context of a template instantiation.

— _end note_]

Given subexpressions E and F, the expression compare_weak_order_fallback(E, F)is expression-equivalent ([defns.expression.equivalent]) to:

• If the decayed types of E and F differ,compare_weak_order_fallback(E, F) is ill-formed.
• Otherwise, weak_order(E, F) if it is a well-formed expression.
• Otherwise, if the expressions E == F and E < F are both well-formed and each of decltype(E == F) and decltype(E < F) modelsboolean-testable,E == F ? weak_ordering::equivalent :E < F ? weak_ordering::less : weak_ordering::greaterexcept that E and F are evaluated only once.
• Otherwise, compare_weak_order_fallback(E, F) is ill-formed.

[Note 5:

Ill-formed cases above result in substitution failure when compare_weak_order_fallback(E, F) appears in the immediate context of a template instantiation.

— _end note_]

Given subexpressions E and F, the expression compare_partial_order_fallback(E, F)is expression-equivalent ([defns.expression.equivalent]) to:

• If the decayed types of E and F differ,compare_partial_order_fallback(E, F) is ill-formed.
• Otherwise, partial_order(E, F) if it is a well-formed expression.
• Otherwise, if the expressionsE == F, E < F, and F < E are all well-formed and each of decltype(E == F), decltype(E < F), anddecltype(F < E) modelsboolean-testable,E == F ? partial_ordering::equivalent :E < F ? partial_ordering::less :F < E ? partial_ordering::greater : partial_ordering::unorderedexcept that E and F are evaluated only once.
• Otherwise, compare_partial_order_fallback(E, F) is ill-formed.

[Note 6:

Ill-formed cases above result in substitution failure when compare_partial_order_fallback(E, F) appears in the immediate context of a template instantiation.

— _end note_]

17.12.7 Type Ordering [compare.type]

There is an implementation-defined total ordering of all types.

For any (possibly incomplete) types X and Y, the expression TYPE-ORDER(X, Y) is a constant expression ([expr.const]) of type strong_ordering ([cmp.strongord]).

Its value is strong_ordering​::​less if X precedes Yin this implementation-defined total order,strong_ordering​::​greater if Y precedes X, andstrong_ordering​::​equal if they are the same type.

[Note 1:

int, const int and int& are different types.

— _end note_]

[Note 2:

This ordering need not be consistent with the one induced by type_info​::​before.

— _end note_]

[Note 3:

The ordering of TU-local types from different translation units is not observable, because the necessary specialization of type_order is impossible to name.

— _end note_]

template<class T, class U> struct type_order;

The name type_order denotes a Cpp17BinaryTypeTrait ([meta.rqmts]) with a base characteristic ofintegral_constant<strong_ordering, _TYPE-ORDER_(T, U)>.

Recommended practice: The order should be lexicographical on parameter-type-lists and template argument lists.