From 624784a729709a339c5a4d90fae982c4b5826652 Mon Sep 17 00:00:00 2001 From: Ivan Solovev Date: Fri, 22 Nov 2024 15:35:36 +0100 Subject: [PATCH] [docs] Add three-way comparison overview Task-number: QTBUG-128837 Pick-to: 6.8 Change-Id: I64ae12994f8a48ee5f4e48ca6ed7f5980476f2aa Reviewed-by: Marc Mutz (cherry picked from commit 737c87b2b21e30abf5e51126fd8ff4e45521144e) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/doc/src/cpp20-overview.qdoc | 38 +++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/src/corelib/doc/src/cpp20-overview.qdoc b/src/corelib/doc/src/cpp20-overview.qdoc index 58d79fe0a66..ed48e10f94a 100644 --- a/src/corelib/doc/src/cpp20-overview.qdoc +++ b/src/corelib/doc/src/cpp20-overview.qdoc @@ -57,6 +57,44 @@ between the classes. See the corresponding section in the \l {span-STL} {QSpan class documentation} for more details. + \section1 Three-way comparison operator + + C++20 introduced \c {operator<=>()}, also known as the + \l {https://en.cppreference.com/w/cpp/language/operator_comparison#Three-way_comparison} + {three-way comparison operator}, and three ordering types to represent + the results of the comparison: + + \list + \li \l {https://en.cppreference.com/w/cpp/utility/compare/strong_ordering} + {std::strong_ordering}; + \li \l {https://en.cppreference.com/w/cpp/utility/compare/weak_ordering} + {std::weak_ordering}; + \li \l {https://en.cppreference.com/w/cpp/utility/compare/partial_ordering} + {std::partial_ordering}. + \endlist + + In Qt 6.8, many of the QtCore classes got support for \c {operator<=>()}. + To use the new operator, the user project must be compiled in C++20 mode. + + However, starting from Qt 6.7, C++17 users can use + \l {Comparison types overview}{our own equivalents} of the std ordering + types. + + As a C++20 language feature, backporting \c {operator<=>()} to C++17 is not + possible, but you can use the \l Qt::compareThreeWay() function, which acts + like a C++17 version of \c {operator<=>()} for built-in C++ types (such as + integers, floating-point, and enumeration types). + + Qt also defines helper functions \c {compareThreeWay()} for various classes + in QtCore. These are all implemented as \l {https://wg21.link/p1601} + {hidden friends}. Users can implement their own \c {compareThreeWay()} + functions for custom types. + + Finally, Qt provides a \l qCompareThreeWay() function template, which serves + as a generic three-way comparison implementation. It relies on + \l {Qt::compareThreeWay()} and the above-mentioned free + \c {compareThreeWay()} functions in its implementation. + \section1 Additional important features Qt has also adopted a few more features from C++20, such as: