Source code
Revision control
Copy as Markdown
// 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 LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
#include "qcompare.h"
#ifdef __cpp_lib_bit_cast
#include <bit>
#endif
QT_BEGIN_NAMESPACE
#ifdef __cpp_lib_three_way_comparison
#ifdef __cpp_lib_bit_cast
#define CHECK(type, flag) \
static_assert(std::bit_cast<Qt:: type ## _ordering>(std:: type ## _ordering:: flag) \
== Qt:: type ## _ordering :: flag); \
static_assert(std::bit_cast<std:: type ## _ordering>(Qt:: type ## _ordering:: flag) \
== std:: type ## _ordering :: flag) \
/* end */
#if !defined(Q_STL_LIBSTDCPP) || QT_VERSION >= QT_VERSION_CHECK(7, 0, 0)
CHECK(partial, unordered);
#endif
CHECK(partial, less);
CHECK(partial, greater);
CHECK(partial, equivalent);
CHECK(weak, less);
CHECK(weak, greater);
CHECK(weak, equivalent);
CHECK(strong, less);
CHECK(strong, greater);
CHECK(strong, equal);
CHECK(strong, equivalent);
#undef CHECK
#endif // __cpp_lib_bit_cast
#endif //__cpp_lib_three_way_comparison
/*!
\page comparison-types.html overview
\title Comparison types overview
\keyword three-way comparison
\inmodule QtCore
\sa 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 \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
{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
{std::strong_ordering}
\li Qt::strong_ordering
\li yes
\li yes
\li integral types, case-sensitive strings, QDate, QTime
\row
{std::weak_ordering}
\li Qt::weak_ordering
\li no
\li yes
\li case-insensitive strings, unordered associative containers, QDateTime
\row
{std::partial_ordering}
\li Qt::partial_ordering
\li no
\li no
\li 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 \c "Qt" and \c "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 \c "Qt" and \c "qt" both hold the same
letters but with different representations. This comparison would
result in \l Qt::weak_ordering::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.
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.
*/
/*!
\headerfile <QtCompare>
\inmodule QtCore
\title Classes and helpers for defining comparison operators
\keyword qtcompare
\brief The <QtCompare> header file defines \c {Qt::*_ordering} types and helper
macros for defining comparison operators.
This header introduces the \l Qt::partial_ordering, \l Qt::weak_ordering, and
\l Qt::strong_ordering types, which are Qt's C++17 backports of
\c {std::*_ordering} types.
This header also contains functions for implementing three-way comparison
in C++17.
The \c {Qt::compareThreeWay()} function overloads provide three-way
comparison for built-in C++ types.
The \l qCompareThreeWay() template serves as a generic three-way comparison
implementation. It relies on \c {Qt::compareThreeWay()} and free
\c {compareThreeWay()} functions in its implementation.
*/
/*!
\class Qt::strong_ordering
\inmodule QtCore
\inheaderfile QtCompare
\brief Qt::strong_ordering represents a comparison where equivalent values are
indistinguishable.
\sa Qt::weak_ordering, Qt::partial_ordering, {Comparison types overview}
\since 6.7
A value of type Qt::strong_ordering is typically returned from a three-way
comparison function. Such a function compares two objects and establishes
how they are ordered. It uses this return type to indicate that the ordering
is strict; that is, the function establishes a well-defined total order.
Qt::strong_ordering has four values, represented by the following symbolic
constants:
\list
\li \l less represents that the left operand is less than the right;
\li \l equal represents that the left operand is equivalent to the right;
\li \l equivalent is an alias for \c equal;
\li \l greater represents that the left operand is greater than the right.
\endlist
Qt::strong_ordering 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:
Qt::strong_ordering compare(T lhs, T rhs); // defined out-of-line
~~~
Qt::strong_ordering 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 Qt::strong_ordering::operator Qt::partial_ordering() const
Converts this Qt::strong_ordering value to a Qt::partial_ordering object using the
following rules:
\list
\li \l less converts to \l {Qt::partial_ordering::less}.
\li \l equivalent converts to \l {Qt::partial_ordering::equivalent}.
\li \l equal converts to \l {Qt::partial_ordering::equivalent}.
\li \l greater converts to \l {Qt::partial_ordering::greater}.
\endlist
*/
/*!
\fn Qt::strong_ordering::operator Qt::weak_ordering() const
Converts this Qt::strong_ordering value to a Qt::weak_ordering object using the
following rules:
\list
\li \l less converts to \l {Qt::weak_ordering::less}.
\li \l equivalent converts to \l {Qt::weak_ordering::equivalent}.
\li \l equal converts to \l {Qt::weak_ordering::equivalent}.
\li \l greater converts to \l {Qt::weak_ordering::greater}.
\endlist
*/
/*!
\fn Qt::strong_ordering::strong_ordering(std::strong_ordering stdorder)
Constructs a Qt::strong_ordering 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 Qt::strong_ordering::operator std::strong_ordering() const
\target qt-strong_ordering-operator-std-strong_ordering
Converts this Qt::strong_ordering 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 Qt::strong_ordering::operator==(Qt::strong_ordering lhs, Qt::strong_ordering rhs)
Returns true if \a lhs and \a rhs represent the same result;
otherwise, returns false.
*/
/*!
\fn bool Qt::strong_ordering::operator!=(Qt::strong_ordering lhs, Qt::strong_ordering rhs)
Returns true if \a lhs and \a rhs represent different results;
otherwise, returns true.
*/
/*!
\internal
\relates Qt::strong_ordering
\fn bool operator==(Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator!=(Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator< (Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator<=(Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator> (Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator>=(Qt::strong_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator==(QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs)
\fn bool operator!=(QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs)
\fn bool operator< (QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs)
\fn bool operator<=(QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs)
\fn bool operator> (QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs)
\fn bool operator>=(QtPrivate::CompareAgainstLiteralZero, Qt::strong_ordering rhs)
*/
/*!
\fn Qt::strong_ordering::is_eq (Qt::strong_ordering o)
\fn Qt::strong_ordering::is_neq (Qt::strong_ordering o)
\fn Qt::strong_ordering::is_lt (Qt::strong_ordering o)
\fn Qt::strong_ordering::is_lteq(Qt::strong_ordering o)
\fn Qt::strong_ordering::is_gt (Qt::strong_ordering o)
\fn Qt::strong_ordering::is_gteq(Qt::strong_ordering o)
//! [is_eq_table]
Converts \a o into the result of one of the six relational operators:
\table
\header \li Function \li Operation
\row \li \c{is_eq} \li \a o \c{== 0}
\row \li \c{is_neq} \li \a o \c{!= 0}
\row \li \c{is_lt} \li \a o \c{< 0}
\row \li \c{is_lteq} \li \a o \c{<= 0}
\row \li \c{is_gt} \li \a o \c{> 0}
\row \li \c{is_gteq} \li \a o \c{>= 0}
\endtable
//! [is_eq_table]
These functions are provided for compatibility with \c{std::strong_ordering}.
*/
/*!
\variable Qt::strong_ordering::less
Represents the result of a comparison where the left operand is less
than the right operand.
*/
/*!
\variable Qt::strong_ordering::equivalent
Represents the result of a comparison where the left operand is equal
to the right operand. Same as \l {Qt::strong_ordering::equal}.
*/
/*!
\variable Qt::strong_ordering::equal
Represents the result of a comparison where the left operand is equal
to the right operand. Same as \l {Qt::strong_ordering::equivalent}.
*/
/*!
\variable Qt::strong_ordering::greater
Represents the result of a comparison where the left operand is greater
than the right operand.
*/
/*!
\class Qt::weak_ordering
\inmodule QtCore
\inheaderfile QtCompare
\brief Qt::weak_ordering represents a comparison where equivalent values are
still distinguishable.
\sa Qt::strong_ordering, Qt::partial_ordering, {Comparison types overview}
\since 6.7
A value of type Qt::weak_ordering is typically returned from a three-way
comparison function. Such a function compares two objects and establishes
how they are ordered. It uses this return type to indicate that the ordering
is weak; that is, equivalent values may be distinguishable.
Qt::weak_ordering has three values, represented by the following symbolic
constants:
\list
\li \l less represents that the left operand is less than the right;
\li \l equivalent represents that the left operand is equivalent to the
right;
\li \l greater represents that the left operand is greater than the right,
\endlist
Qt::weak_ordering 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:
Qt::weak_ordering compare(T lhs, T rhs); // defined out-of-line
~~~
Qt::weak_ordering 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 Qt::weak_ordering::operator Qt::partial_ordering() const
Converts this Qt::weak_ordering value to a Qt::partial_ordering object using the
following rules:
\list
\li \l less converts to \l {Qt::partial_ordering::less}.
\li \l equivalent converts to \l {Qt::partial_ordering::equivalent}.
\li \l greater converts to \l {Qt::partial_ordering::greater}.
\endlist
*/
/*!
\fn Qt::weak_ordering::weak_ordering(std::weak_ordering stdorder)
Constructs a Qt::weak_ordering 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 Qt::weak_ordering::operator std::weak_ordering() const
\target qt-weak_ordering-operator-std-weak_ordering
Converts this Qt::weak_ordering 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 Qt::weak_ordering::operator==(Qt::weak_ordering lhs, Qt::weak_ordering rhs)
Return true if \a lhs and \a rhs represent the same result;
otherwise, returns false.
*/
/*!
\fn bool Qt::weak_ordering::operator!=(Qt::weak_ordering lhs, Qt::weak_ordering rhs)
Return true if \a lhs and \a rhs represent different results;
otherwise, returns true.
*/
/*!
\internal
\relates Qt::weak_ordering
\fn bool operator==(Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator!=(Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator< (Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator<=(Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator> (Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator>=(Qt::weak_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator==(QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs)
\fn bool operator!=(QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs)
\fn bool operator< (QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs)
\fn bool operator<=(QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs)
\fn bool operator> (QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs)
\fn bool operator>=(QtPrivate::CompareAgainstLiteralZero, Qt::weak_ordering rhs)
*/
/*!
\fn Qt::weak_ordering::is_eq (Qt::weak_ordering o)
\fn Qt::weak_ordering::is_neq (Qt::weak_ordering o)
\fn Qt::weak_ordering::is_lt (Qt::weak_ordering o)
\fn Qt::weak_ordering::is_lteq(Qt::weak_ordering o)
\fn Qt::weak_ordering::is_gt (Qt::weak_ordering o)
\fn Qt::weak_ordering::is_gteq(Qt::weak_ordering o)
\include qcompare.cpp is_eq_table
These functions are provided for compatibility with \c{std::weak_ordering}.
*/
/*!
\variable Qt::weak_ordering::less
Represents the result of a comparison where the left operand is less than
the right operand.
*/
/*!
\variable Qt::weak_ordering::equivalent
Represents the result of a comparison where the left operand is equivalent
to the right operand.
*/
/*!
\variable Qt::weak_ordering::greater
Represents the result of a comparison where the left operand is greater
than the right operand.
*/
/*!
\class Qt::partial_ordering
\inmodule QtCore
\inheaderfile QtCompare
\brief Qt::partial_ordering represents the result of a comparison that allows
for unordered results.
\sa Qt::strong_ordering, Qt::weak_ordering, {Comparison types overview}
\since 6.7
A value of type Qt::partial_ordering is typically returned from a
three-way comparison function. Such a function compares two objects,
establishing whether they are ordered and, if so, their ordering. It uses
this return type to indicate that the ordering is partial; that is, not all
pairs of values are ordered.
Qt::partial_ordering has four values, represented by the following symbolic
constants:
\list
\li \l less represents that the left operand is less than the right;
\li \l equivalent represents that the two operands are equivalent;
\li \l greater represents that the left operand is greater than the right;
\li \l unordered represents that the two operands are \e {not ordered}.
\endlist
Qt::partial_ordering 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:
Qt::partial_ordering compare(T lhs, T rhs); // defined out-of-line
~~~
Qt::partial_ordering 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
Comparing Qt::partial_ordering::unordered against literal 0 always returns
a \c false result.
*/
/*!
\fn Qt::partial_ordering::partial_ordering(std::partial_ordering stdorder)
Constructs a Qt::partial_ordering 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 Qt::partial_ordering::operator std::partial_ordering() const
\target qt-partial_ordering-operator-std-partial_ordering
Converts this Qt::partial_ordering 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 Qt::partial_ordering::operator==(Qt::partial_ordering lhs, Qt::partial_ordering rhs)
Return true if \a lhs and \a rhs represent the same result;
otherwise, returns false.
*/
/*!
\fn bool Qt::partial_ordering::operator!=(Qt::partial_ordering lhs, Qt::partial_ordering rhs)
Return true if \a lhs and \a rhs represent different results;
otherwise, returns true.
*/
/*!
\internal
\relates Qt::partial_ordering
\fn bool operator==(Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator!=(Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator< (Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator<=(Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator> (Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator>=(Qt::partial_ordering lhs, QtPrivate::CompareAgainstLiteralZero)
\fn bool operator==(QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs)
\fn bool operator!=(QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs)
\fn bool operator< (QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs)
\fn bool operator<=(QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs)
\fn bool operator> (QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs)
\fn bool operator>=(QtPrivate::CompareAgainstLiteralZero, Qt::partial_ordering rhs)
*/
/*!
\fn Qt::partial_ordering::is_eq (Qt::partial_ordering o)
\fn Qt::partial_ordering::is_neq (Qt::partial_ordering o)
\fn Qt::partial_ordering::is_lt (Qt::partial_ordering o)
\fn Qt::partial_ordering::is_lteq(Qt::partial_ordering o)
\fn Qt::partial_ordering::is_gt (Qt::partial_ordering o)
\fn Qt::partial_ordering::is_gteq(Qt::partial_ordering o)
\include qcompare.cpp is_eq_table
These functions are provided for compatibility with \c{std::partial_ordering}.
*/
/*!
\variable Qt::partial_ordering::less
Represents the result of a comparison where the left operand is less than
the right operand.
*/
/*!
\variable Qt::partial_ordering::equivalent
Represents the result of a comparison where the two operands are equivalent.
*/
/*!
\variable Qt::partial_ordering::greater
Represents the result of a comparison where the left operand is greater
than the right operand.
*/
/*!
\variable Qt::partial_ordering::unordered
Represents the result of a comparison where there is no ordering
relationship between the two operands.
*/
/*!
\class QPartialOrdering
\inmodule QtCore
\brief QPartialOrdering represents the result of a comparison that allows
for unordered results.
\sa Qt::strong_ordering, Qt::weak_ordering, {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,
establishing whether they are ordered and, if so, their ordering. It uses
this return type to indicate that the ordering is partial; that is, not all
pairs of values are ordered.
QPartialOrdering has four values, represented by the following symbolic
constants:
\list
\li \l less represents that the left operand is less than the right;
\li \l equivalent represents that the two operands are equivalent;
\li \l greater represents that the left operand is greater than the right;
\li \l unordered represents that the two operands are \e {not ordered}.
\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
Comparing QPartialOrdering::unordered against literal 0 always returns
a \c false result.
*/
/*!
\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
\target qpartialordering-operator-std-partial_ordering
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)
*/
/*!
\fn QPartialOrdering::is_eq (QPartialOrdering o)
\fn QPartialOrdering::is_neq (QPartialOrdering o)
\fn QPartialOrdering::is_lt (QPartialOrdering o)
\fn QPartialOrdering::is_lteq(QPartialOrdering o)
\fn QPartialOrdering::is_gt (QPartialOrdering o)
\fn QPartialOrdering::is_gteq(QPartialOrdering o)
\since 6.7
\include qcompare.cpp is_eq_table
These functions are provided for compatibility with \c{std::partial_ordering}.
*/
/*!
\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 two operands are equivalent.
*/
/*!
\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 there is no ordering
relationship between the two operands.
*/
/*!
\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 two operands are equivalent.
*/
/*!
\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 there is no ordering
relationship between the two operands.
*/
/*!
\internal
\macro Q_DECLARE_EQUALITY_COMPARABLE(Type)
\macro Q_DECLARE_EQUALITY_COMPARABLE(LeftType, RightType)
\macro Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE(Type)
\macro Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE(LeftType, RightType)
\since 6.7
\relates <QtCompare>
These macros are used to generate \c {operator==()} and \c {operator!=()}.
In C++17 mode, the mixed-type overloads also generate the reversed
operators.
In C++20 mode, only \c {operator==()} is defined. \c {operator!=()},
as well as the reversed operators for mixed-type comparison, are synthesized
by the compiler.
The operators are implemented in terms of a helper function
\c {comparesEqual()}.
It's the user's responsibility to declare and define this function.
Consider the following example of a comparison operators declaration:
\code
class MyClass {
...
private:
friend bool comparesEqual(const MyClass &, const MyClass &) noexcept;
Q_DECLARE_EQUALITY_COMPARABLE(MyClass)
};
\endcode
When compiled with C++17, the macro will expand into the following code:
\code
friend bool operator==(const MyClass &lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
friend bool operator!=(const MyClass &lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
\endcode
When compiled with C++20, the macro will expand only into \c {operator==()}:
\code
friend bool operator==(const MyClass &lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
\endcode
The \c {*_LITERAL_TYPE} versions of the macros are used to generate
\c constexpr operators. This means that the helper \c {comparesEqual()}
function must also be \c constexpr.
Consider the following example of a mixed-type \c constexpr comparison
operators declaration:
\code
class MyClass {
...
private:
friend constexpr bool comparesEqual(const MyClass &, int) noexcept;
Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE(MyClass, int)
};
\endcode
When compiled with C++17, the macro will expand into the following code:
\code
friend constexpr bool operator==(const MyClass &lhs, int rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
friend constexpr bool operator!=(const MyClass &lhs, int rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
friend constexpr bool operator==(int lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
friend constexpr bool operator!=(int lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
\endcode
When compiled with C++20, the macro expands only into \c {operator==()}:
\code
friend constexpr bool operator==(const MyClass &lhs, int rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
\endcode
//! [noexcept-requirement-desc]
These macros generate \c {noexcept} relational operators, and so they check
that the helper functions are \c {noexcept}.
Use the \c {_NON_NOEXCEPT} versions of the macros if the relational
operators of your class cannot be \c {noexcept}.
//! [noexcept-requirement-desc]
*/
/*!
\internal
\macro Q_DECLARE_PARTIALLY_ORDERED(Type)
\macro Q_DECLARE_PARTIALLY_ORDERED(LeftType, RightType)
\macro Q_DECLARE_PARTIALLY_ORDERED_LITERAL_TYPE(Type)
\macro Q_DECLARE_PARTIALLY_ORDERED_LITERAL_TYPE(LeftType, RightType)
\since 6.7
\relates <QtCompare>
These macros are used to generate all six relational operators.
The operators represent
{partial ordering}.
These macros use respective overloads of the
\l {Q_DECLARE_EQUALITY_COMPARABLE} macro to generate \c {operator==()} and
\c {operator!=()}, and also generate the four relational operators:
\c {operator<()}, \c {operator>()}, \c {operator<=()}, and \c {operator>()}.
In C++17 mode, the mixed-type overloads also generate the reversed
operators.
In C++20 mode, only \c {operator==()} and \c {operator<=>()} are defined.
Other operators, as well as the reversed operators for mixed-type
comparison, are synthesized by the compiler.
The (in)equality operators are implemented in terms of a helper function
\c {comparesEqual()}. The other relational operators are implemented in
terms of a helper function \c {compareThreeWay()}.
The \c {compareThreeWay()} function \e must return an object of type
\l Qt::partial_ordering. It's the user's responsibility to declare and define
both helper functions.
Consider the following example of a comparison operators declaration:
\code
class MyClass {
...
private:
friend bool comparesEqual(const MyClass &, const MyClass &) noexcept;
friend Qt::partial_ordering compareThreeWay(const MyClass &, const MyClass &) noexcept;
Q_DECLARE_PARTIALLY_ORDERED(MyClass)
};
\endcode
When compiled with C++17, the macro will expand into the following code:
\code
// operator==() and operator!=() are generated from
// Q_DECLARE_EQUALITY_COMPARABLE
friend bool operator<(const MyClass &lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend bool operator>(const MyClass &lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend bool operator<=(const MyClass &lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend bool operator>=(const MyClass &lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
\endcode
When compiled with C++20, the macro will expand into \c {operator==()} and
\c {operator<=>()}:
\code
friend bool operator==(const MyClass &lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
friend std::partial_ordering
operator<=>(const MyClass &lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
\endcode
The \c {*_LITERAL_TYPE} versions of the macros are used to generate
\c constexpr operators. This means that the helper \c {comparesEqual()} and
\c {compareThreeWay()} functions must also be \c constexpr.
Consider the following example of a mixed-type \c constexpr comparison
operators declaration:
\code
class MyClass {
...
private:
friend constexpr bool comparesEqual(const MyClass &, int) noexcept;
friend constexpr Qt::partial_ordering compareThreeWay(const MyClass &, int) noexcept;
Q_DECLARE_PARTIALLY_ORDERED_LITERAL_TYPE(MyClass, int)
};
\endcode
When compiled with C++17, the macro will expand into the following code:
\code
// operator==(), operator!=(), and their reversed versions are generated
// from Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE
friend constexpr bool operator<(const MyClass &lhs, int rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend constexpr bool operator>(const MyClass &lhs, int rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend constexpr bool operator<=(const MyClass &lhs, int rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend constexpr bool operator>=(const MyClass &lhs, int rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend constexpr bool operator<(int lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend constexpr bool operator>(int lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend constexpr bool operator<=(int lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
friend constexpr bool operator>=(int lhs, const MyClass &rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
\endcode
When compiled with C++20, the macro will expand into \c {operator==()} and
\c {operator<=>()}:
\code
friend constexpr bool operator==(const MyClass &lhs, int rhs) noexcept
{
// inline implementation which uses comparesEqual()
}
friend constexpr std::partial_ordering
operator<=>(const MyClass &lhs, int rhs) noexcept
{
// inline implementation which uses compareThreeWay()
}
\endcode
\include qcompare.cpp noexcept-requirement-desc
\sa Q_DECLARE_EQUALITY_COMPARABLE, Q_DECLARE_WEAKLY_ORDERED,
Q_DECLARE_STRONGLY_ORDERED
*/
/*!
\internal
\macro Q_DECLARE_WEAKLY_ORDERED(Type)
\macro Q_DECLARE_WEAKLY_ORDERED(LeftType, RightType)
\macro Q_DECLARE_WEAKLY_ORDERED_LITERAL_TYPE(Type)
\macro Q_DECLARE_WEAKLY_ORDERED_LITERAL_TYPE(LeftType, RightType)
\since 6.7
\relates <QtCompare>
These macros behave similarly to the
\l {Q_DECLARE_PARTIALLY_ORDERED} overloads, but represent
{weak ordering}.
The (in)equality operators are implemented in terms of a helper function
\c {comparesEqual()}. The other relational operators are implemented in
terms of a helper function \c {compareThreeWay()}.
The \c {compareThreeWay()} function \e must return an object of type
\l Qt::weak_ordering. It's the user's responsibility to declare and define both
helper functions.
The \c {*_LITERAL_TYPE} overloads are used to generate \c constexpr
operators. This means that the helper \c {comparesEqual()} and
\c {compareThreeWay()} functions must also be \c constexpr.
\include qcompare.cpp noexcept-requirement-desc
See \l {Q_DECLARE_PARTIALLY_ORDERED} for usage examples.
\sa Q_DECLARE_PARTIALLY_ORDERED, Q_DECLARE_STRONGLY_ORDERED,
Q_DECLARE_EQUALITY_COMPARABLE
*/
/*!
\internal
\macro Q_DECLARE_STRONGLY_ORDERED(Type)
\macro Q_DECLARE_STRONGLY_ORDERED(LeftType, RightType)
\macro Q_DECLARE_STRONGLY_ORDERED_LITERAL_TYPE(Type)
\macro Q_DECLARE_STRONGLY_ORDERED_LITERAL_TYPE(LeftType, RightType)
\since 6.7
\relates <QtCompare>
These macros behave similarly to the
\l {Q_DECLARE_PARTIALLY_ORDERED} overloads, but represent
{strong ordering}.
The (in)equality operators are implemented in terms of a helper function
\c {comparesEqual()}. The other relational operators are implemented in
terms of a helper function \c {compareThreeWay()}.
The \c {compareThreeWay()} function \e must return an object of type
\l Qt::strong_ordering. It's the user's responsibility to declare and define
both helper functions.
The \c {*_LITERAL_TYPE} overloads are used to generate \c constexpr
operators. This means that the helper \c {comparesEqual()} and
\c {compareThreeWay()} functions must also be \c constexpr.
\include qcompare.cpp noexcept-requirement-desc
See \l {Q_DECLARE_PARTIALLY_ORDERED} for usage examples.
\sa Q_DECLARE_PARTIALLY_ORDERED, Q_DECLARE_WEAKLY_ORDERED,
Q_DECLARE_EQUALITY_COMPARABLE
*/
/*!
\internal
\macro Q_DECLARE_EQUALITY_COMPARABLE(LeftType, RightType, Attributes...)
\macro Q_DECLARE_EQUALITY_COMPARABLE_LITERAL_TYPE(LeftType, RightType, Attributes...)
\macro Q_DECLARE_PARTIALLY_ORDERED(LeftType, RightType, Attributes...)
\macro Q_DECLARE_PARTIALLY_ORDERED_LITERAL_TYPE(LeftType, RightType, Attributes...)
\macro Q_DECLARE_WEAKLY_ORDERED(LeftType, RightType, Attributes...)
\macro Q_DECLARE_WEAKLY_ORDERED_LITERAL_TYPE(LeftType, RightType, Attributes...)
\macro Q_DECLARE_STRONGLY_ORDERED(LeftType, RightType, Attributes...)
\macro Q_DECLARE_STRONGLY_ORDERED_LITERAL_TYPE(LeftType, RightType, Attributes...)
\since 6.8
\relates <QtCompare>
These macros behave like their two-argument versions, but allow
specification of C++ attributes to add before every generated relational
operator.
As an example, the \c Attributes parameter can be used in Qt to pass
the \c QT_ASCII_CAST_WARN marco (whose expansion can mark the function as
deprecated) when implementing comparison of encoding-aware string types
with C-style strings or byte arrays.
Starting from Qt 6.9, \c Attributes becomes a variable argument, meaning
that you can now specify more complex templates and constraints using
these macros.
For example, equality-comparison of a custom type with any integral type
can be implemented in the following way:
\code
class MyClass {
public:
...
private:
template <typename T, std::enable_if_t<std::is_integral_v<T>, bool> = true>
friend constexpr bool comparesEqual(const MyClass &lhs, T rhs) noexcept
{ ... }
Q_DECLARE_EQUALITY_COMPARABLE(MyClass, T,
template <typename T,
std::enable_if_t<std::is_integral_v<T>,
bool> = true>)
};
\endcode
\note Bear in mind that a macro treats each comma (unless within
parentheses) as starting a new argument; for example, the invocation above
has five arguments. Due to implementation details, the macros cannot have
more than nine arguments. If the constraint is too complicated, use an alias
template to give it a self-explanatory name, and use this alias as an
argument of the macro.
\include qcompare.cpp noexcept-requirement-desc
*/
/*!
\internal
\macro Q_DECLARE_EQUALITY_COMPARABLE_NON_NOEXCEPT(Type)
\macro Q_DECLARE_EQUALITY_COMPARABLE_NON_NOEXCEPT(LeftType, RightType)
\macro Q_DECLARE_EQUALITY_COMPARABLE_NON_NOEXCEPT(LeftType, RightType, Attributes...)
\macro Q_DECLARE_PARTIALLY_ORDERED_NON_NOEXCEPT(Type)
\macro Q_DECLARE_PARTIALLY_ORDERED_NON_NOEXCEPT(LeftType, RightType)
\macro Q_DECLARE_PARTIALLY_ORDERED_NON_NOEXCEPT(LeftType, RightType, Attributes...)
\macro Q_DECLARE_WEAKLY_ORDERED_NON_NOEXCEPT(Type)
\macro Q_DECLARE_WEAKLY_ORDERED_NON_NOEXCEPT(LeftType, RightType)
\macro Q_DECLARE_WEAKLY_ORDERED_NON_NOEXCEPT(LeftType, RightType, Attributes...)
\macro Q_DECLARE_STRONGLY_ORDERED_NON_NOEXCEPT(Type)
\macro Q_DECLARE_STRONGLY_ORDERED_NON_NOEXCEPT(LeftType, RightType)
\macro Q_DECLARE_STRONGLY_ORDERED_NON_NOEXCEPT(LeftType, RightType, Attributes...)
\since 6.8
\relates <QtCompare>
These macros behave like their versions without the \c {_NON_NOEXCEPT}
suffix, but should be used when the relational operators cannot be
\c {noexcept}.
Starting from Qt 6.9, \c Attributes becomes a variable argument.
*/
/*!
\internal
\macro Q_DECLARE_ORDERED(Type)
\macro Q_DECLARE_ORDERED(LeftType, RightType)
\macro Q_DECLARE_ORDERED(LeftType, RightType, Attributes...)
\macro Q_DECLARE_ORDERED_LITERAL_TYPE(Type)
\macro Q_DECLARE_ORDERED_LITERAL_TYPE(LeftType, RightType)
\macro Q_DECLARE_ORDERED_LITERAL_TYPE(LeftType, RightType, Attributes...)
\macro Q_DECLARE_ORDERED_NON_NOEXCEPT(Type)
\macro Q_DECLARE_ORDERED_NON_NOEXCEPT(LeftType, RightType)
\macro Q_DECLARE_ORDERED_NON_NOEXCEPT(LeftType, RightType, Attributes...)
\since 6.9
\relates <QtCompare>
These macros behave similarly to the
\c {Q_DECLARE_(PARTIALLY,WEAKLY,STRONGLY)_ORDERED} overloads, but represent
any one of those three, using \c auto return type.
This is what you typically would use for template classes where
the strength of the ordering depends on the template arguments.
For example, if one of the template arguments is a floating-point
type, the ordering would be \l {Qt::partial_ordering}, if they all
are integral - \l {Qt::strong_ordering}.
\note It is better to use one of the explicit-strength macros in general, to
communicate intent. Use these macros only when the stength actually does vary
with template arguments.
The (in)equality operators are implemented in terms of a helper function
\c {comparesEqual()}. The other relational operators are implemented in
terms of a helper function \c {compareThreeWay()}.
The \c {compareThreeWay()} function \e must return an object of an ordering
type. It's the user's responsibility to declare and define both helper
functions.
The \c {*_LITERAL_TYPE} overloads are used to generate \c constexpr
operators. This means that the helper \c {comparesEqual()} and
\c {compareThreeWay()} functions must also be \c constexpr.
See \l {Q_DECLARE_PARTIALLY_ORDERED} for usage examples.
By default, the generated operators are \c {noexcept}.
Use the \c {*_NON_NOEXCEPT} overloads if the relational operators cannot be
\c {noexcept}.
The three-argument versions of the macros allow specification of C++
attributes to add before every generated relational operator.
See \l {Q_DECLARE_EQUALITY_COMPARABLE(LeftType, RightType, Attributes...)}
for more details and usage examples.
\sa Q_DECLARE_PARTIALLY_ORDERED, Q_DECLARE_WEAKLY_ORDERED,
Q_DECLARE_STRONGLY_ORDERED, Q_DECLARE_EQUALITY_COMPARABLE
*/
/*!
\fn template <typename LeftInt, typename RightInt, Qt::if_integral<LeftInt> = true, Qt::if_integral<RightInt> = true> auto Qt::compareThreeWay(LeftInt lhs, RightInt rhs)
\since 6.7
\relates <QtCompare>
\overload
Implements three-way comparison of integral types.
Returns \c {lhs <=> rhs}, provided \c LeftInt and \c RightInt are built-in
integral types. Unlike \c {operator<=>()}, this function template is also
available in C++17. See
{cppreference} for more details.
This function can also be used in custom \c {compareThreeWay()} functions,
when ordering members of a custom class represented by built-in types:
\code
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)
};
\endcode
Returns an instance of \l Qt::strong_ordering that represents the relation
between \a lhs and \a rhs.
\constraints both
\c LeftInt and \c RightInt are built-in integral types.
*/
/*!
\fn template <typename LeftFloat, typename RightFloat, Qt::if_floating_point<LeftFloat> = true, Qt::if_floating_point<RightFloat> = true> auto Qt::compareThreeWay(LeftFloat lhs, RightFloat rhs)
\since 6.7
\relates <QtCompare>
\overload
Implements three-way comparison of floating point types.
Returns \c {lhs <=> rhs}, provided \c LeftFloat and \c RightFloat are
built-in floating-point types. Unlike \c {operator<=>()}, this function
template is also available in C++17. See
{cppreference} for more details.
This function can also be used in custom \c {compareThreeWay()} functions,
when ordering members of a custom class represented by built-in types:
\code
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)
};
\endcode
Returns an instance of \l Qt::partial_ordering that represents the relation
between \a lhs and \a rhs. If \a lhs or \a rhs is not a number (NaN),
\l Qt::partial_ordering::unordered is returned.
\constraints both
\c LeftFloat and \c RightFloat are built-in floating-point types.
*/
/*!
\fn template <typename IntType, typename FloatType, Qt::if_integral<IntType> = true, Qt::if_floating_point<FloatType> = true> auto Qt::compareThreeWay(IntType lhs, FloatType rhs)
\since 6.7
\relates <QtCompare>
\overload
Implements three-way comparison of integral and floating point types.
This function converts \a lhs to \c FloatType and calls the overload for
floating-point types.
Returns an instance of \l Qt::partial_ordering that represents the relation
between \a lhs and \a rhs. If \a rhs is not a number (NaN),
\l Qt::partial_ordering::unordered is returned.
\constraints \c IntType
is a built-in integral type and \c FloatType is a built-in floating-point
type.
*/
/*!
\fn template <typename FloatType, typename IntType, Qt::if_floating_point<FloatType> = true, Qt::if_integral<IntType> = true> auto Qt::compareThreeWay(FloatType lhs, IntType rhs)
\since 6.7
\relates <QtCompare>
\overload
Implements three-way comparison of floating point and integral types.
This function converts \a rhs to \c FloatType and calls the overload for
floating-point types.
Returns an instance of \l Qt::partial_ordering that represents the relation
between \a lhs and \a rhs. If \a lhs is not a number (NaN),
\l Qt::partial_ordering::unordered is returned.
\constraints \c FloatType
is a built-in floating-point type and \c IntType is a built-in integral
type.
*/
#if QT_DEPRECATED_SINCE(6, 8)
/*!
\fn template <typename LeftType, typename RightType, Qt::if_compatible_pointers<LeftType, RightType> = true> Qt::compareThreeWay(const LeftType *lhs, const RightType *rhs)
\since 6.7
\deprecated [6.8] Wrap the pointers into Qt::totally_ordered_wrapper and
use the respective Qt::compareThreeWay() overload instead.
\relates <QtCompare>
\overload
Implements three-way comparison of pointers.
Returns an instance of \l Qt::strong_ordering that represents the relation
between \a lhs and \a rhs.
\constraints \c LeftType and
\c RightType are the same type, or base and derived types. It is also used
to compare any pointer to \c {std::nullptr_t}.
*/
#endif // QT_DEPRECATED_SINCE(6, 8)
/*!
\fn template <class Enum, Qt::if_enum<Enum> = true> Qt::compareThreeWay(Enum lhs, Enum rhs)
\since 6.7
\relates <QtCompare>
\overload
Implements three-way comparison of enum types.
This function converts \c Enum to its underlying type and calls the
overload for integral types.
Returns an instance of \l Qt::strong_ordering that represents the relation
between \a lhs and \a rhs.
\constraints \c Enum is an enum type.
*/
/*!
\fn template <typename T, typename U, Qt::if_compatible_pointers<T, U> = true> Qt::compareThreeWay(Qt::totally_ordered_wrapper<T*> lhs, Qt::totally_ordered_wrapper<U*> rhs)
\since 6.8
\relates <QtCompare>
\overload
Implements three-way comparison of pointers that are wrapped into
\l Qt::totally_ordered_wrapper. Uses
{strict total order over pointers} when doing the comparison.
Returns an instance of \l Qt::strong_ordering that represents the relation
between \a lhs and \a rhs.
\constraints \c T and \c U are the same type, or base and derived types.
*/
/*!
\fn template <typename T, typename U, Qt::if_compatible_pointers<T, U> = true> Qt::compareThreeWay(Qt::totally_ordered_wrapper<T*> lhs, U *rhs)
\since 6.8
\relates <QtCompare>
\overload
Implements three-way comparison of a pointer wrapped into
\l Qt::totally_ordered_wrapper with a normal pointer. Uses
{strict total order over pointers} when doing the comparison.
Returns an instance of \l Qt::strong_ordering that represents the relation
between \a lhs and \a rhs.
\constraints \c T and \c U are the same type, or base and derived types.
*/
/*!
\fn template <typename T, typename U, Qt::if_compatible_pointers<T, U> = true> Qt::compareThreeWay(U *lhs, Qt::totally_ordered_wrapper<T*> rhs)
\since 6.8
\relates <QtCompare>
\overload
Implements three-way comparison of a normal pointer with a pointer wrapped
into \l Qt::totally_ordered_wrapper. Uses
{strict total order over pointers} when doing the comparison.
Returns an instance of \l Qt::strong_ordering that represents the relation
between \a lhs and \a rhs.
\constraints \c T and \c U are the same type, or base and derived types.
*/
/*!
\fn template <typename T> Qt::compareThreeWay(Qt::totally_ordered_wrapper<T*> lhs, std::nullptr_t rhs)
\since 6.8
\relates <QtCompare>
\overload
Implements three-way comparison of a pointer wrapped into
\l Qt::totally_ordered_wrapper with \c {std::nullptr_t}.
Returns an instance of \l Qt::strong_ordering that represents the relation
between \a lhs and \a rhs.
*/
/*!
\fn template <typename T> Qt::compareThreeWay(std::nullptr_t lhs, Qt::totally_ordered_wrapper<T*> rhs)
\since 6.8
\relates <QtCompare>
\overload
Implements three-way comparison of \c {std::nullptr_t} with a pointer
wrapped into \l Qt::totally_ordered_wrapper.
Returns an instance of \l Qt::strong_ordering that represents the relation
between \a lhs and \a rhs.
*/
/*!
\fn template <typename T1, typename T2, typename U1, typename U2> Qt::compareThreeWay(const std::pair<T1, T2> &lhs, const std::pair<U1, U2> &rhs)
\since 6.12
\relates <QtCompare>
\overload
\note \c T1 should be comparable to \c U1 and \c T2 should be comparable to
\c U2 using \c {compareThreeWay()} or \c {operator<()}.
This overload uses \c auto return type, because the strength of the ordering
depends on the template arguments of the pair. For example, if either of
the arguments is a floating point type, the ordering would be
\l {Qt::partial_ordering}, if they both are integral - \l {Qt::strong_ordering}.
*/
/*!
\fn template <typename LeftType, typename RightType> qCompareThreeWay(const LeftType &lhs, const RightType &rhs)
\since 6.7
\relates <QtCompare>
Performs the three-way comparison on \a lhs and \a 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 \c LeftType and \c RightType.
\note This function template is only available when \c {compareThreeWay()}
is implemented for the \c {(LeftType, RightType)} pair or the reversed
\c {(RightType, LeftType)} pair.
This method is equivalent to
\code
using Qt::compareThreeWay;
return compareThreeWay(lhs, rhs);
\endcode
where \c {Qt::compareThreeWay} is the Qt implementation of three-way
comparison for built-in types.
The free \c {compareThreeWay} functions should provide three-way comparison
for custom types. The functions should return one of the Qt ordering types.
Qt provides \c {compareThreeWay} implementation for some of its types.
\note \b {Do not} re-implement \c {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
\c LeftType and \c RightType.
If you know the types, use
\list
\li \c {Qt::compareThreeWay} for built-in types
\li \c {compareThreeWay} for custom types
\endlist
Use \c {operator<=>()} directly in code that will only be compiled with
C++20 or later.
\sa Qt::partial_ordering, Qt::weak_ordering, Qt::strong_ordering
*/
/*!
\fn template <typename InputIt1, typename InputIt2> QtOrderingPrivate::lexicographicalCompareThreeWay(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2)
\internal
\relates <QtCompare>
\brief Three-way lexicographic comparison of ranges.
Checks how the range [ \a first1, \a last1 ) compares to the second range
[ \a first2, \a last2 ) and produces a result of the strongest applicable
category type.
This function can only be used if \c InputIt1::value_type and
\c InputIt2::value_type types provide a \c {compareThreeWay()} helper method
that returns one of the Qt ordering types.
\sa {Comparison types overview}
*/
/*!
\fn template <typename InputIt1, typename InputIt2, typename Comparator> QtOrderingPrivate::lexicographicalCompareThreeWay(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2, Comparator cmp)
\internal
\relates <QtCompare>
\overload
This overload takes a custom \c Comparator that is used to do the comparison.
The comparator should have the following signature:
\badcode
OrderingType cmp(const InputIt1::value_type &lhs, const InputIt2::value_type &rhs);
\endcode
where \c OrderingType is one of the Qt ordering types.
\sa {Comparison types overview}
*/
/*!
\class Qt::totally_ordered_wrapper
\inmodule QtCore
\inheaderfile QtCompare
\brief Qt::totally_ordered_wrapper is a wrapper type that provides strict
total order for the wrapped types.
\since 6.8
Qt::totally_ordered_wrapper\<P\> is a template class where \a P specifies
the type to wrap.
One of its primary usecases is to prevent \e {Undefined Behavior} (UB) when
comparing pointers.
Consider the following simple class:
\code
template <typename T>
struct PointerWrapperBad {
int val;
T *ptr;
};
\endcode
Lexicographical comparison of the two instances of the \c PointerWrapperBad
type would result in UB, because it will call \c {operator<()} or
\c {operator<=>()} on the \c {ptr} members.
To fix it, use the new wrapper type:
\code
template <typename T>
struct PointerWrapperGood {
int val;
Qt::totally_ordered_wrapper<T *> ptr;
friend bool
operator==(PointerWrapperGood lhs, PointerWrapperGood rhs) noexcept = default;
friend auto
operator<=>(PointerWrapperGood lhs, PointerWrapperGood rhs) noexecpt = default;
};
\endcode
The \c {operator<()} and (if available) \c {operator<=>()} operators for
the \c {Qt::totally_ordered_wrapper} type use the
{std::compare_three_way} function objects respectively, providing
{strict total order over pointers} when doing the comparison.
As a result, the relational operators for \c {PointerWrapperGood::ptr}
member will be well-defined, and we can even \c {=default} the relational
operators for the \c {PointerWrapperGood} class, like it's shown above.
*/
/*!
\struct Qt::has_qt_compare_three_way
\inmodule QtCore
\inheaderfile QtCompare
\brief A type trait for checking if a type supports
\c {compareThreeWay()}.
\since 6.12
This struct is a
{UnaryTypeTrait} that inherits \c {std::true_type} if \c T supports
three-way comparison via \c {compareThreeWay()}, and \c {std::false_type}
otherwise.
Use Qt::if_has_qt_compare_three_way to constrain function templates
on this property.
\sa Qt::if_has_qt_compare_three_way, Qt::compareThreeWay()
*/
/*!
\typealias Qt::if_has_qt_compare_three_way
\inmodule QtCore
\relates <QtCompare>
\since 6.12
A convenience alias for \c {std::enable_if_t} that can be used to
constrain function templates to types that support three-way comparison
via \c {compareThreeWay()}.
\sa Qt::has_qt_compare_three_way
*/
QT_END_NAMESPACE