Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Types and Language Concepts

Three-way comparison: operator<=>

Reference for the C++20 three-way comparison operator <=>: comparison categories, defaulted comparisons, rewritten operators and std::strong_ordering.

The three-way comparison operator <=>, nicknamed the spaceship operator, compares two values and returns an object that says whether the left side is less, equal or greater. It was added in C++20. If you declare auto operator<=>(const T&) const = default;, the compiler generates <=> by comparing the members in order, and the four relational operators <, <=, >, >= work automatically.

The result is not an int. It is one of the comparison category types from <compare>: std::strong_ordering, std::weak_ordering or std::partial_ordering. They can be compared with 0 ((a <=> b) < 0) and carry the exact kind of ordering the type supports.

C++
#include <compare>
struct Version {
    int major, minor;
    auto operator<=>(const Version&) const = default;
};

Try it

C++ Defaulted comparison

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Custom ordering and categories

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
auto operator<=>(const T&) const = default;     // member-wise, in declaration order
R    operator<=>(const T&) const;               // hand-written
bool operator==(const T&) const = default;      // equality, separate
Category Meaning and values
std::strong_ordering Equal values are indistinguishable. less, equal, equivalent (same as equal), greater. Integers, std::string.
std::weak_ordering Equivalent values may still differ (for example case-insensitive strings). less, equivalent, greater.
std::partial_ordering Some pairs have no order. Adds unordered (floating point with NaN).

Returns: a value of the comparison category; test it against 0 or against the named constants such as std::strong_ordering::less.

Usage notes

  • Defaulted <=> also defaults ==. If you write your own <=>, == is not generated; declare bool operator==(const T&) const = default; too.
  • Rewritten operators. a < b is evaluated as (a <=> b) < 0. a != b is rewritten as !(a == b), and a == b can be used with reversed operands, so one function covers both argument orders.
  • The return type of a defaulted <=> is deduced from the members. Use auto, or state the category explicitly when you want to promise one (std::strong_ordering); the declaration fails to compile if a member cannot provide it.
  • Member order matters. The comparison is lexicographic over base classes, then members in declaration order. Reordering members changes the result.
  • Mixed-type comparison works with extra overloads: operator<=>(const T&, int).
  • Built-in types support <=> too. Comparing a signed with an unsigned integer is ill-formed (narrowing), as in other mixed-sign comparisons.
  • Pointers and arrays do not compare element-wise: a raw pointer member compares addresses.
  • Performance. A single <=> call replaces two comparisons in sort-like code, but a defaulted == can stop at the first different member, so keep == separate (the compiler does this for you when both are defaulted).
  • Header: include <compare>. Most standard types already define <=>, so a struct of standard types becomes sortable with one line.
  • Library helpers: std::strong_order, std::weak_order, std::partial_order give total orders for floating point (including NaN); std::compare_three_way is a function object.