<QtCompare> - Classes and helpers for defining comparison operators | Qt Core | Qt 6.11.0
Description: The <QtCompare> header file defines <@type>Qt</@type><@op>::</@op><@op>*</@op>_ordering types and helper macros for defining comparison operators.

- Qt 6.11
- Qt Core
- <QtCompare> - Classes and helpers for defining comparison operators
- Qt 6.11.0 Reference Documentation

# <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>`

- Deprecated members

## Functions

`(since 6.7)` Qt::strong_ordering | compareThreeWay(Enum lhs, Enum rhs)
`(since 6.7)` auto | compareThreeWay(FloatType lhs, IntType rhs)
`(since 6.7)` auto | compareThreeWay(IntType lhs, FloatType rhs)
`(since 6.7)` auto | compareThreeWay(LeftFloat lhs, RightFloat rhs)
`(since 6.7)` auto | compareThreeWay(LeftInt lhs, RightInt rhs)
`(since 6.8)` Qt::strong_ordering | compareThreeWay(Qt::totally_ordered_wrapper<T *> lhs, Qt::totally_ordered_wrapper<U *> rhs)
`(since 6.8)` Qt::strong_ordering | compareThreeWay(Qt::totally_ordered_wrapper<T *> lhs, U *rhs)
`(since 6.8)` Qt::strong_ordering | compareThreeWay(Qt::totally_ordered_wrapper<T *> lhs, std::nullptr_t rhs)
`(since 6.8)` Qt::strong_ordering | compareThreeWay(U *lhs, Qt::totally_ordered_wrapper<T *> rhs)
`(since 6.8)` Qt::strong_ordering | compareThreeWay(std::nullptr_t lhs, Qt::totally_ordered_wrapper<T *> 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 Enum, Qt::if_enum<Enum> = true> Qt::strong_ordering compareThreeWay(Enum lhs, Enum rhs)

Implements three-way comparison of enum types.

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.

#### Constraints

Participates in overload resolution only if `Enum` is an enum type.

This is an overloaded function.

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<IntType> = true > auto compareThreeWay(FloatType lhs, IntType rhs)

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

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.

#### Constraints

Participates in overload resolution only if `FloatType` is a built-in floating-point type and `IntType` is a built-in integral type.

This is an overloaded function.

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<FloatType> = true > auto compareThreeWay(IntType lhs, FloatType rhs)

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

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.

#### Constraints

Participates in overload resolution only if `IntType` is a built-in integral type and `FloatType` is a built-in floating-point type.

This is an overloaded function.

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<RightFloat> = true > auto compareThreeWay(LeftFloat lhs, RightFloat rhs)

Implements three-way comparison of 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.

#### Constraints

Participates in overload resolution only if both `LeftFloat` and `RightFloat` are built-in floating-point types.

This is an overloaded function.

This function was introduced in Qt 6.7.

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

Implements three-way comparison of 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.

#### Constraints

Participates in overload resolution only if both `LeftInt` and `RightInt` are built-in integral types.

This is an overloaded function.

This function was introduced in Qt 6.7.

### `[constexpr noexcept, since 6.8]` template < typename T, typename U, Qt::if_compatible_pointers<T, U> = true > Qt::strong_ordering compareThreeWay(Qt::totally_ordered_wrapper<T *> lhs, Qt::totally_ordered_wrapper<U *> rhs)

Implements three-way comparison of pointers that are wrapped into Qt::totally_ordered_wrapper. Uses strict total order over pointers when doing the comparison.

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

#### Constraints

Participates in overload resolution only if `T` and `U` are the same type, or base and derived types.

This is an overloaded function.

This function was introduced in Qt 6.8.

### `[constexpr noexcept, since 6.8]` template < typename T, typename U, Qt::if_compatible_pointers<T, U> = true > Qt::strong_ordering compareThreeWay(Qt::totally_ordered_wrapper<T *> lhs, U *rhs)

Implements three-way comparison of a pointer wrapped into Qt::totally_ordered_wrapper with a normal pointer. Uses strict total order over pointers when doing the comparison.

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

#### Constraints

Participates in overload resolution only if `T` and `U` are the same type, or base and derived types.

This is an overloaded function.

This function was introduced in Qt 6.8.

### `[constexpr noexcept, since 6.8]` template <typename T> Qt::strong_ordering compareThreeWay(Qt::totally_ordered_wrapper<T *> lhs, std::nullptr_t rhs)

Implements three-way comparison of a pointer wrapped into Qt::totally_ordered_wrapper with `std::nullptr_t`.

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

This is an overloaded function.

This function was introduced in Qt 6.8.

### `[constexpr noexcept, since 6.8]` template < typename T, typename U, Qt::if_compatible_pointers<T, U> = true > Qt::strong_ordering compareThreeWay(U *lhs, Qt::totally_ordered_wrapper<T *> rhs)

Implements three-way comparison of a normal pointer with a pointer wrapped into Qt::totally_ordered_wrapper. Uses strict total order over pointers when doing the comparison.

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

#### Constraints

Participates in overload resolution only if `T` and `U` are the same type, or base and derived types.

This is an overloaded function.

This function was introduced in Qt 6.8.

### `[constexpr noexcept, since 6.8]` template <typename T> Qt::strong_ordering compareThreeWay(std::nullptr_t lhs, Qt::totally_ordered_wrapper<T *> rhs)

Implements three-way comparison of `std::nullptr_t` with a pointer wrapped into Qt::totally_ordered_wrapper.

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

This is an overloaded function.

This function was introduced in Qt 6.8.

### `[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.