std::compare_three_way
| Defined in header <compare>
|
||
| Defined in header <functional>
|
||
| struct compare_three_way; |
(since C++20) | |
Function object for performing comparisons. Deduces the parameter types and the return type of the function call operator.
Contents |
Implementation-defined strict total order over pointers
The function call operator yields the implementation-defined strict total order over pointers if the <=> operator between arguments invokes a built-in comparison operator for a pointer, even if the built-in <=> operator does not.
The implementation-defined strict total order is consistent with the partial order imposed by built-in comparison operators (<=>, <, >, <=, and >=), and consistent among following standard function objects:
- std::less, std::greater, std::less_equal, and std::greater_equal, when the template argument is a pointer type or void
- std::ranges::equal_to, std::ranges::not_equal_to, std::ranges::less, std::ranges::greater, std::ranges::less_equal, std::ranges::greater_equal, and std::compare_three_way
Member types
| Member type | Definition |
is_transparent
|
/* unspecified */ |
Member functions
| operator() |
obtains the result of three-way comparison on both arguments (public member function) |
std::compare_three_way::operator()
| template<class T, class U> requires std::three_way_comparable_with<T, U> // with different semantic requirements |
||
Compares t and u, equivalent to return std::forward<T>(t) <=> std::forward<U>(u);, except when that expression resolves to a call to a builtin operator<=> comparing pointers.
When a call would not invoke a built-in operator comparing pointers, the behavior is undefined if std::three_way_comparable_with<T, U> is not modeled.
When a call would invoke a built-in operator comparing pointers of type P, the result is instead determined as follows:
- Returns std::strong_ordering::less if the (possibly converted) value of the first argument precedes the (possibly converted) value of the second argument in the implementation-defined strict total ordering over all pointer values of type
P. This strict total ordering is consistent with the partial order imposed by the builtin operators<,>,<=, and>=. - Otherwise, returns std::strong_ordering::greater if (possibly converted) value of the second argument precedes the (possibly converted) value of the first argument in the same strict total ordering.
- Otherwise, returns std::strong_ordering::equal.
The behavior is undefined unless the conversion sequences from both T and U to P are equality-preserving (see below).
Equality preservation
Expressions declared in requires expressions of the standard library concepts are required to be equality-preserving (except where stated otherwise).
Example
#include <iostream> #include <compare> struct Rational_2 { int num; int den; // > 0 }; constexpr std::weak_ordering operator<=>(Rational_2 lhs, Rational_2 rhs) { return lhs.num * rhs.den <=> rhs.num * lhs.den; } void print(std::weak_ordering value) { if (value == 0) std::cout << "equal\n"; else if (value < 0) std::cout << "less\n"; else std::cout << "greater\n"; } int main() { Rational_2 c{6,5}; Rational_2 d{8,7}; print(c <=> d); print(std::compare_three_way{}(c,d)); }
Output:
greater greater
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 3530 | C++20 | syntactic checks were relaxed while comparing pointers | only semantic requirements relaxed |
See also
| (C++20) |
constrained function object implementing x == y (class) |
| (C++20) |
constrained function object implementing x != y (class) |
| (C++20) |
constrained function object implementing x < y (class) |
| (C++20) |
constrained function object implementing x > y (class) |
| (C++20) |
constrained function object implementing x <= y (class) |
| (C++20) |
constrained function object implementing x >= y (class) |
