// 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 GFDL-1.3-no-invariants-only /*! \page comparison-types.html overview \title Comparison types overview \keyword three-way comparison \inmodule QtCore \sa QStrongOrdering, QWeakOrdering, QPartialOrdering \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 QStrongOrdering \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 QWeakOrdering \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 QPartialOrdering \li no \li no \li floating-point types, QOperatingSystemVersion, QVariant \endtable The strongest comparison type, QStrongOrdering, 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 QStrongOrdering::Equal. Both values are indistinguishable and all deterministic operations performed on these values would yield identical results. QWeakOrdering 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 QWeakOrdering::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. QPartialOrdering represents, as the name implies, a partial ordering. It allows for the possibility that two values may not be comparable, resulting in an \l {QPartialOrdering::}{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. */ /*! \class QStrongOrdering \inmodule QtCore \brief QStrongOrdering represents a comparison where equivalent values are indistinguishable. \sa QWeakOrdering, QPartialOrdering, {Comparison types overview} \since 6.6 A value of type QStrongOrdering is typically returned from a three-way comparison function. Such a function compares two objects and establishes that the two objects are in a strict ordering relationship; that is, the function establishes a well-defined total order. The possible values of type QStrongOrdering are fully represented by the following four symbolic constants: \list \li \c Less represents that the left operand is less than the right; \li \c Equal represents that the left operand is equivalent to the right; \li \c Equivalent is an alias for \c Equal; \li \c Greater represents that the left operand is greater than the right. \endlist QStrongOrdering 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: QStrongOrdering compare(T lhs, T rhs); // defined out-of-line ~~~ QStrongOrdering 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 QStrongOrdering::operator QPartialOrdering() const Converts this QStrongOrdering value to a QPartialOrdering object using the following rules: \list \li \l Less converts to \l {QPartialOrdering::Less}. \li \l Equivalent converts to \l {QPartialOrdering::Equivalent}. \li \l Equal converts to \l {QPartialOrdering::Equivalent}. \li \l Greater converts to \l {QPartialOrdering::Greater}. \endlist */ /*! \fn QStrongOrdering::operator QWeakOrdering() const Converts this QStrongOrdering value to a QWeakOrdering object using the following rules: \list \li \l Less converts to \l {QWeakOrdering::Less}. \li \l Equivalent converts to \l {QWeakOrdering::Equivalent}. \li \l Equal converts to \l {QWeakOrdering::Equivalent}. \li \l Greater converts to \l {QWeakOrdering::Greater}. \endlist */ /*! \fn QStrongOrdering::QStrongOrdering(std::strong_ordering stdorder) Constructs a QStrongOrdering 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 QStrongOrdering::operator std::strong_ordering() const Converts this QStrongOrdering 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 QStrongOrdering::operator==(QStrongOrdering lhs, QStrongOrdering rhs) Returns true if \a lhs and \a rhs represent the same result; otherwise, returns false. */ /*! \fn bool QStrongOrdering::operator!=(QStrongOrdering lhs, QStrongOrdering rhs) Returns true if \a lhs and \a rhs represent different results; otherwise, returns true. */ /*! \internal \relates QStrongOrdering \fn bool operator==(QStrongOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator!=(QStrongOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator< (QStrongOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator<=(QStrongOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator> (QStrongOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator>=(QStrongOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator==(QtPrivate::CompareAgainstLiteralZero, QStrongOrdering rhs) \fn bool operator!=(QtPrivate::CompareAgainstLiteralZero, QStrongOrdering rhs) \fn bool operator< (QtPrivate::CompareAgainstLiteralZero, QStrongOrdering rhs) \fn bool operator<=(QtPrivate::CompareAgainstLiteralZero, QStrongOrdering rhs) \fn bool operator> (QtPrivate::CompareAgainstLiteralZero, QStrongOrdering rhs) \fn bool operator>=(QtPrivate::CompareAgainstLiteralZero, QStrongOrdering rhs) */ /*! \variable QStrongOrdering::Less Represents the result of a comparison where the left operand is less than the right operand. */ /*! \variable QStrongOrdering::Equivalent Represents the result of a comparison where the left operand is equal to the right operand. Same as \l {QStrongOrdering::Equal}. */ /*! \variable QStrongOrdering::Equal Represents the result of a comparison where the left operand is equal to the right operand. Same as \l {QStrongOrdering::Equivalent}. */ /*! \variable QStrongOrdering::Greater Represents the result of a comparison where the left operand is greater than the right operand. */ /*! \class QWeakOrdering \inmodule QtCore \brief QWeakOrdering represents a comparison where equivalent values are still distinguishable. \sa QStrongOrdering, QPartialOrdering, {Comparison types overview} \since 6.6 A value of type QWeakOrdering is typically returned from a three-way comparison function. Such a function compares two objects and establishes the order of the elements relative to each other. The possible values of type QWeakOrdering are fully represented by the following three symbolic constants: \list \li \c Less represents that the left operand is less than the right; \li \c Equivalent represents that the left operand is equivalent to the right; \li \c Greater represents that the left operand is greater than the right, \endlist QWeakOrdering 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: QWeakOrdering compare(T lhs, T rhs); // defined out-of-line ~~~ QWeakOrdering 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 QWeakOrdering::operator QPartialOrdering() const Converts this QWeakOrdering value to a QPartialOrdering object using the following rules: \list \li \l Less converts to \l {QPartialOrdering::Less}. \li \l Equivalent converts to \l {QPartialOrdering::Equivalent}. \li \l Greater converts to \l {QPartialOrdering::Greater}. \endlist */ /*! \fn QWeakOrdering::QWeakOrdering(std::weak_ordering stdorder) Constructs a QWeakOrdering 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 QWeakOrdering::operator std::weak_ordering() const Converts this QWeakOrdering 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 QWeakOrdering::operator==(QWeakOrdering lhs, QWeakOrdering rhs) Return true if \a lhs and \a rhs represent the same result; otherwise, returns false. */ /*! \fn bool QWeakOrdering::operator!=(QWeakOrdering lhs, QWeakOrdering rhs) Return true if \a lhs and \a rhs represent different results; otherwise, returns true. */ /*! \internal \relates QWeakOrdering \fn bool operator==(QWeakOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator!=(QWeakOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator< (QWeakOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator<=(QWeakOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator> (QWeakOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator>=(QWeakOrdering lhs, QtPrivate::CompareAgainstLiteralZero) \fn bool operator==(QtPrivate::CompareAgainstLiteralZero, QWeakOrdering rhs) \fn bool operator!=(QtPrivate::CompareAgainstLiteralZero, QWeakOrdering rhs) \fn bool operator< (QtPrivate::CompareAgainstLiteralZero, QWeakOrdering rhs) \fn bool operator<=(QtPrivate::CompareAgainstLiteralZero, QWeakOrdering rhs) \fn bool operator> (QtPrivate::CompareAgainstLiteralZero, QWeakOrdering rhs) \fn bool operator>=(QtPrivate::CompareAgainstLiteralZero, QWeakOrdering rhs) */ /*! \variable QWeakOrdering::Less Represents the result of a comparison where the left operand is less than the right operand. */ /*! \variable QWeakOrdering::Equivalent Represents the result of a comparison where the left operand is equivalent to the right operand. */ /*! \variable QWeakOrdering::Greater Represents the result of a comparison where the left operand is greater than the right operand. */ /*! \class QPartialOrdering \inmodule QtCore \brief QPartialOrdering represents the result of a comparison that allows for unordered results. \sa QStrongOrdering, QWeakOrdering, {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, and it may either establish that the two objects are ordered relative to each other, or that they are not ordered. The QPartialOrdering value returned from the comparison function represents one of those possibilities. The possible values of type QPartialOrdering are, in fact, fully represented by the following four symbolic constants: \list \li \c Less represents that the left operand is less than the right; \li \c Equivalent represents that left operand is equivalent to the right; \li \c Greater represents that the left operand is greater than the right; \li \c Unordered represents that the left operand is \e {not ordered} with respect to the right operand. \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 A QPartialOrdering value which represents an unordered result will always return false when compared against literal 0. */ /*! \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) */ /*! \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 left operand is equivalent to the right operand. */ /*! \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 the left operand is not ordered with respect to the right operand. */