diff options
| author | Ivan Solovev <ivan.solovev@qt.io> | 2023-09-29 20:36:31 +0200 |
|---|---|---|
| committer | Ivan Solovev <ivan.solovev@qt.io> | 2023-12-07 23:36:14 +0100 |
| commit | 3d231e27a8c38f8e840e161e76be3a153d6b0aa9 (patch) | |
| tree | 4e66c98abd30052ab9672b1696797e63607a4e38 /src/corelib/global/qcompare.cpp | |
| parent | 7cb25eb33c7875c913b4cb0154afd741e602d8aa (diff) | |
Long live qCompareThreeWay()
qCompareThreeWay() is a top-level wrapper around the helper
three-way comparison methods, which is mostly convenient for
generic client code.
When implementing compareThreeWay() for Qt types, we normally
provide the implementation only for (LeftType, RightType) pair,
but not the reversed one.
However, it is expected that qCompareThreeWay() would be available
for both combinations, because the reversed result can be easily
calculated.
Solve it by providing a helper hasCompareThreeWay<LT, RT> variable
and branching the implementation based on its value.
The noexcept check is inspired by the old implementation of qSwap().
[ChangeLog][QtCore] Added qCompareThreeWay() as a public API for
three-way comparison.
Task-number: QTBUG-104113
Change-Id: I6f24494d968c336f3dcdf620004b4190769cbdb2
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
Diffstat (limited to 'src/corelib/global/qcompare.cpp')
| -rw-r--r-- | src/corelib/global/qcompare.cpp | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/src/corelib/global/qcompare.cpp b/src/corelib/global/qcompare.cpp index 4f3a2400688..91124c3d7dd 100644 --- a/src/corelib/global/qcompare.cpp +++ b/src/corelib/global/qcompare.cpp @@ -134,6 +134,16 @@ CHECK(strong, equivalent); This header introduces the \l Qt::partial_ordering, \l Qt::weak_ordering, and \l Qt::strong_ordering types, which are Qt's C++17 backports of \c {std::*_ordering} types. + + This header also contains functions for implementing three-way comparison + in C++17. + + The \c {Qt::compareThreeWay()} function overloads provide three-way + comparison for built-in C++ types. + + The \l qCompareThreeWay() template serves as a generic three-way comparison + implementation. It relies on \c {Qt::compareThreeWay()} and free + \c {compareThreeWay()} functions in its implementation. */ /*! @@ -1250,4 +1260,53 @@ CHECK(strong, equivalent); between \a lhs and \a rhs. */ +/*! + \fn template <typename LeftType, typename RightType> qCompareThreeWay(const LeftType &lhs, const RightType &rhs) + \since 6.7 + \relates <QtCompare> + + Performs the three-way comparison on \a lhs and \a rhs and returns one of + the Qt ordering types as a result. This function is available for both + C++17 and C++20. + + The actual returned type depends on \c LeftType and \c RightType. + + \note This function template is only available when \c {compareThreeWay()} + is implemented for the \c {(LeftType, RightType)} pair or the reversed + \c {(RightType, LeftType)} pair. + + This method is equivalent to + + \code + using Qt::compareThreeWay; + return compareThreeWay(lhs, rhs); + \endcode + + where \c {Qt::compareThreeWay} is the Qt implementation of three-way + comparison for built-in types. + + The free \c {compareThreeWay} functions should provide three-way comparison + for custom types. The functions should return one of the Qt ordering types. + + Qt provides \c {compareThreeWay} implementation for some of its types. + + \note \b {Do not} re-implement \c {compareThreeWay()} for Qt types, as more + Qt types will get support for it in future Qt releases. + + Use this function primarly in generic code, when you know nothing about + \c LeftType and \c RightType. + + If you know the types, use + + \list + \li \c {Qt::compareThreeWay} for built-in types + \li \c {compareThreeWay} for custom types + \endlist + + Use \c {operator<=>()} directly in code that will only be compiled with + C++20 or later. + + \sa Qt::partial_ordering, Qt::weak_ordering, Qt::strong_ordering +*/ + QT_END_NAMESPACE |