Deprecate QDateTime methods using plain Qt::TimeSpec

As foreshadowed when QDateTime adapted to route all QTimeSpec use
through QTimeZone, this commit deprecates the old API in favor of the
newly more capable QTimeZone-based API.

Fixes: QTBUG-108199
Change-Id: I9a3f9f94d4a5d8cc229db72b3e4731a9e318a076
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

Author: ediosyncratic

src/corelib/time/qdatetime.cpp

@@ -755,6 +755,8 @@ int QDate::weekNumber(int *yearNumber) const
     return (thursday.dayOfYear() + 6) / 7;
 }
 
+#if QT_DEPRECATED_SINCE(6, 9)
+// Only called by deprecated methods (so bootstrap builds warn unused without this #if).
 static QTimeZone asTimeZone(Qt::TimeSpec spec, int offset, const char *warner)
 {
     if (warner) {
@@ -783,6 +785,7 @@ static QTimeZone asTimeZone(Qt::TimeSpec spec, int offset, const char *warner)
         ? QTimeZone::fromSecondsAheadOfUtc(offset)
         : QTimeZone(QTimeZone::LocalTime);
 }
+#endif // Helper for 6.9 deprecation
 
 static bool inDateTimeRange(qint64 jd, bool start)
 {
@@ -893,9 +896,11 @@ QDateTime QDate::startOfDay() const
     return startOfDay(QTimeZone::LocalTime);
 }
 
+#if QT_DEPRECATED_SINCE(6, 9)
 /*!
     \overload
     \since 5.14
+    \deprecated [6.9] Use \c{startOfDay(const QTimeZone &)} instead.
 
     Returns the start-moment of the day.
 
@@ -926,6 +931,7 @@ QDateTime QDate::startOfDay(Qt::TimeSpec spec, int offsetSeconds) const
     // If spec was Qt::TimeZone, zone's is Qt::LocalTime.
     return zone.timeSpec() == spec ? startOfDay(zone) :  QDateTime();
 }
+#endif // 6.9 deprecation
 
 static QDateTime toLatest(QDate day, const QTimeZone &zone)
 {
@@ -1022,9 +1028,11 @@ QDateTime QDate::endOfDay() const
     return endOfDay(QTimeZone::LocalTime);
 }
 
+#if QT_DEPRECATED_SINCE(6, 9)
 /*!
     \overload
     \since 5.14
+    \deprecated [6.9] Use \c{endOfDay(const QTimeZone &) instead.
 
     Returns the end-moment of the day.
 
@@ -1055,6 +1063,7 @@ QDateTime QDate::endOfDay(Qt::TimeSpec spec, int offsetSeconds) const
     // If spec was Qt::TimeZone, zone's is Qt::LocalTime.
     return endOfDay(zone);
 }
+#endif // 6.9 deprecation
 
 #if QT_CONFIG(datestring) // depends on, so implies, textdate
 
@@ -3410,7 +3419,10 @@ QDateTime::QDateTime() noexcept
     static_assert(sizeof(ShortData) >= sizeof(void*), "oops, Data::swap() is broken!");
 }
 
+#if QT_DEPRECATED_SINCE(6, 9)
 /*!
+    \deprecated [6.9] Use \c{QDateTime(date, time)} or \c{QDateTime(date, time, QTimeZone::fromSecondsAheadOfUtc(offsetSeconds))}.
+
     Constructs a datetime with the given \a date and \a time, using the time
     representation implied by \a spec and \a offsetSeconds seconds.
 
@@ -3432,6 +3444,7 @@ QDateTime::QDateTime(QDate date, QTime time, Qt::TimeSpec spec, int offsetSecond
     : d(QDateTimePrivate::create(date, time, asTimeZone(spec, offsetSeconds, "QDateTime")))
 {
 }
+#endif // 6.9 deprecation
 
 /*!
     \since 5.2
@@ -3772,7 +3785,10 @@ void QDateTime::setTime(QTime time)
     checkValidDateTime(d);
 }
 
+#if QT_DEPRECATED_SINCE(6, 9)
 /*!
+    \deprecated [6.9] Use setTimeZone() instead
+
     Sets the time specification used in this datetime to \a spec.
     The datetime may refer to a different point in time.
 
@@ -3795,6 +3811,7 @@ void QDateTime::setTimeSpec(Qt::TimeSpec spec)
 
 /*!
     \since 5.2
+    \deprecated [6.9] Use setTimeZone(QTimeZone::fromSecondsAheadOfUtc(offsetSeconds)) instead
 
     Sets the timeSpec() to Qt::OffsetFromUTC and the offset to \a offsetSeconds.
     The datetime may refer to a different point in time.
@@ -3812,6 +3829,7 @@ void QDateTime::setOffsetFromUtc(int offsetSeconds)
 {
     reviseTimeZone(d, QTimeZone::fromSecondsAheadOfUtc(offsetSeconds));
 }
+#endif // 6.9 deprecations
 
 /*!
     \since 5.2
@@ -4480,7 +4498,10 @@ qint64 QDateTime::msecsTo(const QDateTime &other) const
     \sa addMSecs
 */
 
+#if QT_DEPRECATED_SINCE(6, 9)
 /*!
+    \deprecated [6.9] Use \l toTimeZone() instead.
+
     Returns a copy of this datetime converted to the given time \a spec.
 
     The result represents the same moment in time as, and is equal to, this datetime.
@@ -4501,6 +4522,7 @@ QDateTime QDateTime::toTimeSpec(Qt::TimeSpec spec) const
 {
     return toTimeZone(asTimeZone(spec, 0, "toTimeSpec"));
 }
+#endif // 6.9 deprecation
 
 /*!
     \since 5.2
@@ -4919,8 +4941,11 @@ qint64 QDateTime::currentSecsSinceEpoch() noexcept
 #error "What system is this?"
 #endif
 
+#if QT_DEPRECATED_SINCE(6, 9)
 /*!
+    \since 5.2
     \overload
+    \deprecated [6.9] Pass a \l QTimeZone instead, or omit \a spec and \a offsetSeconds.
 
     Returns a datetime representing a moment the given number \a msecs of
     milliseconds after the start, in UTC, of the year 1970, described as
@@ -4949,6 +4974,7 @@ QDateTime QDateTime::fromMSecsSinceEpoch(qint64 msecs, Qt::TimeSpec spec, int of
 /*!
     \since 5.8
     \overload
+    \deprecated [6.9] Pass a \l QTimeZone instead, or omit \a spec and \a offsetSeconds.
 
     Returns a datetime representing a moment the given number \a secs of seconds
     after the start, in UTC, of the year 1970, described as specified by \a spec
@@ -4973,6 +4999,7 @@ QDateTime QDateTime::fromSecsSinceEpoch(qint64 secs, Qt::TimeSpec spec, int offs
     return fromSecsSinceEpoch(secs,
                               asTimeZone(spec, offsetSeconds, "QDateTime::fromSecsSinceEpoch"));
 }
+#endif // 6.9 deprecations
 
 /*!
     \since 5.2

src/corelib/time/qdatetime.h

@@ -103,8 +103,13 @@ class Q_CORE_EXPORT QDate
     int daysInMonth(QCalendar cal) const;
     int daysInYear(QCalendar cal) const;
 
+#if QT_DEPRECATED_SINCE(6, 9)
+    QT_DEPRECATED_VERSION_X_6_9("Pass QTimeZone instead")
     QDateTime startOfDay(Qt::TimeSpec spec, int offsetSeconds = 0) const;
+    QT_DEPRECATED_VERSION_X_6_9("Pass QTimeZone instead")
     QDateTime endOfDay(Qt::TimeSpec spec, int offsetSeconds = 0) const;
+#endif
+
     QDateTime startOfDay(const QTimeZone &zone) const;
     QDateTime endOfDay(const QTimeZone &zone) const;
     QDateTime startOfDay() const;
@@ -307,7 +312,10 @@ class Q_CORE_EXPORT QDateTime
 
 public:
     QDateTime() noexcept;
+#if QT_DEPRECATED_SINCE(6, 9)
+    QT_DEPRECATED_VERSION_X_6_9("Pass QTimeZone instead")
     QDateTime(QDate date, QTime time, Qt::TimeSpec spec, int offsetSeconds = 0);
+#endif
     QDateTime(QDate date, QTime time, const QTimeZone &timeZone);
     QDateTime(QDate date, QTime time);
     QDateTime(const QDateTime &other) noexcept;
@@ -338,8 +346,12 @@ class Q_CORE_EXPORT QDateTime
 
     void setDate(QDate date);
     void setTime(QTime time);
+#if QT_DEPRECATED_SINCE(6, 9)
+    QT_DEPRECATED_VERSION_X_6_9("Use setTimeZone() instead")
     void setTimeSpec(Qt::TimeSpec spec);
+    QT_DEPRECATED_VERSION_X_6_9("Use setTimeZone() instead")
     void setOffsetFromUtc(int offsetSeconds);
+#endif
     void setTimeZone(const QTimeZone &toZone);
     void setMSecsSinceEpoch(qint64 msecs);
     void setSecsSinceEpoch(qint64 secs);
@@ -360,7 +372,10 @@ class Q_CORE_EXPORT QDateTime
         return addMSecs(msecs.count());
     }
 
+#if QT_DEPRECATED_SINCE(6, 9)
+    QT_DEPRECATED_VERSION_X_6_9("Use toTimeZone instead")
     QDateTime toTimeSpec(Qt::TimeSpec spec) const;
+#endif
     QDateTime toLocalTime() const;
     QDateTime toUTC() const;
     QDateTime toOffsetFromUtc(int offsetSeconds) const;
@@ -387,8 +402,12 @@ class Q_CORE_EXPORT QDateTime
     { return fromString(string, qToStringViewIgnoringNull(format), cal); }
 #endif
 
+#if QT_DEPRECATED_SINCE(6, 9)
+    QT_DEPRECATED_VERSION_X_6_9("Pass QTimeZone instead of time-spec, offset")
     static QDateTime fromMSecsSinceEpoch(qint64 msecs, Qt::TimeSpec spec, int offsetFromUtc = 0);
+    QT_DEPRECATED_VERSION_X_6_9("Pass QTimeZone instead of time-spec, offset")
     static QDateTime fromSecsSinceEpoch(qint64 secs, Qt::TimeSpec spec, int offsetFromUtc = 0);
+#endif
 
     static QDateTime fromMSecsSinceEpoch(qint64 msecs, const QTimeZone &timeZone);
     static QDateTime fromSecsSinceEpoch(qint64 secs, const QTimeZone &timeZone);

tests/auto/corelib/time/qdatetime/tst_qdatetime.cpp

@@ -32,7 +32,9 @@ private Q_SLOTS:
     void isValid();
     void date();
     void time();
+#if QT_DEPRECATED_SINCE(6, 9)
     void timeSpec();
+#endif
     void toSecsSinceEpoch_data();
     void toSecsSinceEpoch();
     void daylightSavingsTimeChange_data();
@@ -44,8 +46,10 @@ private Q_SLOTS:
     void setTime();
     void setTimeZone_data();
     void setTimeZone();
+#if QT_DEPRECATED_SINCE(6, 9)
     void setTimeSpec_data();
     void setTimeSpec();
+#endif
     void setSecsSinceEpoch();
     void setMSecsSinceEpoch_data();
     void setMSecsSinceEpoch();
@@ -74,13 +78,15 @@ private Q_SLOTS:
     void addSecs();
     void addMSecs_data();
     void addMSecs();
+#if QT_DEPRECATED_SINCE(6, 9)
     void toTimeSpec_data();
     void toTimeSpec();
     void toLocalTime_data() { toTimeSpec_data(); }
     void toLocalTime();
     void toUTC_data() { toTimeSpec_data(); }
     void toUTC();
     void toUTC_extra();
+#endif
     void daysTo();
     void secsTo_data();
     void secsTo();
@@ -105,8 +111,10 @@ private Q_SLOTS:
 #endif
 
     void offsetFromUtc();
+#if QT_DEPRECATED_SINCE(6, 9)
     void setOffsetFromUtc();
     void toOffsetFromUtc();
+#endif
 
     void zoneAtTime_data();
     void zoneAtTime();
@@ -428,6 +436,9 @@ void tst_QDateTime::time()
     QCOMPARE(dt4.time(), QTime(0, 45, 57));
 }
 
+#if QT_DEPRECATED_SINCE(6, 9)
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
 void tst_QDateTime::timeSpec()
 {
     QDateTime dt1(QDate(2004, 1, 24), QTime(23, 45, 57));
@@ -450,6 +461,8 @@ void tst_QDateTime::timeSpec()
     QDateTime dt4 = QDateTime::currentDateTime();
     QCOMPARE(dt4.timeSpec(), Qt::LocalTime);
 }
+QT_WARNING_POP
+#endif
 
 void tst_QDateTime::setDate()
 {
@@ -577,6 +590,7 @@ void tst_QDateTime::setTimeZone()
     QCOMPARE(dateTime.timeRepresentation(), zone);
 }
 
+#if QT_DEPRECATED_SINCE(6, 9)
 void tst_QDateTime::setTimeSpec_data()
 {
     QTest::addColumn<QDateTime>("dateTime");
@@ -590,6 +604,8 @@ void tst_QDateTime::setTimeSpec_data()
         << QDateTime(QDate(2004, 3, 25), QTime(0, 45, 57), UTC) << Qt::OffsetFromUTC;
 }
 
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
 void tst_QDateTime::setTimeSpec()
 {
     QFETCH(QDateTime, dateTime);
@@ -607,6 +623,8 @@ void tst_QDateTime::setTimeSpec()
     else
         QCOMPARE(dateTime.timeSpec(), newTimeSpec);
 }
+QT_WARNING_POP
+#endif
 
 void tst_QDateTime::setSecsSinceEpoch()
 {
@@ -1597,6 +1615,7 @@ void tst_QDateTime::addMSecs()
     verify(dt.addDuration(std::chrono::milliseconds(nsecs * 1000)));
 }
 
+#if QT_DEPRECATED_SINCE(6, 9)
 void tst_QDateTime::toTimeSpec_data()
 {
     if (!zoneIsCET)
@@ -1665,6 +1684,8 @@ void tst_QDateTime::toTimeSpec_data()
         << QDateTime(QDate(4000, 6, 30), localDaylightTime.addMSecs(1));
 }
 
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
 void tst_QDateTime::toTimeSpec()
 {
     QFETCH(QDateTime, fromUtc);
@@ -1752,6 +1773,8 @@ void tst_QDateTime::toUTC_extra()
     QString t = dt.toUTC().toString("zzz");
     QCOMPARE(s, t);
 }
+QT_WARNING_POP
+#endif // 6.9 deprecation
 
 void tst_QDateTime::daysTo()
 {
@@ -3232,6 +3255,9 @@ void tst_QDateTime::offsetFromUtc()
 #endif
 }
 
+#if QT_DEPRECATED_SINCE(6, 9)
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
 void tst_QDateTime::setOffsetFromUtc()
 {
     /* Basic tests. */
@@ -3327,6 +3353,8 @@ void tst_QDateTime::toOffsetFromUtc()
     QCOMPARE(dt2.date(), QDate(2013, 1, 1));
     QCOMPARE(dt2.time(), QTime(0, 0));
 }
+QT_WARNING_POP
+#endif // 6.9 deprecation
 
 void tst_QDateTime::zoneAtTime_data()
 {