[C++20] Nicolai M. Josuttis's C++20 the complete guide reading minute - operator <=>

Comparisons and Operator <=>

Reference:

std::compare_three_way

std::three_way_comparable

std::lexicographical_compare_three_way

C++20 behaviour breaking existing code with equality operator?

C++20 compiler rewrites

1. Operator != with !(a==b)
2. If above doesn't work, change the order of the operands. !(b==a)

And a, b can be different types.

If there's a free-standing operator:

• A free-standing operator!=(TypeA, TypeB)
• A free-standing operator==(TypeA, TypeB)
• A free-standing operator==(TypeB, TypeA)
• A member function TypeA::operator!=(TypeB)
• A member function TypeA::operator==(TypeB)
• A member function TypeB::operator==(TypeA)
  

Compiler can do the rewrite trick.

Thus To compile

x != y

the compiler might now try all of the following:

x.operator!=(y) // calling member operator!= for x
operator!=(x, y) // calling a free-standing operator!= for x and y
!x.operator==(y) // calling member operator== for x
!operator==(x, y) // calling a free-standing operator== for x and y
!x.operator==(y) // calling member operator== generated by operator<=> for x
!y.operator==(x) // calling member operator== generated by operator<=> for y

The last form is tried to support an implicit type conversion for the first operand, which requires that the operand is a parameter.

In general, the compiler tries to call:

• A free-standing operator !=: operator!=(x, y)
• or a member operator !=: x.operator!=(y)

Having both operators != defined is an ambiguity error.

• A free-standing operator ==: !operator==(x, y)
• or a member operator ==: !x.operator==(y)

Note that the member operator == may be generated from a defaulted operator<=> member.

Having both operators == defined is an ambiguity error.
This also applies if the member operator== is generated due to a defaulted operator<=>.

When an implicit type conversion for the first operand v is necessary, 

the compiler also tries to reorder the operands. Consider:

42 != y // 42 implicitly converts to the type of y

In that case, the compiler tries to call in that order:

• A free-standing or member operator !=
• A free-standing or member operator == (note that the member operator == may be generated from a defaulted operator<=> member)

Note that a rewritten expression never tries to call a member operator !=

Thus To compile

x <= y

new operator <=> and compare the result with 0. 

The operator behaves like a three-way comparison function

returning a negative value for less, 0 for equal, and a positive value for greater 

(the returned value is not a numeric value; it is only a value that supports the corresponding comparisons).

The compiler might now try all of the following:

x.operator<=(y) // calling member operator<= for x
operator<=(x, y) // calling a free-standing operator<= for x and y
x.operator<=>(y) <= 0 // calling member operator<=> for x
operator<=>(x, y) <= 0 // calling a free-standing operator<=> for x and y
0 <= y.operator<=>(x) // calling member operator<=> for y

The last form is tried to support an implicit type conversion for the first operand,

for which it has to become a parameter.

Operator <=>

• The return of <=> operator type should be marked as 'auto' and let compiler to deduce the type.
• Operator <=> takes precedence over all other comparison operators; except explicitly user defined.
• Should only call operator <=> directly when implementing operator<=>.
  However, it can be very helpful to know the returned comparison category.

#include <compare>
// order of the members in the class matters.
class Value {
// defines the ordering and can be used by the relational operators <, <=, >, and >=.
auto operator<=> (const Value& rhs) const = default;
// implicitly generated
// defines equality and can be used by the equality operators == and !=.
auto operator== (const Value& rhs) const = default; 
};

class Value {
private:
long id;

public:
constexpr Value(long i) noexcept
: id{i} {}

// for equality operators:
bool operator== (const Value& rhs) const {
  return id == rhs.id; // defines equality (== and !=)
}

// for relational operators:
auto operator<=> (const Value& rhs) const {
  return id <=> rhs.id; // defines ordering (<, <=, >, and >=)
}
};

Compiler generated operator has following traits

• They are noexcept if comparing the members never throws 
• They are constexpr if comparing the members is possible at compile time 
• Thanks to rewriting, implicit type conversions for the first operand are also supported (This can also be tricky/buggy)

C++20 compiler rewrites

If no operator<=:

x <= y

rewrites with:

  (x <=> y) <= 0;
  // Or:
  0 <= (y <=> x);

• If the value of x<=>y is equal to 0, x and y are equal or equivalent.
• If the value of x<=>y is less than 0, x is less than y.
• If the value of x<=>y is greater than 0, x is greater than y.

