{"id":24455,"date":"2019-06-27T14:52:46","date_gmt":"2019-06-27T14:52:46","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cppblog\/?p=24455"},"modified":"2025-06-24T17:20:15","modified_gmt":"2025-06-24T17:20:15","slug":"simplify-your-code-with-rocket-science-c20s-spaceship-operator","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/simplify-your-code-with-rocket-science-c20s-spaceship-operator\/","title":{"rendered":"Simplify Your Code With Rocket Science: C++20’s Spaceship Operator"},"content":{"rendered":"

This post is part of a regular series of posts<\/a> where the C++ product team here at Microsoft and other guests answer questions we have received from customers. The questions can be about anything C++ related: MSVC toolset, the standard language and library, the C++ standards committee, isocpp.org, CppCon, etc. Today’s post is by Cameron DaCamara.<\/em><\/p>\n

C++20 adds a new operator, affectionately dubbed the “spaceship” operator: <=><\/code>. There was a post<\/a> awhile back by our very own Sy Brand<\/a> detailing some information regarding this new operator along with some conceptual information about what it is and does.\u00a0 The goal of this post is to explore some concrete applications of this strange new operator and its associated counterpart, the operator==<\/code> (yes it has been changed, for the better!), all while providing some guidelines for its use in everyday code.<\/p>\n

Comparisons<\/h2>\n

It is not an uncommon thing to see code like the following:<\/p>\n

struct IntWrapper {\r\n  int value;\r\n  constexpr IntWrapper(int value): value{value} { }\r\n  bool operator==(const IntWrapper& rhs) const { return value == rhs.value; }\r\n  bool operator!=(const IntWrapper& rhs) const { return !(*this == rhs);    }\r\n  bool operator<(const IntWrapper& rhs)  const { return value < rhs.value;  }\r\n  bool operator<=(const IntWrapper& rhs) const { return !(rhs < *this);     }\r\n  bool operator>(const IntWrapper& rhs)  const { return rhs < *this;        }\r\n  bool operator>=(const IntWrapper& rhs) const { return !(*this < rhs);     }\r\n};\r\n<\/pre>\n
Note: eagle-eyed readers will notice this is actually even less verbose than it should be in pre-C++20 code because these functions should actually all be nonmember friends, more about that later.<\/em><\/p>\n
That is a lot of boilerplate code to write just to make sure that my type is comparable to something of the same type. Well, OK, we deal with it for awhile. Then comes someone who writes this:<\/p>\n
constexpr bool is_lt(const IntWrapper& a, const IntWrapper& b) {\r\n  return a < b;\r\n}\r\nint main() {\r\n  static_assert(is_lt(0, 1));\r\n}\r\n<\/pre>\n
The first thing you will notice is that this program will not compile.<\/p>\n
\nerror C3615: constexpr function 'is_lt' cannot result in a constant expression\n<\/code><\/p>\n
Ah! The problem is that we forgot constexpr<\/code> on our comparison function, drat! So one goes and adds constexpr<\/code> to all of the comparison operators. A few days later someone goes and adds a is_gt<\/code> helper but notices all of the comparison operators do not have an exception specification and goes through the same tedious process of adding noexcept<\/code> to each of the 5 overloads.<\/p>\n
This is where C++20’s new spaceship operator steps in to help us out. Let’s see how the original IntWrapper<\/code> can be written in a C++20 world:<\/p>\n
#include <compare>\r\nstruct IntWrapper {\r\n  int value;\r\n  constexpr IntWrapper(int value): value{value} { }\r\n  auto operator<=>(const IntWrapper&) const = default;\r\n};\r\n<\/pre>\n
The first difference you may notice is the new inclusion of <compare><\/code>. The <compare><\/code><\/a> header is responsible for populating the compiler with all of the comparison category types necessary for the spaceship operator to return a type appropriate for our defaulted function. In the snippet above, the return type auto<\/code> will be deduced to std::strong_ordering<\/code><\/a>.<\/p>\n
Not only did we remove 5 superfluous lines, but we don’t even have to define anything, the compiler does it for us! Our is_lt<\/code> remains unchanged and just works while still being constexpr<\/code> even though we didn’t explicitly specify that in our defaulted operator<=><\/code>. That’s well and good but some people may be scratching their heads as to why<\/em> is_lt<\/code> is allowed to still compile even though it does not even use the spaceship operator at all. Let’s explore the answer to this question.<\/p>\n
Rewriting Expressions<\/h2>\n
In C++20, the compiler is introduced to a new concept referred to “rewritten” expressions. The spaceship operator, along with operator==<\/code>, are among the first two candidates subject to rewritten expressions. For a more concrete example of expression rewriting, let us break down the example provided in is_lt<\/code>.<\/p>\n
During overload resolution the compiler is going to select from a set of viable candidates, all of which match the operator we are looking for. The candidate gathering process is changed very slightly for the case of relational and equivalency operations where the compiler must also gather special rewritten and synthesized candidates ([over.match.oper]\/3.4<\/a>).<\/p>\n
For our expression a < b<\/code> the standard states that we can search the type of a<\/code> for an operator<=><\/code> or a namespace scope function operator<=><\/code> which accepts its type. So the compiler does and it finds that, in fact, a<\/code>‘s type does contain IntWrapper::operator<=><\/code>. The compiler is then allowed to use that operator and rewrite the expression a < b<\/code> as (a <=> b) < 0<\/code>. That rewritten expression is then used as a candidate for normal overload resolution.<\/p>\n
You may find yourself asking why this rewritten expression is valid and correct. The correctness of the expression actually stems from the semantics the spaceship operator provides. The <=><\/code> is a three-way comparison which implies that you get not just a binary result, but an ordering (in most cases) and if you have an ordering you can express that ordering in terms of any relational operations. A quick example, the expression 4 <=> 5<\/code> in C++20 will give you back the result std::strong_ordering::less<\/code><\/a>. The std::strong_ordering::less<\/code> result implies that 4<\/code> is not only different from 5<\/code> but it is strictly less than that value, this makes applying the operation (4 <=> 5) < 0<\/code> correct and exactly accurate to describe our result.<\/p>\n
Using the information above the compiler can take any generalized relational operator (i.e. <<\/code>, ><\/code>, etc.) and rewrite it in terms of the spaceship operator. In the standard the rewritten expression is often referred to as (a <=> b) @ 0<\/code> where the @<\/code> represents any relational operation.<\/p>\n
Synthesizing Expressions<\/h2>\n
Readers may have noticed the subtle mention of “synthesized” expressions above and they play a part in this operator rewriting process as well. Consider a different predicate function:<\/p>\n
constexpr bool is_gt_42(const IntWrapper& a) {\r\n  return 42 < a;\r\n}\r\n<\/pre>\n
If we use our original definition for IntWrapper<\/code> this code will not compile.<\/p>\n
error C2677: binary '<': no global operator found which takes type 'const IntWrapper' (or there is no acceptable conversion)<\/code><\/p>\n
This makes sense in pre-C++20 land, and the way to solve this problem would be to add some extra friend<\/code> functions to IntWrapper<\/code> which take a left-hand side of int<\/code>. If you try to build that sample with a C++20 compiler and our C++20 definition of IntWrapper<\/code> you might notice that it, again, “just works”\u2014another head scratcher. Let’s examine why the code above is still allowed to compile in C++20.<\/p>\n
During overload resolution the compiler will also gather what the standard refers to as “synthesized” candidates, or a rewritten expression with the order of the parameters reversed. In the example above the compiler will try to use the rewritten expression (42 <=> a) < 0<\/code> but it will find that there is no conversion from IntWrapper<\/code> to int<\/code> to satisfy the left-hand side so that rewritten expression is dropped. The compiler also conjures up the “synthesized” expression 0 < (a <=> 42)<\/code> and finds that there is a conversion from int<\/code> to IntWrapper<\/code> through its converting constructor so this candidate is used.<\/p>\n
The goal of the synthesized expressions are to avoid the mess of needing to write the boilerplate of friend<\/code> functions to fill in gaps where your object could be converted from other types. Synthesized expressions are generalized to 0 @ (b <=> a)<\/code>.<\/p>\n
More Complex Types<\/h2>\n
The compiler-generated spaceship operator doesn’t stop at single members of classes, it will generate a correct set of comparisons for all of the sub-objects within your types:<\/p>\n
struct Basics {\r\n  int i;\r\n  char c;\r\n  float f;\r\n  double d;\r\n  auto operator<=>(const Basics&) const = default;\r\n};\r\n\r\nstruct Arrays {\r\n  int ai[1];\r\n  char ac[2];\r\n  float af[3];\r\n  double ad[2][2];\r\n  auto operator<=>(const Arrays&) const = default;\r\n};\r\n\r\nstruct Bases : Basics, Arrays {\r\n  auto operator<=>(const Bases&) const = default;\r\n};\r\n\r\nint main() {\r\n  constexpr Bases a = { { 0, 'c', 1.f, 1. },\r\n                        { { 1 }, { 'a', 'b' }, { 1.f, 2.f, 3.f }, { { 1., 2. }, { 3., 4. } } } };\r\n  constexpr Bases b = { { 0, 'c', 1.f, 1. },\r\n                        { { 1 }, { 'a', 'b' }, { 1.f, 2.f, 3.f }, { { 1., 2. }, { 3., 4. } } } };\r\n  static_assert(a == b);\r\n  static_assert(!(a != b));\r\n  static_assert(!(a < b));\r\n  static_assert(a <= b);\r\n  static_assert(!(a > b));\r\n  static_assert(a >= b);\r\n}\r\n<\/pre>\n
The compiler knows how to expand members of classes that are arrays into their lists of sub-objects and compare them recursively. Of course, if you wanted to write the bodies of these functions yourself you still get the benefit of the compiler rewriting expressions for you.<\/p>\n
Looks Like a Duck, Swims Like a Duck, and Quacks Like operator==<\/code><\/h2>\n
Some very smart people on the standardization committee noticed that the spaceship operator will always perform a lexicographic comparison of elements no matter what. Unconditionally performing lexicographic comparisons can lead to inefficient generated code with the equality operator in particular.<\/p>\n
The canonical example is comparing two strings. If you have the string \"foobar\"<\/code> and you compare it to the string \"foo\"<\/code> using ==<\/code> one would expect that operation to be nearly constant. The efficient string comparison algorithm is thus:<\/p>\n