Comparison types overview
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 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:
| C++ type | Qt type | strict | total | Example |
|---|---|---|---|---|
| std::strong_ordering | Qt::strong_ordering | yes | yes | integral types, case-sensitive strings, QDate, QTime |
| std::weak_ordering | Qt::weak_ordering | no | yes | case-insensitive strings, unordered associative containers, QDateTime |
| std::partial_ordering | Qt::partial_ordering | no | no | floating-point types, QOperatingSystemVersion, QVariant |
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 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 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 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.
See also Qt::strong_ordering, Qt::weak_ordering, and Qt::partial_ordering.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