However, note that the return type of operator<=> is not an integral value.

Return type is a type that signals the comparison category, which could be 

• strong ordering, 
• weak ordering, 
• or partial ordering.

These types support the comparison with 0 to deal with the result.

Note that operator<=> is for implementing types. Outside the implementation of an operator<=>,

programmers should never invoke <=> directly. Although you can, you should never write 

a<=>b < 0

instead of

a<b

Comparison Category Types

strong ordering (total ordering):

– std::strong_ordering::less

– std::strong_ordering::equal

(also available as std::strong_ordering::equivalent)

– std::strong_ordering::greater

Any value of a given type is less than or equal to or

greater than any other value of this type (including itself).

weak ordering:

– std::weak_ordering::less

– std::weak_ordering::equivalent

– std::weak_ordering::greater

Any value of a given type is less than or equivalent to or greater than any other

value of this type (including itself). However, equivalent values do not have to be equal

 (have the same value).

E.g. "hello" is equivalent to "HELLO"

partial ordering:

– std::partial_ordering::less

– std::partial_ordering::equivalent

– std::partial_ordering::greater

– std::partial_ordering::unordered

Any value of a given type could be less than or equivalent to or greater than any

other value of this type (including itself). 

However, in addition, it may not be possible to specify a specific order between two values at all.

E.g. floating-point types, because they might have the special value

NaN (“not a number”). Any comparison with NaN yields false. Therefore, in this case a comparison

might yield that two values are unordered and the comparison operator might return one of four values.

std::strong_ordering operator<=> (MyType x, MyOtherType y)
{
  if (xIsEqualToY) return std::strong_ordering::equal;
  if (xIsLessThanY) return std::strong_ordering::less;
  return std::strong_ordering::greater;
}

class MyType {
  std::strong_ordering operator<=> (const MyType& rhs) const {
    return value == rhs.value ? std::strong_ordering::equal :
      value < rhs.value ? std::strong_ordering::less :
      std::strong_ordering::greater;
  }
};

// often
class MyType {

  auto operator<=> (const MyType& rhs) const {
    return value <=> rhs.value;
  }
};

C++20 compiler rewrites

if (!(x < y || y < x)) // might call operator<=> to check for equality
if (x <= y && y <= x) // might call operator<=> to check for equality 

Operator <=> return type mismatch due to multiple data members:

class Person {
std::string name;
double value;

  std::partial_ordering operator<=> (const Person& rhs) const { // OK
    auto cmp1 = name <=> rhs.name;
    if (cmp1 != 0) return cmp1; // strong_ordering converted to return type
    return value <=> rhs.value; // partial_ordering used as the return type
  }
};

// better
class Person {
std::string name;
double value;

  auto operator<=> (const Person& rhs) const 
	-> std::common_comparison_category_t<decltype(name <=> rhs.name),
	decltype(value <=> rhs.value)> {
    auto cmp1 = name <=> rhs.name;
    if (cmp1 != 0) return cmp1; // used as or converted to common comparison type
    return value <=> rhs.value; // used as or converted to common comparison type
  }
};

// convert to same comparison category:
class Person {
std::string name;
double value;

  std::strong_ordering operator<=> (const Person& rhs) const {
    auto cmp1 = name <=> rhs.name;
    if (cmp1 != 0) return cmp1; // return strong_ordering for std::string
    // map floating-point comparison result to strong ordering:
    // https://en.cppreference.com/w/cpp/utility/compare/strong_order
    return std::strong_order(value, rhs.value);
  }
};

std::strong_order() yields a std::strong_ordering value according to the passed arguments as follows:

• Using std::strong_order(val1, val2) for the passed types if defined
• Otherwise, if the passed values are floating-point types, using the value of totalOrder() as specified in ISO/IEC/IEEE 60559 (for which, e.g., -0 is less than +0 and -NaN is less than any non-NAN value and +NaN) 
• Using the new function object std::compare_three_way{}(val1, val2) if defined for the passed types std::compare_three_way use like std::less 

For other types that have a weaker ordering and operators == and < defined, you can use the function

object std::compare_strong_order_fallback() accordingly:

class Person {
std::string name;
SomeType value;

