// Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo // 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 #endif QT_BEGIN_NAMESPACE #ifdef __cpp_lib_three_way_comparison #ifdef __cpp_lib_bit_cast #define CHECK(type, flag) \ static_assert(std::bit_cast(std:: type ## _ordering:: flag) \ == Qt:: type ## _ordering :: flag); \ static_assert(std::bit_cast(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 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 \inmodule QtCore \title Classes and helpers for defining comparison operators \keyword qtcompare \brief The 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 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 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 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 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 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 = true, Qt::if_integral = true> auto Qt::compareThreeWay(LeftInt lhs, RightInt rhs) \since 6.7 \relates \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 = true, Qt::if_floating_point = true> auto Qt::compareThreeWay(LeftFloat lhs, RightFloat rhs) \since 6.7 \relates \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 = true, Qt::if_floating_point = true> auto Qt::compareThreeWay(IntType lhs, FloatType rhs) \since 6.7 \relates \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 = true, Qt::if_integral = true> auto Qt::compareThreeWay(FloatType lhs, IntType rhs) \since 6.7 \relates \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 = true> Qt::compareThreeWay(const LeftType *lhs, const RightType *rhs) \since 6.7 \relates \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 = true> Qt::compareThreeWay(Enum lhs, Enum rhs) \since 6.7 \relates \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 qCompareThreeWay(const LeftType &lhs, const RightType &rhs) \since 6.7 \relates 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