diff options
Diffstat (limited to 'src/corelib/global/qcompare.cpp')
| -rw-r--r-- | src/corelib/global/qcompare.cpp | 1357 |
1 files changed, 1357 insertions, 0 deletions
diff --git a/src/corelib/global/qcompare.cpp b/src/corelib/global/qcompare.cpp new file mode 100644 index 0000000000..ac220b8434 --- /dev/null +++ b/src/corelib/global/qcompare.cpp @@ -0,0 +1,1357 @@ +// Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only + +#include "qcompare.h" + +#ifdef __cpp_lib_bit_cast +#include <bit> +#endif + +QT_BEGIN_NAMESPACE + +#ifdef __cpp_lib_three_way_comparison +#ifdef __cpp_lib_bit_cast +#define CHECK(type, flag) \ + static_assert(std::bit_cast<Qt:: type ## _ordering>(std:: type ## _ordering:: flag) \ + == Qt:: type ## _ordering :: flag); \ + static_assert(std::bit_cast<std:: type ## _ordering>(Qt:: type ## _ordering:: flag) \ + == std:: type ## _ordering :: flag) \ + /* end */ +CHECK(partial, unordered); +CHECK(partial, less); +CHECK(partial, greater); +CHECK(partial, equivalent); +CHECK(weak, less); +CHECK(weak, greater); +CHECK(weak, equivalent); +CHECK(strong, less); +CHECK(strong, greater); +CHECK(strong, equal); +CHECK(strong, equivalent); +#undef CHECK +#endif // __cpp_lib_bit_cast +#endif //__cpp_lib_three_way_comparison + + +/*! + \page comparison-types.html overview + \title Comparison types overview + \keyword three-way comparison + \inmodule QtCore + \sa Qt::strong_ordering, Qt::weak_ordering, Qt::partial_ordering + + \note Qt's comparison types provide functionality equivalent to their C++20 + standard counterparts. The only reason why they exist is to make the + functionality available in C++17 builds, too. In a C++20 build, they + implicitly convert to and from the \c std types, making them fully + interchangeable. We therefore recommended that you prefer to use the C++ + standard types in your code, if you can use C++20 in your projects already. + The Qt comparison types will be removed in Qt 7. + + Qt provides several comparison types for a \l + {https://en.cppreference.com/w/cpp/language/operator_comparison#Three-way_comparison} + {three-way comparison}, which are comparable against a \e {zero literal}. + To use these comparison types, you need to include the \c <QtCompare> + header. These comparison types are categorized based on their \e order, + which is a mathematical concept used to describe the arrangement or ranking + of elements. The following categories are provided: + + \table 100 % + \header + \li C++ type + \li Qt type + \li strict + \li total + \li Example + \row + \li \l {https://en.cppreference.com/w/cpp/utility/compare/strong_ordering} + {std::strong_ordering} + \li Qt::strong_ordering + \li yes + \li yes + \li integral types, case-sensitive strings, QDate, QTime + \row + \li \l {https://en.cppreference.com/w/cpp/utility/compare/weak_ordering} + {std::weak_ordering} + \li Qt::weak_ordering + \li no + \li yes + \li case-insensitive strings, unordered associative containers, QDateTime + \row + \li \l {https://en.cppreference.com/w/cpp/utility/compare/partial_ordering} + {std::partial_ordering} + \li Qt::partial_ordering + \li no + \li no + \li floating-point types, QOperatingSystemVersion, QVariant + \endtable + + The strongest comparison type, Qt::strong_ordering, represents a strict total + order. It requires that any two elements be comparable in a way where + equality implies substitutability. In other words, equivalent values + cannot be distinguished from each other. A practical example would be the + case-sensitive comparison of two strings. For instance, when comparing the + values \c "Qt" and \c "Qt" the result would be \l Qt::strong_ordering::equal. + Both values are indistinguishable and all deterministic operations performed + on these values would yield identical results. + + Qt::weak_ordering represents a total order. While any two values still need to + be comparable, equivalent values may be distinguishable. The canonical + example here would be the case-insensitive comparison of two strings. For + instance, when comparing the values \c "Qt" and \c "qt" both hold the same + letters but with different representations. This comparison would + result in \l Qt::weak_ordering::equivalent, but not actually \c Equal. + Another example would be QDateTime, which can represent a given instant in + time in terms of local time or any other time-zone, including UTC. The + different representations are equivalent, even though their \c time() and + sometimes \c date() may differ. + + Qt::partial_ordering represents, as the name implies, a partial ordering. It + allows for the possibility that two values may not be comparable, resulting + in an \l {Qt::partial_ordering::}{unordered} state. Additionally, equivalent + values may still be distinguishable. A practical example would be the + comparison of two floating-point values, comparing with NaN (Not-a-Number) + would yield an unordered result. Another example is the comparison of two + QOperatingSystemVersion objects. Comparing versions of two different + operating systems, such as Android and Windows, would produce an unordered + result. + + Utilizing these comparison types enhances the expressiveness of defining + relations. Furthermore, they serve as a fundamental component for + implementing three-way comparison with C++17. +*/ + +/*! + \headerfile <QtCompare> + \inmodule QtCore + \title Classes and helpers for defining comparison operators + \keyword qtcompare + + \brief The <QtCompare> header file defines \c {Qt::*_ordering} types and helper + macros for defining comparison operators. + + 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. +*/ + +/*! + \class Qt::strong_ordering + \inmodule QtCore + \brief Qt::strong_ordering represents a comparison where equivalent values are + indistinguishable. + \sa Qt::weak_ordering, Qt::partial_ordering, {Comparison types overview} + \since 6.7 + + A value of type Qt::strong_ordering is typically returned from a three-way + comparison function. Such a function compares two objects and establishes + how they are ordered. It uses this return type to indicate that the ordering + is strict; that is, the function establishes a well-defined total order. + + Qt::strong_ordering has four values, represented by the following symbolic + constants: + + \list + \li \l less represents that the left operand is less than the right; + \li \l equal represents that the left operand is equivalent to the right; + \li \l equivalent is an alias for \c equal; + \li \l greater represents that the left operand is greater than the right. + \endlist + + Qt::strong_ordering is idiomatically used by comparing an instance against a + literal zero, for instance like this: + + \code + + // given a, b, c, d as objects of some type that allows for a 3-way compare, + // and a compare function declared as follows: + + Qt::strong_ordering compare(T lhs, T rhs); // defined out-of-line + ~~~ + + Qt::strong_ordering result = compare(a, b); + if (result < 0) { + // a is less than b + } + + if (compare(c, d) >= 0) { + // c is greater than or equal to d + } + + \endcode +*/ + +/*! + \fn Qt::strong_ordering::operator Qt::partial_ordering() const + + Converts this Qt::strong_ordering value to a Qt::partial_ordering object using the + following rules: + + \list + \li \l less converts to \l {Qt::partial_ordering::less}. + \li \l equivalent converts to \l {Qt::partial_ordering::equivalent}. + \li \l equal converts to \l {Qt::partial_ordering::equivalent}. + \li \l greater converts to \l {Qt::partial_ordering::greater}. + \endlist +*/ + +/*! + \fn Qt::strong_ordering::operator Qt::weak_ordering() const + + Converts this Qt::strong_ordering value to a Qt::weak_ordering object using the + following rules: + + \list + \li \l less converts to \l {Qt::weak_ordering::less}. + \li \l equivalent converts to \l {Qt::weak_ordering::equivalent}. + \li \l equal converts to \l {Qt::weak_ordering::equivalent}. + \li \l greater converts to \l {Qt::weak_ordering::greater}. + \endlist +*/ + +/*! + \fn Qt::strong_ordering::strong_ordering(std::strong_ordering stdorder) + + Constructs a Qt::strong_ordering object from \a stdorder using the following rules: + + \list + \li std::strong_ordering::less converts to \l less. + \li std::strong_ordering::equivalent converts to \l equivalent. + \li std::strong_ordering::equal converts to \l equal. + \li std::strong_ordering::greater converts to \l greater. + \endlist +*/ + +/*! + \fn Qt::strong_ordering::operator std::strong_ordering() const + + Converts this Qt::strong_ordering value to a std::strong_ordering object using + the following rules: + + \list + \li \l less converts to std::strong_ordering::less. + \li \l equivalent converts to std::strong_ordering::equivalent. + \li \l equal converts to std::strong_ordering::equal. + \li \l greater converts to std::strong_ordering::greater. + \endlist +*/ + +/*! + \fn bool Qt::strong_ordering::operator==(Qt::strong_ordering lhs, Qt::strong_ordering rhs) + + Returns true if \a lhs and \a rhs represent the same result; + otherwise, returns false. +*/ + +/*! + \fn bool Qt::strong_ordering::operator!=(Qt::strong_ordering lhs, Qt::strong_ordering rhs) + + Returns true if \a lhs and \a rhs represent different results; + otherwise, returns true. +*/ + +/*! + \internal + \relates Qt::strong_ordering + \fn bool operator==(Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator!=(Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator< (Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator<=(Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator> (Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator>=(Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + + \fn bool operator==(QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs) + \fn bool operator!=(QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs) + \fn bool operator< (QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs) + \fn bool operator<=(QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs) + \fn bool operator> (QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs) + \fn bool operator>=(QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs) +*/ + +/*! + \fn Qt::strong_ordering::is_eq (Qt::strong_ordering o) + \fn Qt::strong_ordering::is_neq (Qt::strong_ordering o) + \fn Qt::strong_ordering::is_lt (Qt::strong_ordering o) + \fn Qt::strong_ordering::is_lteq(Qt::strong_ordering o) + \fn Qt::strong_ordering::is_gt (Qt::strong_ordering o) + \fn Qt::strong_ordering::is_gteq(Qt::strong_ordering o) + +//! [is_eq_table] + Converts \a o into the result of one of the six relational operators: + \table + \header \li Function \li Operation + \row \li \c{is_eq} \li \a o \c{== 0} + \row \li \c{is_neq} \li \a o \c{!= 0} + \row \li \c{is_lt} \li \a o \c{< 0} + \row \li \c{is_lteq} \li \a o \c{<= 0} + \row \li \c{is_gt} \li \a o \c{> 0} + \row \li \c{is_gteq} \li \a o \c{>= 0} + \endtable +//! [is_eq_table] + + These functions are provided for compatibility with \c{std::strong_ordering}. +*/ + +/*! + \variable Qt::strong_ordering::less + + Represents the result of a comparison where the left operand is less + than the right operand. +*/ + +/*! + \variable Qt::strong_ordering::equivalent + + Represents the result of a comparison where the left operand is equal + to the right operand. Same as \l {Qt::strong_ordering::equal}. +*/ + +/*! + \variable Qt::strong_ordering::equal + + Represents the result of a comparison where the left operand is equal + to the right operand. Same as \l {Qt::strong_ordering::equivalent}. +*/ + +/*! + \variable Qt::strong_ordering::greater + + Represents the result of a comparison where the left operand is greater + than the right operand. +*/ + +/*! + \class Qt::weak_ordering + \inmodule QtCore + \brief Qt::weak_ordering represents a comparison where equivalent values are + still distinguishable. + \sa Qt::strong_ordering, Qt::partial_ordering, {Comparison types overview} + \since 6.7 + + A value of type Qt::weak_ordering is typically returned from a three-way + comparison function. Such a function compares two objects and establishes + how they are ordered. It uses this return type to indicate that the ordering + is weak; that is, equivalent values may be distinguishable. + + Qt::weak_ordering has three values, represented by the following symbolic + constants: + + \list + \li \l less represents that the left operand is less than the right; + \li \l equivalent represents that the left operand is equivalent to the + right; + \li \l greater represents that the left operand is greater than the right, + \endlist + + Qt::weak_ordering is idiomatically used by comparing an instance against a + literal zero, for instance like this: + + \code + + // given a, b, c, d as objects of some type that allows for a 3-way compare, + // and a compare function declared as follows: + + Qt::weak_ordering compare(T lhs, T rhs); // defined out-of-line + ~~~ + + Qt::weak_ordering result = compare(a, b); + if (result < 0) { + // a is less than b + } + + if (compare(c, d) >= 0) { + // c is greater than or equivalent to d + } + + \endcode +*/ + +/*! + \fn Qt::weak_ordering::operator Qt::partial_ordering() const + + Converts this Qt::weak_ordering value to a Qt::partial_ordering object using the + following rules: + + \list + \li \l less converts to \l {Qt::partial_ordering::less}. + \li \l equivalent converts to \l {Qt::partial_ordering::equivalent}. + \li \l greater converts to \l {Qt::partial_ordering::greater}. + \endlist +*/ + +/*! + \fn Qt::weak_ordering::weak_ordering(std::weak_ordering stdorder) + + Constructs a Qt::weak_ordering object from \a stdorder using the following rules: + + \list + \li std::weak_ordering::less converts to \l less. + \li std::weak_ordering::equivalent converts to \l equivalent. + \li std::weak_ordering::greater converts to \l greater. + \endlist +*/ + +/*! + \fn Qt::weak_ordering::operator std::weak_ordering() const + + Converts this Qt::weak_ordering value to a std::weak_ordering object using + the following rules: + + \list + \li \l less converts to std::weak_ordering::less. + \li \l equivalent converts to std::weak_ordering::equivalent. + \li \l greater converts to std::weak_ordering::greater. + \endlist +*/ + +/*! + \fn bool Qt::weak_ordering::operator==(Qt::weak_ordering lhs, Qt::weak_ordering rhs) + + Return true if \a lhs and \a rhs represent the same result; + otherwise, returns false. +*/ + +/*! + \fn bool Qt::weak_ordering::operator!=(Qt::weak_ordering lhs, Qt::weak_ordering rhs) + + Return true if \a lhs and \a rhs represent different results; + otherwise, returns true. +*/ + +/*! + \internal + \relates Qt::weak_ordering + \fn bool operator==(Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator!=(Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator< (Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator<=(Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator> (Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator>=(Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + + \fn bool operator==(QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs) + \fn bool operator!=(QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs) + \fn bool operator< (QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs) + \fn bool operator<=(QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs) + \fn bool operator> (QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs) + \fn bool operator>=(QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs) +*/ + +/*! + \fn Qt::weak_ordering::is_eq (Qt::weak_ordering o) + \fn Qt::weak_ordering::is_neq (Qt::weak_ordering o) + \fn Qt::weak_ordering::is_lt (Qt::weak_ordering o) + \fn Qt::weak_ordering::is_lteq(Qt::weak_ordering o) + \fn Qt::weak_ordering::is_gt (Qt::weak_ordering o) + \fn Qt::weak_ordering::is_gteq(Qt::weak_ordering o) + + \include qcompare.cpp is_eq_table + + These functions are provided for compatibility with \c{std::weak_ordering}. +*/ + +/*! + \variable Qt::weak_ordering::less + + Represents the result of a comparison where the left operand is less than + the right operand. +*/ + +/*! + \variable Qt::weak_ordering::equivalent + + Represents the result of a comparison where the left operand is equivalent + to the right operand. +*/ + +/*! + \variable Qt::weak_ordering::greater + + Represents the result of a comparison where the left operand is greater + than the right operand. +*/ + +/*! + \class Qt::partial_ordering + \inmodule QtCore + \brief Qt::partial_ordering represents the result of a comparison that allows + for unordered results. + \sa Qt::strong_ordering, Qt::weak_ordering, {Comparison types overview} + \since 6.7 + + A value of type Qt::partial_ordering is typically returned from a + three-way comparison function. Such a function compares two objects, + establishing whether they are ordered and, if so, their ordering. It uses + this return type to indicate that the ordering is partial; that is, not all + pairs of values are ordered. + + Qt::partial_ordering has four values, represented by the following symbolic + constants: + + \list + \li \l less represents that the left operand is less than the right; + \li \l equivalent represents that the two operands are equivalent; + \li \l greater represents that the left operand is greater than the right; + \li \l unordered represents that the two operands are \e {not ordered}. + \endlist + + Qt::partial_ordering is idiomatically used by comparing an instance + against a literal zero, for instance like this: + + \code + + // given a, b, c, d as objects of some type that allows for a 3-way compare, + // and a compare function declared as follows: + + Qt::partial_ordering compare(T lhs, T rhs); // defined out-of-line + ~~~ + + Qt::partial_ordering result = compare(a, b); + if (result < 0) { + // a is less than b + } + + if (compare(c, d) >= 0) { + // c is greater than or equal to d + } + + \endcode + + Comparing Qt::partial_ordering::unordered against literal 0 always returns + a \c false result. +*/ + +/*! + \fn Qt::partial_ordering::partial_ordering(std::partial_ordering stdorder) + + Constructs a Qt::partial_ordering object from \a stdorder using the following + rules: + + \list + \li std::partial_ordering::less converts to \l less. + \li std::partial_ordering::equivalent converts to \l equivalent. + \li std::partial_ordering::greater converts to \l greater. + \li std::partial_ordering::unordered converts to \l unordered + \endlist +*/ + +/*! + \fn Qt::partial_ordering::operator std::partial_ordering() const + + Converts this Qt::partial_ordering value to a std::partial_ordering object using + the following rules: + + \list + \li \l less converts to std::partial_ordering::less. + \li \l equivalent converts to std::partial_ordering::equivalent. + \li \l greater converts to std::partial_ordering::greater. + \li \l unordered converts to std::partial_ordering::unordered. + \endlist +*/ + +/*! + \fn bool Qt::partial_ordering::operator==(Qt::partial_ordering lhs, Qt::partial_ordering rhs) + + Return true if \a lhs and \a rhs represent the same result; + otherwise, returns false. +*/ + +/*! + \fn bool Qt::partial_ordering::operator!=(Qt::partial_ordering lhs, Qt::partial_ordering rhs) + + Return true if \a lhs and \a rhs represent different results; + otherwise, returns true. +*/ + +/*! + \internal + \relates Qt::partial_ordering + \fn bool operator==(Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator!=(Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator< (Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator<=(Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator> (Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator>=(Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero) + + \fn bool operator==(QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs) + \fn bool operator!=(QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs) + \fn bool operator< (QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs) + \fn bool operator<=(QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs) + \fn bool operator> (QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs) + \fn bool operator>=(QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs) +*/ + +/*! + \fn Qt::partial_ordering::is_eq (Qt::partial_ordering o) + \fn Qt::partial_ordering::is_neq (Qt::partial_ordering o) + \fn Qt::partial_ordering::is_lt (Qt::partial_ordering o) + \fn Qt::partial_ordering::is_lteq(Qt::partial_ordering o) + \fn Qt::partial_ordering::is_gt (Qt::partial_ordering o) + \fn Qt::partial_ordering::is_gteq(Qt::partial_ordering o) + + \include qcompare.cpp is_eq_table + + These functions are provided for compatibility with \c{std::partial_ordering}. +*/ + +/*! + \variable Qt::partial_ordering::less + + Represents the result of a comparison where the left operand is less than + the right operand. +*/ + +/*! + \variable Qt::partial_ordering::equivalent + + Represents the result of a comparison where the two operands are equivalent. +*/ + +/*! + \variable Qt::partial_ordering::greater + + Represents the result of a comparison where the left operand is greater + than the right operand. +*/ + +/*! + \variable Qt::partial_ordering::unordered + + Represents the result of a comparison where there is no ordering + relationship between the two operands. +*/ + +/*! + \class QPartialOrdering + \inmodule QtCore + \brief QPartialOrdering represents the result of a comparison that allows + for unordered results. + \sa Qt::strong_ordering, Qt::weak_ordering, {Comparison types overview} + \since 6.0 + + A value of type QPartialOrdering is typically returned from a + three-way comparison function. Such a function compares two objects, + establishing whether they are ordered and, if so, their ordering. It uses + this return type to indicate that the ordering is partial; that is, not all + pairs of values are ordered. + + QPartialOrdering has four values, represented by the following symbolic + constants: + + \list + \li \l less represents that the left operand is less than the right; + \li \l equivalent represents that the two operands are equivalent; + \li \l greater represents that the left operand is greater than the right; + \li \l unordered represents that the two operands are \e {not ordered}. + \endlist + + QPartialOrdering is idiomatically used by comparing an instance + against a literal zero, for instance like this: + + \code + + // given a, b, c, d as objects of some type that allows for a 3-way compare, + // and a compare function declared as follows: + + QPartialOrdering compare(T lhs, T rhs); // defined out-of-line + ~~~ + + QPartialOrdering result = compare(a, b); + if (result < 0) { + // a is less than b + } + + if (compare(c, d) >= 0) { + // c is greater than or equal to d + } + + \endcode + + Comparing QPartialOrdering::unordered against literal 0 always returns + a \c false result. +*/ + +/*! + \fn QPartialOrdering::QPartialOrdering(std::partial_ordering stdorder) + + Constructs a QPartialOrdering object from \a stdorder using the following + rules: + + \list + \li std::partial_ordering::less converts to \l less. + \li std::partial_ordering::equivalent converts to \l equivalent. + \li std::partial_ordering::greater converts to \l greater. + \li std::partial_ordering::unordered converts to \l unordered + \endlist +*/ + +/*! + \fn QPartialOrdering::operator std::partial_ordering() const + + Converts this QPartialOrdering value to a std::partial_ordering object using + the following rules: + + \list + \li \l less converts to std::partial_ordering::less. + \li \l equivalent converts to std::partial_ordering::equivalent. + \li \l greater converts to std::partial_ordering::greater. + \li \l unordered converts to std::partial_ordering::unordered. + \endlist +*/ + +/*! + \fn bool QPartialOrdering::operator==(QPartialOrdering lhs, QPartialOrdering rhs) + + Return true if \a lhs and \a rhs represent the same result; + otherwise, returns false. +*/ + +/*! + \fn bool QPartialOrdering::operator!=(QPartialOrdering lhs, QPartialOrdering rhs) + + Return true if \a lhs and \a rhs represent different results; + otherwise, returns true. +*/ + +/*! + \internal + \relates QPartialOrdering + \fn bool operator==(QPartialOrdering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator!=(QPartialOrdering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator< (QPartialOrdering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator<=(QPartialOrdering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator> (QPartialOrdering lhs, QtPrivate::CompareAgainstLiteralZero) + \fn bool operator>=(QPartialOrdering lhs, QtPrivate::CompareAgainstLiteralZero) + + \fn bool operator==(QtPrivate::CompareAgainstLiteralZero, QPartialOrdering rhs) + \fn bool operator!=(QtPrivate::CompareAgainstLiteralZero, QPartialOrdering rhs) + \fn bool operator< (QtPrivate::CompareAgainstLiteralZero, QPartialOrdering rhs) + \fn bool operator<=(QtPrivate::CompareAgainstLiteralZero, QPartialOrdering rhs) + \fn bool operator> (QtPrivate::CompareAgainstLiteralZero, QPartialOrdering rhs) + \fn bool operator>=(QtPrivate::CompareAgainstLiteralZero, QPartialOrdering rhs) +*/ + +/*! + \fn QPartialOrdering::is_eq (QPartialOrdering o) + \fn QPartialOrdering::is_neq (QPartialOrdering o) + \fn QPartialOrdering::is_lt (QPartialOrdering o) + \fn QPartialOrdering::is_lteq(QPartialOrdering o) + \fn QPartialOrdering::is_gt (QPartialOrdering o) + \fn QPartialOrdering::is_gteq(QPartialOrdering o) + + \since 6.7 + \include qcompare.cpp is_eq_table + + These functions are provided for compatibility with \c{std::partial_ordering}. +*/ + +/*! + \variable QPartialOrdering::less + + Represents the result of a comparison where the left operand is less than + the right operand. +*/ + +/*! + \variable QPartialOrdering::equivalent + + Represents the result of a comparison where the two operands are equivalent. +*/ + +/*! + \variable QPartialOrdering::greater + + Represents the result of a comparison where the left operand is greater + than the right operand. +*/ + +/*! + \variable QPartialOrdering::unordered + + Represents the result of a comparison where there is no ordering + relationship between the two operands. +*/ + +/*! + \variable QPartialOrdering::Less + + Represents the result of a comparison where the left operand is less than + the right operand. +*/ + +/*! + \variable QPartialOrdering::Equivalent + + Represents the result of a comparison where the two operands are equivalent. +*/ + +/*! + \variable QPartialOrdering::Greater + + Represents the result of a comparison where the left operand is greater + than the right operand. +*/ + +/*! + \variable QPartialOrdering::Unordered + + Represents the result of a comparison where there is no ordering + relationship between the two operands. +*/ + +/*! + \internal + \macro Q_DECLARE_EQUALITY_COMPARABLE(Type) + \macro Q_DECLARE_EQUALITY_COMPARABLE(LeftType, RightType) + \macro Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE(Type) + \macro Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE(LeftType, RightType) + \since 6.7 + \relates <QtCompare> + + These macros are used to generate \c {operator==()} and \c {operator!=()}. + + In C++17 mode, the mixed-type overloads also generate the reversed + operators. + + In C++20 mode, only \c {operator==()} is defined. \c {operator!=()}, + as well as the reversed operators for mixed-type comparison, are synthesized + by the compiler. + + The operators are implemented in terms of a helper function + \c {comparesEqual()}. + It's the user's responsibility to declare and define this function. + + Consider the following example of a comparison operators declaration: + + \code + class MyClass { + ... + private: + friend bool comparesEqual(const MyClass &, const MyClass &) noexcept; + Q_DECLARE_EQUALITY_COMPARABLE(MyClass) + }; + \endcode + + When compiled with C++17, the macro will expand into the following code: + + \code + friend bool operator==(const MyClass &lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + friend bool operator!=(const MyClass &lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + \endcode + + When compiled with C++20, the macro will expand only into \c {operator==()}: + + \code + friend bool operator==(const MyClass &lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + \endcode + + The \c {*_LITERAL_TYPE} versions of the macros are used to generate + \c constexpr operators. This means that the helper \c {comparesEqual()} + function must also be \c constexpr. + + Consider the following example of a mixed-type \c constexpr comparison + operators declaration: + + \code + class MyClass { + ... + private: + friend constexpr bool comparesEqual(const MyClass &, int) noexcept; + Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE(MyClass, int) + }; + \endcode + + When compiled with C++17, the macro will expand into the following code: + + \code + friend constexpr bool operator==(const MyClass &lhs, int rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + friend constexpr bool operator!=(const MyClass &lhs, int rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + friend constexpr bool operator==(int lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + friend constexpr bool operator!=(int lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + \endcode + + When compiled with C++20, the macro expands only into \c {operator==()}: + + \code + friend constexpr bool operator==(const MyClass &lhs, int rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + \endcode +*/ + +/*! + \internal + \macro Q_DECLARE_PARTIALLY_ORDERED(Type) + \macro Q_DECLARE_PARTIALLY_ORDERED(LeftType, RightType) + \macro Q_DECLARE_PARTIALLY_ORDERED_LITERAL_TYPE(Type) + \macro Q_DECLARE_PARTIALLY_ORDERED_LITERAL_TYPE(LeftType, RightType) + \since 6.7 + \relates <QtCompare> + + These macros are used to generate all six relational operators. + The operators represent + \l {https://en.cppreference.com/w/cpp/utility/compare/partial_ordering} + {partial ordering}. + + These macros use respective overloads of the + \l {Q_DECLARE_EQUALITY_COMPARABLE} macro to generate \c {operator==()} and + \c {operator!=()}, and also generate the four relational operators: + \c {operator<()}, \c {operator>()}, \c {operator<=()}, and \c {operator>()}. + + In C++17 mode, the mixed-type overloads also generate the reversed + operators. + + In C++20 mode, only \c {operator==()} and \c {operator<=>()} are defined. + Other operators, as well as the reversed operators for mixed-type + comparison, are synthesized by the compiler. + + The (in)equality operators are implemented in terms of a helper function + \c {comparesEqual()}. The other relational operators are implemented in + terms of a helper function \c {compareThreeWay()}. + The \c {compareThreeWay()} function \e must return an object of type + \l Qt::partial_ordering. It's the user's responsibility to declare and define + both helper functions. + + Consider the following example of a comparison operators declaration: + + \code + class MyClass { + ... + private: + friend bool comparesEqual(const MyClass &, const MyClass &) noexcept; + friend Qt::partial_ordering compareThreeWay(const MyClass &, const MyClass &) noexcept; + Q_DECLARE_PARTIALLY_ORDERED(MyClass) + }; + \endcode + + When compiled with C++17, the macro will expand into the following code: + + \code + // operator==() and operator!=() are generated from + // Q_DECLARE_EQUALITY_COMPARABLE + friend bool operator<(const MyClass &lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend bool operator>(const MyClass &lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend bool operator<=(const MyClass &lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend bool operator>=(const MyClass &lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + \endcode + + When compiled with C++20, the macro will expand into \c {operator==()} and + \c {operator<=>()}: + + \code + friend bool operator==(const MyClass &lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + friend std::partial_ordering + operator<=>(const MyClass &lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + \endcode + + The \c {*_LITERAL_TYPE} versions of the macros are used to generate + \c constexpr operators. This means that the helper \c {comparesEqual()} and + \c {compareThreeWay()} functions must also be \c constexpr. + + Consider the following example of a mixed-type \c constexpr comparison + operators declaration: + + \code + class MyClass { + ... + private: + friend constexpr bool comparesEqual(const MyClass &, int) noexcept; + friend constexpr Qt::partial_ordering compareThreeWay(const MyClass &, int) noexcept; + Q_DECLARE_PARTIALLY_ORDERED_LITERAL_TYPE(MyClass, int) + }; + \endcode + + When compiled with C++17, the macro will expand into the following code: + + \code + // operator==(), operator!=(), and their reversed versions are generated + // from Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE + friend constexpr bool operator<(const MyClass &lhs, int rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend constexpr bool operator>(const MyClass &lhs, int rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend constexpr bool operator<=(const MyClass &lhs, int rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend constexpr bool operator>=(const MyClass &lhs, int rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend constexpr bool operator<(int lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend constexpr bool operator>(int lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend constexpr bool operator<=(int lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + friend constexpr bool operator>=(int lhs, const MyClass &rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + \endcode + + When compiled with C++20, the macro will expand into \c {operator==()} and + \c {operator<=>()}: + + \code + friend constexpr bool operator==(const MyClass &lhs, int rhs) noexcept + { + // inline implementation which uses comparesEqual() + } + friend constexpr std::partial_ordering + operator<=>(const MyClass &lhs, int rhs) noexcept + { + // inline implementation which uses compareThreeWay() + } + \endcode + + \sa Q_DECLARE_EQUALITY_COMPARABLE, Q_DECLARE_WEAKLY_ORDERED, + Q_DECLARE_STRONGLY_ORDERED +*/ + +/*! + \internal + \macro Q_DECLARE_WEAKLY_ORDERED(Type) + \macro Q_DECLARE_WEAKLY_ORDERED(LeftType, RightType) + \macro Q_DECLARE_WEAKLY_ORDERED_LITERAL_TYPE(Type) + \macro Q_DECLARE_WEAKLY_ORDERED_LITERAL_TYPE(LeftType, RightType) + \since 6.7 + \relates <QtCompare> + + These macros behave similarly to the + \l {Q_DECLARE_PARTIALLY_ORDERED} overloads, but represent + \l {https://en.cppreference.com/w/cpp/utility/compare/weak_ordering} + {weak ordering}. + + The (in)equality operators are implemented in terms of a helper function + \c {comparesEqual()}. The other relational operators are implemented in + terms of a helper function \c {compareThreeWay()}. + The \c {compareThreeWay()} function \e must return an object of type + \l Qt::weak_ordering. It's the user's responsibility to declare and define both + helper functions. + + The \c {*_LITERAL_TYPE} overloads are used to generate \c constexpr + operators. This means that the helper \c {comparesEqual()} and + \c {compareThreeWay()} functions must also be \c constexpr. + + See \l {Q_DECLARE_PARTIALLY_ORDERED} for usage examples. + + \sa Q_DECLARE_PARTIALLY_ORDERED, Q_DECLARE_STRONGLY_ORDERED, + Q_DECLARE_EQUALITY_COMPARABLE +*/ + +/*! + \internal + \macro Q_DECLARE_STRONGLY_ORDERED(Type) + \macro Q_DECLARE_STRONGLY_ORDERED(LeftType, RightType) + \macro Q_DECLARE_STRONGLY_ORDERED_LITERAL_TYPE(Type) + \macro Q_DECLARE_STRONGLY_ORDERED_LITERAL_TYPE(LeftType, RightType) + \since 6.7 + \relates <QtCompare> + + These macros behave similarly to the + \l {Q_DECLARE_PARTIALLY_ORDERED} overloads, but represent + \l {https://en.cppreference.com/w/cpp/utility/compare/strong_ordering} + {strong ordering}. + + The (in)equality operators are implemented in terms of a helper function + \c {comparesEqual()}. The other relational operators are implemented in + terms of a helper function \c {compareThreeWay()}. + The \c {compareThreeWay()} function \e must return an object of type + \l Qt::strong_ordering. It's the user's responsibility to declare and define + both helper functions. + + The \c {*_LITERAL_TYPE} overloads are used to generate \c constexpr + operators. This means that the helper \c {comparesEqual()} and + \c {compareThreeWay()} functions must also be \c constexpr. + + See \l {Q_DECLARE_PARTIALLY_ORDERED} for usage examples. + + \sa Q_DECLARE_PARTIALLY_ORDERED, Q_DECLARE_WEAKLY_ORDERED, + Q_DECLARE_EQUALITY_COMPARABLE +*/ + +/*! + \internal + \macro Q_DECLARE_EQUALITY_COMPARABLE(LeftType, RightType, Attributes) + \macro Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE(LeftType, RightType, Attributes) + \macro Q_DECLARE_PARTIALLY_ORDERED(LeftType, RightType, Attributes) + \macro Q_DECLARE_PARTIALLY_ORDERED_LITERAL_TYPE(LeftType, RightType, Attributes) + \macro Q_DECLARE_WEAKLY_ORDERED(LeftType, RightType, Attributes) + \macro Q_DECLARE_WEAKLY_ORDERED_LITERAL_TYPE(LeftType, RightType, Attributes) + \macro Q_DECLARE_STRONGLY_ORDERED(LeftType, RightType, Attributes) + \macro Q_DECLARE_STRONGLY_ORDERED_LITERAL_TYPE(LeftType, RightType, Attributes) + \since 6.8 + \relates <QtCompare> + + These macros behave like their two-argument versions, but allow + specification of C++ attributes to add before every generated relational + operator. + + As an example, the \c Attributes parameter can be used in Qt to pass + the \c QT_ASCII_CAST_WARN marco (whose expansion can mark the function as + deprecated) when implementing comparison of encoding-aware string types + with C-style strings or byte arrays. +*/ + +/*! + \fn template <typename LeftInt, typename RightInt, Qt::if_integral<LeftInt> = true, Qt::if_integral<RightInt> = true> auto Qt::compareThreeWay(LeftInt lhs, RightInt rhs) + \since 6.7 + \relates <QtCompare> + \overload + + Implements three-way comparison of integral types. + + \note This function participates in overload resolution only if both + \c LeftInt and \c RightInt are built-in integral types. + + Returns \c {lhs <=> rhs}, provided \c LeftInt and \c RightInt are built-in + integral types. Unlike \c {operator<=>()}, this function template is also + available in C++17. See + \l {https://en.cppreference.com/w/cpp/language/operator_comparison#Three-way_comparison} + {cppreference} for more details. + + This function can also be used in custom \c {compareThreeWay()} functions, + when ordering members of a custom class represented by built-in types: + + \code + class MyClass { + public: + ... + private: + int value; + ... + friend Qt::strong_ordering + compareThreeWay(const MyClass &lhs, const MyClass &rhs) noexcept + { return Qt::compareThreeWay(lhs.value, rhs.value); } + Q_DECLARE_STRONGLY_ORDERED(MyClass) + }; + \endcode + + Returns an instance of \l Qt::strong_ordering that represents the relation + between \a lhs and \a rhs. +*/ + +/*! + \fn template <typename LeftFloat, typename RightFloat, Qt::if_floating_point<LeftFloat> = true, Qt::if_floating_point<RightFloat> = true> auto Qt::compareThreeWay(LeftFloat lhs, RightFloat rhs) + \since 6.7 + \relates <QtCompare> + \overload + + Implements three-way comparison of floating point types. + + \note This function participates in overload resolution only if both + \c LeftFloat and \c RightFloat are built-in floating-point types. + + Returns \c {lhs <=> rhs}, provided \c LeftFloat and \c RightFloat are + built-in floating-point types. Unlike \c {operator<=>()}, this function + template is also available in C++17. See + \l {https://en.cppreference.com/w/cpp/language/operator_comparison#Three-way_comparison} + {cppreference} for more details. + + This function can also be used in custom \c {compareThreeWay()} functions, + when ordering members of a custom class represented by built-in types: + + \code + class MyClass { + public: + ... + private: + double value; + ... + friend Qt::partial_ordering + compareThreeWay(const MyClass &lhs, const MyClass &rhs) noexcept + { return Qt::compareThreeWay(lhs.value, rhs.value); } + Q_DECLARE_PARTIALLY_ORDERED(MyClass) + }; + \endcode + + Returns an instance of \l Qt::partial_ordering that represents the relation + between \a lhs and \a rhs. If \a lhs or \a rhs is not a number (NaN), + \l Qt::partial_ordering::unordered is returned. +*/ + +/*! + \fn template <typename IntType, typename FloatType, Qt::if_integral<IntType> = true, Qt::if_floating_point<FloatType> = true> auto Qt::compareThreeWay(IntType lhs, FloatType rhs) + \since 6.7 + \relates <QtCompare> + \overload + + Implements three-way comparison of integral and floating point types. + + \note This function participates in overload resolution only if \c IntType + is a built-in integral type and \c FloatType is a built-in floating-point + type. + + This function converts \a lhs to \c FloatType and calls the overload for + floating-point types. + + Returns an instance of \l Qt::partial_ordering that represents the relation + between \a lhs and \a rhs. If \a rhs is not a number (NaN), + \l Qt::partial_ordering::unordered is returned. +*/ + +/*! + \fn template <typename FloatType, typename IntType, Qt::if_floating_point<FloatType> = true, Qt::if_integral<IntType> = true> auto Qt::compareThreeWay(FloatType lhs, IntType rhs) + \since 6.7 + \relates <QtCompare> + \overload + + Implements three-way comparison of floating point and integral types. + + \note This function participates in overload resolution only if \c FloatType + is a built-in floating-point type and \c IntType is a built-in integral + type. + + This function converts \a rhs to \c FloatType and calls the overload for + floating-point types. + + Returns an instance of \l Qt::partial_ordering that represents the relation + between \a lhs and \a rhs. If \a lhs is not a number (NaN), + \l Qt::partial_ordering::unordered is returned. +*/ + +/*! + \fn template <typename LeftType, typename RightType, Qt::if_compatible_pointers<LeftType, RightType> = true> Qt::compareThreeWay(const LeftType *lhs, const RightType *rhs) + \since 6.7 + \relates <QtCompare> + \overload + + Implements three-way comparison of pointers. + + \note This function participates in overload resolution if \c LeftType and + \c RightType are the same type, or base and derived types. It is also used + to compare any pointer to \c {std::nullptr_t}. + + Returns an instance of \l Qt::strong_ordering that represents the relation + between \a lhs and \a rhs. +*/ + +/*! + \fn template <class Enum, Qt::if_enum<Enum> = true> Qt::compareThreeWay(Enum lhs, Enum rhs) + \since 6.7 + \relates <QtCompare> + \overload + + Implements three-way comparison of enum types. + + \note This function participates in overload resolution only if \c Enum + is an enum type. + + This function converts \c Enum to its underlying type and calls the + overload for integral types. + + Returns an instance of \l Qt::strong_ordering that represents the relation + 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 |