  std::strong_ordering operator<=> (const Person& rhs) const {
    auto cmp1 = name <=> rhs.name;
    if (cmp1 != 0) return cmp1; // return strong_ordering for std::string
    // map weak/partial comparison result to strong ordering:
    return std::compare_strong_order_fallback(value, rhs.value);
  }
};

Defaulted operator== and operator<=> contract:

Defaulted operator<=> implies Defaulted operator==
Thus the following is enough to support all six comparison operators for objects of the type Coord:

#include <compare>
struct Coord {
  double x{};
  double y{};
  double z{};
  auto operator<=>(const Coord&) const = default;
};

The second parameter as const lvalue reference (const &) in member function. 

Friend functions might alternatively take both parameters by value.

• The defaulted operators require the support of the members and possible base classes
• Defaulted operators == require the support of == in the members and base classes.
• Defaulted operators <=> require the support of == and either an implemented operator < or a defaulted operator <=> in the members and base classes.
• The operator is noexcept if comparing the members guarantees not to throw.
• The operator is constexpr if comparing the members is possible at compile time.

For empty classes, the defaulted operators compare all objects as equal: 

• operators ==, <=, and >= yield true, 
• operators !=, <, and > yield false, 
• and <=> yields std::strong_ordering::equal.

template<typename T>
class Type {

public:
[[nodiscard]] virtual std::strong_ordering
operator<=>(const Type&) const requires(!std::same_as<T,bool>) = default;
};

// compiler generates equivalent to
template<typename T>
class Type {

public:
[[nodiscard]] virtual std::strong_ordering
operator<=> (const Type&) const requires(!std::same_as<T,bool>) = default;
[[nodiscard]] virtual bool
operator== (const Type&) const requires(!std::same_as<T,bool>) = default;
};

Implementation of the Defaulted operator<=>:

Contract:

If operator<=> is defaulted and you have members or base classes and you call one of the relational

operators, then the following happens:

• If operator<=> is defined for a member or base class, that operator is called.
• Otherwise, operator== and operator< are called to decide whether (from the point of view of the members or base classes)

– The objects are equal/equivalent (operator== yields true)

– The objects are less or greater

– The objects are unordered (only when partial ordering is checked)

In this case, the return type of the defaulted operator<=> calling these operators cannot be auto.

For example, consider the following declarations:

struct B {
bool operator==(const B&) const;
bool operator<(const B&) const;
};

struct D : public B {
  // return type can not be auto due to base type has the operator== and operator< defined
  // because it cannot decide which ordering category the base class has. 
  // In that case, you need operator<=> in the base class too.
  std::strong_ordering operator<=> (const D&) const = default;

  // auto generated by compiler even
  // operator<=> is declared as
  // auto operator<=> (const D&) const = default;
  // which then d1 > d2; does't work but d1 != d2; works.
  bool operator== (const D&) const = default;  
};

// Then:
D d1, d2;
d1 > d2; // calls B::operator== and possibly B::operator<

// If operator== yields true, we know that the result of > is false and that is it. 
// Otherwise, operator< is called to find out whether the expression is true or false.

Compare values of a generic type

Defines a total order for raw pointers.

For forward declare operator<=>() result type; use std::compare_three_way_result_t

template<typename T>
struct Value {
  T val{};
...
  auto operator<=> (const Value& v) const noexcept(noexcept(val<=>val)) {
     return std::compare_three_way{}(val<=>v.val);
  }
};

template<typename T>
struct Value {
  T val{};
...
  std::compare_three_way_result_t<T,T>
    operator<=> (const Value& v) const noexcept(noexcept(val<=>val));
};

Appendix

std::common_comparison_category impl:

namespace detail
{
    template <unsigned int>
    struct common_cmpcat_base     { using type = void; };
    template <>
    struct common_cmpcat_base <0u> { using type = std::strong_ordering; };
    template <>
    struct common_cmpcat_base <2u> { using type = std::partial_ordering; };
    template <>
    struct common_cmpcat_base <4u> { using type = std::weak_ordering; };
    template <>
    struct common_cmpcat_base <6u> { using type = std::partial_ordering; };
} // namespace detail
 
template <class...Ts>
struct common_comparison_category :
    detail::common_cmpcat_base <(0u | ... |
        (std::is_same_v <Ts, std::strong_ordering>  ? 0u :
         std::is_same_v <Ts, std::weak_ordering>    ? 4u :
         std::is_same_v <Ts, std::partial_ordering> ? 2u : 1u)
    )> {};