<QtCompare> - Classes and helpers for defining comparison operators

The <QtCompare> header file defines Qt::*_ordering types and helper macros for defining comparison operators. More...

Header: #include <QtCompare>

Functions

(since 6.7) Qt::strong_ordering compareThreeWay(LeftInt lhs, RightInt rhs)
(since 6.7) Qt::partial_ordering compareThreeWay(LeftFloat lhs, RightFloat rhs)
(since 6.7) Qt::partial_ordering compareThreeWay(IntType lhs, FloatType rhs)
(since 6.7) Qt::partial_ordering compareThreeWay(FloatType lhs, IntType rhs)
(since 6.7) Qt::strong_ordering compareThreeWay(const LeftType *lhs, const RightType *rhs)
(since 6.7) Qt::strong_ordering compareThreeWay(Enum lhs, Enum rhs)
(since 6.7) auto qCompareThreeWay(const LeftType &lhs, const RightType &rhs)

Detailed Description

This header introduces the Qt::partial_ordering, Qt::weak_ordering, and Qt::strong_ordering types, which are Qt's C++17 backports of std::*_ordering types.

This header also contains functions for implementing three-way comparison in C++17.

The Qt::compareThreeWay() function overloads provide three-way comparison for built-in C++ types.

The qCompareThreeWay() template serves as a generic three-way comparison implementation. It relies on Qt::compareThreeWay() and free compareThreeWay() functions in its implementation.

Function Documentation

[constexpr noexcept, since 6.7] template <typename LeftInt, typename RightInt, Qt::if_integral<LeftInt> = true, Qt::if_integral = true> Qt::strong_ordering compareThreeWay(LeftInt lhs, RightInt rhs)

This is an overloaded function.

Implements three-way comparison of integral types.

Note: This function participates in overload resolution only if both LeftInt and RightInt are built-in integral types.

Returns lhs <=> rhs, provided LeftInt and RightInt are built-in integral types. Unlike operator<=>(), this function template is also available in C++17. See cppreference for more details.

This function can also be used in custom compareThreeWay() functions, when ordering members of a custom class represented by built-in types:

 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)
 };

Returns an instance of Qt::strong_ordering that represents the relation between lhs and rhs.

This function was introduced in Qt 6.7.

[constexpr noexcept, since 6.7] template <typename LeftFloat, typename RightFloat, Qt::if_floating_point<LeftFloat> = true, Qt::if_floating_point = true> Qt::partial_ordering compareThreeWay(LeftFloat lhs, RightFloat rhs)

This is an overloaded function.

Implements three-way comparison of floating point types.

Note: This function participates in overload resolution only if both LeftFloat and RightFloat are built-in floating-point types.

Returns lhs <=> rhs, provided LeftFloat and RightFloat are built-in floating-point types. Unlike operator<=>(), this function template is also available in C++17. See cppreference for more details.

This function can also be used in custom compareThreeWay() functions, when ordering members of a custom class represented by built-in types:

 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)
 };

Returns an instance of Qt::partial_ordering that represents the relation between lhs and rhs. If lhs or rhs is not a number (NaN), Qt::partial_ordering::unordered is returned.

This function was introduced in Qt 6.7.

[constexpr noexcept, since 6.7] template <typename IntType, typename FloatType, Qt::if_integral<IntType> = true, Qt::if_floating_point = true> Qt::partial_ordering compareThreeWay(IntType lhs, FloatType rhs)

This is an overloaded function.

Implements three-way comparison of integral and floating point types.

Note: This function participates in overload resolution only if IntType is a built-in integral type and FloatType is a built-in floating-point type.

This function converts lhs to FloatType and calls the overload for floating-point types.

Returns an instance of Qt::partial_ordering that represents the relation between lhs and rhs. If rhs is not a number (NaN), Qt::partial_ordering::unordered is returned.

This function was introduced in Qt 6.7.

[constexpr noexcept, since 6.7] template <typename FloatType, typename IntType, Qt::if_floating_point<FloatType> = true, Qt::if_integral = true> Qt::partial_ordering compareThreeWay(FloatType lhs, IntType rhs)

This is an overloaded function.

Implements three-way comparison of floating point and integral types.

Note: This function participates in overload resolution only if FloatType is a built-in floating-point type and IntType is a built-in integral type.

This function converts rhs to FloatType and calls the overload for floating-point types.

Returns an instance of Qt::partial_ordering that represents the relation between lhs and rhs. If lhs is not a number (NaN), Qt::partial_ordering::unordered is returned.

This function was introduced in Qt 6.7.

[constexpr noexcept, since 6.7] template <typename LeftType, typename RightType, Qt::if_compatible_pointers<LeftType, RightType> = true> Qt::strong_ordering compareThreeWay(const LeftType *lhs, const RightType *rhs)

This is an overloaded function.

Implements three-way comparison of pointers.

Note: This function participates in overload resolution if LeftType and RightType are the same type, or base and derived types. It is also used to compare any pointer to std::nullptr_t.

Returns an instance of Qt::strong_ordering that represents the relation between lhs and rhs.

This function was introduced in Qt 6.7.

[constexpr noexcept, since 6.7] template <typename Enum, Qt::if_enum<Enum> = true> Qt::strong_ordering compareThreeWay(Enum lhs, Enum rhs)

This is an overloaded function.

Implements three-way comparison of enum types.

Note: This function participates in overload resolution only if Enum is an enum type.

This function converts Enum to its underlying type and calls the overload for integral types.

Returns an instance of Qt::strong_ordering that represents the relation between lhs and rhs.

This function was introduced in Qt 6.7.

[since 6.7] template <typename LeftType, typename RightType> auto qCompareThreeWay(const LeftType &lhs, const RightType &rhs)

Performs the three-way comparison on lhs and 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 LeftType and RightType.

Note: This function template is only available when compareThreeWay() is implemented for the (LeftType, RightType) pair or the reversed (RightType, LeftType) pair.

This method is equivalent to

 using Qt::compareThreeWay;
 return compareThreeWay(lhs, rhs);

where Qt::compareThreeWay is the Qt implementation of three-way comparison for built-in types.

The free compareThreeWay functions should provide three-way comparison for custom types. The functions should return one of the Qt ordering types.

Qt provides compareThreeWay implementation for some of its types.

Note: Do not re-implement 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 LeftType and RightType.

If you know the types, use

  • Qt::compareThreeWay for built-in types
  • compareThreeWay for custom types

Use operator<=>() directly in code that will only be compiled with C++20 or later.

This function was introduced in Qt 6.7.

See also Qt::partial_ordering, Qt::weak_ordering, and Qt::strong_ordering.