// 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 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 <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 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.
*/