From b93e7619a421f072c2a73cbae47f98e4fdccc20c Mon Sep 17 00:00:00 2001 From: Edward Welbourne Date: Tue, 5 Mar 2024 11:40:04 +0100 Subject: [PATCH] Correct documentation of QDateTime's comparisons These previously claimed that date-times with different date, time or zone are different; as pointed out by Marcus Tillmanns, this is not true. Corrected the documentation to talk about representing the same moment in time. In the process, renamed the snippet shared with several other docs, since the snippet name only focused on the other part of what it was saying. Pick-to: 6.6 6.5 6.2 5.15 Fixes: QTBUG-122973 Change-Id: Ifd74da84aad0b0dca688c131b6ae6a7b65633225 Reviewed-by: Giuseppe D'Angelo Reviewed-by: Thiago Macieira (cherry picked from commit cb5aac06cf7b3982a42004fd7455d78a3caba550) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/time/qdatetime.cpp | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/src/corelib/time/qdatetime.cpp b/src/corelib/time/qdatetime.cpp index e54ebf9c4f9..3dc5c1f71a1 100644 --- a/src/corelib/time/qdatetime.cpp +++ b/src/corelib/time/qdatetime.cpp @@ -5201,13 +5201,20 @@ bool QDateTime::equals(const QDateTime &other) const /*! \fn bool QDateTime::operator==(const QDateTime &lhs, const QDateTime &rhs) - Returns \c true if \a lhs is the same as \a rhs; otherwise returns \c false. + Returns \c true if \a lhs represents the same moment in time as \a rhs; + otherwise returns \c false. -//! [invalid-vs-valid-datetime] - Two datetimes are different if either the date, the time, or the time zone - components are different. Since 5.14, all invalid datetimes are equal (and - less than all valid datetimes). -//! [invalid-vs-valid-datetime] +//! [datetime-order-details] + Two datetimes using different time representations can have different + offsets from UTC. In this case, they may compare equivalent even if their \l + date() and \l time() differ, if that difference matches the difference in + UTC offset. If their \c date() and \c time() coincide, the one with higher + offset from UTC is less (earlier) than the one with lower offset. As a + result, datetimes are only weakly ordered. + + Since 5.14, all invalid datetimes are equivalent and less than all valid + datetimes. +//! [datetime-order-details] \sa operator!=(), operator<(), operator<=(), operator>(), operator>=() */ @@ -5218,7 +5225,7 @@ bool QDateTime::equals(const QDateTime &other) const Returns \c true if \a lhs is different from \a rhs; otherwise returns \c false. - \include qdatetime.cpp invalid-vs-valid-datetime + \include qdatetime.cpp datetime-order-details \sa operator==() */ @@ -5244,7 +5251,7 @@ Qt::weak_ordering compareThreeWay(const QDateTime &lhs, const QDateTime &rhs) Returns \c true if \a lhs is earlier than \a rhs; otherwise returns \c false. - \include qdatetime.cpp invalid-vs-valid-datetime + \include qdatetime.cpp datetime-order-details \sa operator==() */ @@ -5255,7 +5262,7 @@ Qt::weak_ordering compareThreeWay(const QDateTime &lhs, const QDateTime &rhs) Returns \c true if \a lhs is earlier than or equal to \a rhs; otherwise returns \c false. - \include qdatetime.cpp invalid-vs-valid-datetime + \include qdatetime.cpp datetime-order-details \sa operator==() */ @@ -5265,7 +5272,7 @@ Qt::weak_ordering compareThreeWay(const QDateTime &lhs, const QDateTime &rhs) Returns \c true if \a lhs is later than \a rhs; otherwise returns \c false. - \include qdatetime.cpp invalid-vs-valid-datetime + \include qdatetime.cpp datetime-order-details \sa operator==() */ @@ -5276,7 +5283,7 @@ Qt::weak_ordering compareThreeWay(const QDateTime &lhs, const QDateTime &rhs) Returns \c true if \a lhs is later than or equal to \a rhs; otherwise returns \c false. - \include qdatetime.cpp invalid-vs-valid-datetime + \include qdatetime.cpp datetime-order-details \sa operator==() */