{"id":5923,"date":"2020-06-11T21:06:14","date_gmt":"2020-06-11T21:06:14","guid":{"rendered":"https:\/\/www.modernescpp.com\/index.php\/c-20-the-three-way-comparison-operator\/"},"modified":"2023-06-26T09:49:06","modified_gmt":"2023-06-26T09:49:06","slug":"c-20-the-three-way-comparison-operator","status":"publish","type":"post","link":"https:\/\/www.modernescpp.com\/index.php\/c-20-the-three-way-comparison-operator\/","title":{"rendered":"C++20: The Three-Way Comparison Operator"},"content":{"rendered":"

The three-way comparison operator <=><\/span> is often just called the spaceship operator. The spaceship operator determines whether A < B, A = B, or A > B for two values, A and B. You can define the spaceship operator, or the compiler can auto-generate it.<\/p>\n

<\/p>\n

 \"TimelineCpp20\"<\/p>\n

Let me start classically to appreciate the three-way comparison operator’s advantages.<\/p>\n

Ordering before C++20<\/h2>\n

I implemented a simple int<\/span> wrapper MyInt<\/span>. Of course, I want to compare MyInt<\/span>. Here is my solution using the isLessThan<\/span> function template.<\/p>\n

 <\/p>\n

<\/p>\n

\n
\/\/ comparisonOperator.cpp<\/span>\r\n\r\n#include <iostream><\/span>\r\n\r\nstruct<\/span> MyInt {\r\n    int<\/span> value;\r\n    explicit<\/span> MyInt(int<\/span> val):<\/span> value{val} { }\r\n    bool<\/span> operator<\/span> <<\/span> (const<\/span> MyInt&<\/span> rhs) const<\/span> {                  \r\n        return<\/span> value <<\/span> rhs.value;\r\n    }\r\n};\r\n\r\ntemplate<\/span> <<\/span>typename<\/span> T><\/span>\r\nconstexpr bool<\/span> isLessThan(const<\/span> T&<\/span> lhs, const<\/span> T&<\/span> rhs) {\r\n    return<\/span> lhs <<\/span> rhs;\r\n}\r\n\r\nint<\/span> main() {\r\n\r\n    std::<\/span>cout <<<\/span> std::<\/span>boolalpha <<<\/span> std::<\/span>endl;\r\n\r\n    MyInt myInt2011<\/span>(2011<\/span>);\r\n    MyInt myInt2014<\/span>(2014<\/span>);\r\n\r\n    std::<\/span>cout <<<\/span> \"isLessThan(myInt2011, myInt2014): \"<\/span>\r\n              <<<\/span> isLessThan(myInt2011, myInt2014) <<<\/span> std::<\/span>endl;\r\n\r\n   std::<\/span>cout <<<\/span> std::<\/span>endl;\r\n\r\n}\r\n<\/pre>\n<\/div>\n
 <\/p>\n
The program works as expected:<\/p>\n
\"comparisonOperator\"<\/p>\n
Honestly, MyInt<\/span> is an unintuitive type. When you define one of the six ordering relations, you should define all. Intuitive types should be at least semi-regular: “C++20: Define the Concept Regular and SemiRegular.<\/a>“<\/p>\n
Now, I have to write a lot of boilerplate code. Here are the missing five operators:<\/p>\n
 <\/p>\n
<\/p>\n
\n
bool<\/span> operator<\/span>==<\/span>(const<\/span> MyInt&<\/span> rhs) const<\/span> { \r\n    return<\/span> value ==<\/span> rhs.value; \r\n}\r\nbool<\/span> operator<\/span>!=<\/span>(const<\/span> MyInt&<\/span> rhs) const<\/span> { \r\n    return<\/span> !<\/span>(*<\/span>this<\/span> ==<\/span> rhs);    \r\n}\r\nbool<\/span> operator<\/span><=<\/span>(const<\/span> MyInt&<\/span> rhs) const<\/span> { \r\n    return<\/span> !<\/span>(rhs <<\/span> *<\/span>this<\/span>);     \r\n}\r\nbool<\/span> operator<\/span>><\/span>(const<\/span> MyInt&<\/span> rhs)  const<\/span> { \r\n    return<\/span> rhs <<\/span> *<\/span>this<\/span>;        \r\n}\r\nbool<\/span> operator<\/span>>=<\/span>(const<\/span> MyInt&<\/span> rhs) const<\/span> {   \r\n    return<\/span> !<\/span>(*<\/span>this<\/span> <<\/span> rhs);     \r\n}\r\n<\/pre>\n<\/div>\n
 <\/p>\n
Done? No! I assume you want to compare MyInt<\/span> with int’s. To support the comparison of an int<\/span> and a MyInt<\/span>, and a MyInt<\/span> and an int<\/span>, you have to overload each operator three times because the constructor is declared as explicit<\/span>. Thanks to explicit<\/span>, no implicit conversion from int<\/span> to MyInt<\/span> kicks in. For convenience, you make the operators to a friend of the class. If you need more background information for my design decisions, read my previous post: “C++ Core Guidelines: Rules for Overloading and Overload Operators<\/a>“<\/p>\n
These are the three overloads for smaller-than.<\/p>\n
 <\/p>\n
<\/p>\n
\n
friend<\/span> bool<\/span> operator<\/span> <<\/span> (const<\/span> MyInts&<\/span> lhs, const<\/span> MyInt&<\/span> rhs) {                  \r\n    return<\/span> lhs.value <<\/span> rhs.value;\r\n}\r\n\r\nfriend<\/span> bool<\/span> operator<\/span> <<\/span> (int<\/span> lhs, const<\/span> MyInt&<\/span> rhs) {                  \r\n    return<\/span> lhs <<\/span> rhs.value;\r\n}\r\n\r\nfriend<\/span> bool<\/span> operator<\/span> <<\/span> (const<\/span> MyInts&<\/span> lhs, int<\/span> rhs) {                  \r\n    return<\/span> lhs.value <<\/span> rhs;\r\n}\r\n<\/pre>\n<\/div>\n
 <\/p>\n
This means, in total, that you have to implement 18 comparison operators. Is this the end of the story? Maybe not, because you decided that the MyInt<\/span> and all operators should become constexpr<\/span>. You should also consider making the operators noexcept.<\/span><\/p>\n
I assume this is enough motivation for the three-way comparison operators.<\/p>\n<\/p>\n
Ordering with C++20<\/h2>\n
You can define the three-way comparison operator or request it from the compiler with =default<\/span>. In both cases, you get all six comparison operators: ==, !=, <, <=, >, <\/span>and >=. <\/span><\/p>\n
 <\/p>\n
<\/p>\n
\n
\/\/ threeWayComparison.cpp<\/span>\r\n\r\n#include <compare><\/span>\r\n#include <iostream><\/span>\r\n\r\nstruct<\/span> MyInt {\r\n    int<\/span> value;\r\n    explicit<\/span> MyInt(int<\/span> val):<\/span> value{val} { }\r\n    auto<\/span> operator<\/span><=><\/span>(const<\/span> MyInt&<\/span> rhs) const<\/span> {           \/\/ (1)<\/span>      \r\n        return<\/span> value <=><\/span> rhs.value;\r\n    }\r\n};\r\n\r\nstruct<\/span> MyDouble {\r\n    double<\/span> value;\r\n    explicit<\/span> constexpr MyDouble(double<\/span> val):<\/span> value{val} { }\r\n    auto<\/span> operator<\/span><=><\/span>(const<\/span> MyDouble&<\/span>) const<\/span> =<\/span> default<\/span>;   \/\/ (2)<\/span>\r\n};\r\n\r\ntemplate<\/span> <<\/span>typename<\/span> T><\/span>\r\nconstexpr bool<\/span> isLessThan(const<\/span> T&<\/span> lhs, const<\/span> T&<\/span> rhs) {\r\n    return<\/span> lhs <<\/span> rhs;\r\n}\r\n\r\nint<\/span> main() {\r\n    \r\n    std::<\/span>cout <<<\/span> std::<\/span>boolalpha <<<\/span> std::<\/span>endl;\r\n    \r\n    MyInt myInt1<\/span>(2011<\/span>);\r\n    MyInt myInt2<\/span>(2014<\/span>);\r\n    \r\n    std::<\/span>cout <<<\/span> \"isLessThan(myInt1, myInt2): \"<\/span>\r\n              <<<\/span> isLessThan(myInt1, myInt2) <<<\/span> std::<\/span>endl;\r\n              \r\n    MyDouble myDouble1<\/span>(2011<\/span>);\r\n    MyDouble myDouble2<\/span>(2014<\/span>);\r\n    \r\n    std::<\/span>cout <<<\/span> \"isLessThan(myDouble1, myDouble2): \"<\/span>\r\n              <<<\/span> isLessThan(myDouble1, myDouble2) <<<\/span> std::<\/span>endl;          \r\n              \r\n    std::<\/span>cout <<<\/span> std::<\/span>endl;\r\n              \r\n}\r\n<\/pre>\n<\/div>\n
 <\/p>\n
The user-defined (1) and the compiler-generated (2) three-way comparison operator work as expected.<\/p>\n
\"threeWayComparison\"<\/p>\n
But there are a few subtle differences in this case. The compiler-deduced return type for MyInt<\/span> (1) supports strong ordering, and the compiler-deduced return type of MyDouble<\/span> supports partial ordering. Floating pointer numbers only <\/span>support partial ordering because floating-point values such as NaN<\/span><\/a> (Not a Number) can not be ordered. For example, NaN<\/span> == NaN<\/span>  is false<\/span>.<\/p>\n
I want to focus on this post about the compiler-generated spaceship operator.<\/p>\n
The Compiler-Generated Spaceship Operator<\/h3>\n
The compiler-generated three-way comparison operator needs the header <compare><\/span>, which is implicit constexpr<\/span> and noexcept<\/span>. Additionally, it performs a lexicographical comparison. What? Let me start with constexpr<\/span>.<\/p>\n
Comparison at Compile-Time<\/h4>\n
The three-way comparison operator is implicit constexpr<\/span>. Consequently, I simplify the previous program threeWayComparison.cpp<\/span> and compare MyDouble<\/span> in the following program at compile-time.<\/p>\n
 <\/p>\n
<\/p>\n
\n
\/\/ threeWayComparisonAtCompileTime.cpp<\/span>\r\n\r\n#include <compare><\/span>\r\n#include <iostream><\/span>\r\n\r\nstruct<\/span> MyDouble {\r\n    double<\/span> value;\r\n    explicit<\/span> constexpr MyDouble(double<\/span> val):<\/span> value{val} { }\r\n    auto<\/span> operator<\/span><=><\/span>(const<\/span> MyDouble&<\/span>) const<\/span> =<\/span> default<\/span>;    \r\n};\r\n\r\ntemplate<\/span> <<\/span>typename<\/span> T><\/span>\r\nconstexpr bool<\/span> isLessThan(const<\/span> T&<\/span> lhs, const<\/span> T&<\/span> rhs) {\r\n    return<\/span> lhs <<\/span> rhs;\r\n}\r\n\r\nint<\/span> main() {\r\n    \r\n    std::<\/span>cout <<<\/span> std::<\/span>boolalpha <<<\/span> std::<\/span>endl;\r\n\r\n              \r\n    constexpr MyDouble myDouble1<\/span>(2011<\/span>);\r\n    constexpr MyDouble myDouble2<\/span>(2014<\/span>);\r\n    \r\n    constexpr bool<\/span> res =<\/span> isLessThan(myDouble1, myDouble2); \/\/ (1)<\/span>\r\n    \r\n    std::<\/span>cout <<<\/span> \"isLessThan(myDouble1, myDouble2): \"<\/span>\r\n              <<<\/span> res <<<\/span> std::<\/span>endl;          \r\n              \r\n    std::<\/span>cout <<<\/span> std::<\/span>endl;\r\n              \r\n}\r\n<\/pre>\n<\/div>\n
 <\/p>\n
I ask for the result of the comparison at compile-time (1), and I get it.<\/p>\n
\"threeWayComparisonAtComileTime\"<\/h4>\n
 <\/p>\n
The compiler-generated three-way comparison operator performs a lexicographical comparison. <\/p>\n
Lexicographical Comparison<\/h4>\n
Lexicographical comparison means that all base classes are compared left to right and all non-static members in their declaration order. I have to qualify: for performance reasons, the compiler-generated ==<\/span> and !=<\/span> operators behave differently in C++20. I will write about this exception to the rule in my next post.<\/p>\n
The post “Simplify Your Code With Rocket Science: C++20\u2019s Spaceship Operator<\/a>” Microsoft C++ Team Blog provides an impressive example of the lexicographical comparison.<\/p>\n
 <\/p>\n
<\/p>\n
\n
struct<\/span> Basics {\r\n  int<\/span> i;\r\n  char<\/span> c;\r\n  float<\/span> f;\r\n  double<\/span> d;\r\n  auto<\/span> operator<\/span><=><\/span>(const<\/span> Basics&<\/span>) const<\/span> =<\/span> default<\/span>;\r\n};\r\n\r\nstruct<\/span> Arrays {\r\n  int<\/span> ai[1<\/span>];\r\n  char<\/span> ac[2<\/span>];\r\n  float<\/span> af[3<\/span>];\r\n  double<\/span> ad[2<\/span>][2<\/span>];\r\n  auto<\/span> operator<\/span><=><\/span>(const<\/span> Arrays&<\/span>) const<\/span> =<\/span> default<\/span>;\r\n};\r\n\r\nstruct<\/span> Bases :<\/span> Basics, Arrays {\r\n  auto<\/span> operator<\/span><=><\/span>(const<\/span> Bases&<\/span>) const<\/span> =<\/span> default<\/span>;\r\n};\r\n\r\nint<\/span> main<\/span>() {\r\n  constexpr Bases a =<\/span> { { 0<\/span>, 'c'<\/span>, 1.f<\/span>, 1.<\/span> },    \/\/ (1)<\/span>\r\n                        { { 1<\/span> }, { 'a'<\/span>, 'b'<\/span> }, { 1.f<\/span>, 2.f<\/span>, 3.f<\/span> }, { { 1.<\/span>, 2.<\/span> }, { 3.<\/span>, 4.<\/span> } } } };\r\n  constexpr Bases b =<\/span> { { 0<\/span>, 'c'<\/span>, 1.f<\/span>, 1.<\/span> },   \/\/ (1)<\/span>\r\n                        { { 1<\/span> }, { 'a'<\/span>, 'b'<\/span> }, { 1.f<\/span>, 2.f<\/span>, 3.f<\/span> }, { { 1.<\/span>, 2.<\/span> }, { 3.<\/span>, 4.<\/span> } } } };\r\n  static_assert(a ==<\/span> b);\r\n  static_assert(!<\/span>(a !=<\/span> b));\r\n  static_assert(!<\/span>(a <<\/span> b));\r\n  static_assert(a <=<\/span> b);\r\n  static_assert(!<\/span>(a ><\/span> b));\r\n  static_assert(a >=<\/span> b);\r\n}\r\n<\/pre>\n<\/div>\n
 <\/p>\n
I assume the most complex aspect of the program is not the spaceship operator but the initialization of Base<\/span> via aggregate initialization (1). Aggregate initialization enables it to directly initialize the members of a class type (class, struct, union<\/span>) when the members are all public<\/span>.  In this case, you can use brace initialization. If you want to know more about aggregate initialization, cppreference.com<\/a> provides more information. I will write more about aggregate initialization in a future post when I will have a closer look at designated initialization in C++20.<\/p>\n
What’s next?<\/h2>\n
The compiler performs quite a clever job when it generates all operators. Ultimately, you get intuitive and efficient comparison operators for free. My next post <\/a>dives deeper into the magic under the hood.<\/p>\n
 <\/p>\n
 <\/p><\/p>\n","protected":false},"excerpt":{"rendered":"
The three-way comparison operator <=> is often just called the spaceship operator. The spaceship operator determines whether A < B, A = B, or A > B for two values, A and B. You can define the spaceship operator, or the compiler can auto-generate it.<\/p>\n","protected":false},"author":21,"featured_media":5199,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[375],"tags":[462],"class_list":["post-5923","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-c-20","tag-spaceship"],"_links":{"self":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/5923","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/comments?post=5923"}],"version-history":[{"count":1,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/5923\/revisions"}],"predecessor-version":[{"id":6738,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/5923\/revisions\/6738"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media\/5199"}],"wp:attachment":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media?parent=5923"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/categories?post=5923"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/tags?post=5923"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}