\title Comparison types overview \keyword three-way comparison \inmodule QtCore

See also: 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 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 {zero literal}. To use these comparison types, you need to include the <QtCompare> header. These comparison types are categorized based on their order, which is a mathematical concept used to describe the arrangement or ranking of elements. The following categories are provided:

\table 100 % \header

C++ type
Qt type
strict
total
Example \row
\l {https://en.cppreference.com/w/cpp/utility/compare/strong_ordering} {std::strong_ordering}
Qt::strong_ordering
yes
yes
integral types, case-sensitive strings, QDate, QTime \row
\l {https://en.cppreference.com/w/cpp/utility/compare/weak_ordering} {std::weak_ordering}
Qt::weak_ordering
no
yes
case-insensitive strings, unordered associative containers, QDateTime \row
\l {https://en.cppreference.com/w/cpp/utility/compare/partial_ordering} {std::partial_ordering}
Qt::partial_ordering
no
no
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 "Qt" and "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 "Qt" and "qt" both hold the same letters but with different representations. This comparison would result in \l Qt::weak_ordering::equivalent, but not actually 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 time() and sometimes 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.