Move YearRange to QDateTime from its Private

As planned when adding YearRange: now that it's merged up to dev, move
it to QDateTime, since we can add to the API at 5.14.0.

This follows up on commit 82ad4be4a2.

Change-Id: I81b6c2331121a71e2592514781c02c5756e70c52
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

src/corelib/time/qdatetime.cpp

@@ -386,7 +386,7 @@ static constexpr int daysInUsualMonth(int month) // (February isn't usual.)
     for technical reasons limited to between -784350574879 and 784354017364,
     which means from before 2 billion BCE to after 2 billion CE.
 
-    \sa QTime, QDateTime, QDateEdit, QDateTimeEdit, QCalendarWidget
+    \sa QTime, QDateTime, QDateTime::YearRange, QDateEdit, QDateTimeEdit, QCalendarWidget
 */
 
 /*!
@@ -3387,6 +3387,25 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT
     \sa QDate, QTime, QDateTimeEdit, QTimeZone
 */
 
+/*!
+    \enum QDateTime::YearRange
+
+    This enumerated type describes the range of years (in the Gregorian
+    calendar) representable by QDateTime:
+
+    \value First The later parts of this year are representable
+    \value Last The earlier parts of this year are representable
+
+    All dates strictly between these two years are also representable.
+    Note, however, that the Gregorian Calendar has no year zero.
+
+    \note QDate can describe dates in a wider range of years.  For most
+    purposes, this makes little difference, as the range of years that QDateTime
+    can support reaches 292 million years either side of 1970.
+
+    \sa isValid(), QDate
+*/
+
 /*!
     Constructs a null datetime (i.e. null date and null time). A null
     datetime is invalid, since the date is invalid.
@@ -3535,7 +3554,7 @@ bool QDateTime::isNull() const
     hour, i.e. if the transition is at 2am and the clock goes forward to 3am
     then the time from 02:00:00 to 02:59:59.999 is considered to be invalid.
 
-    \sa QDate::isValid(), QTime::isValid()
+    \sa QDateTime::YearRange, QDate::isValid(), QTime::isValid()
 */
 
 bool QDateTime::isValid() const

src/corelib/time/qdatetime.h

@@ -384,6 +384,10 @@ public:
     NSDate *toNSDate() const Q_DECL_NS_RETURNS_AUTORELEASED;
 #endif
 
+    // (1<<63) ms is 292277024.6 (average Gregorian) years, counted from the start of 1970, so
+    // Last is floor(1970 + 292277024.6); no year 0, so First is floor(1970 - 1 - 292277024.6)
+    enum class YearRange : qint32 { First = -292275056,  Last = +292278994 };
+
 private:
     friend class QDateTimePrivate;
 

src/corelib/time/qdatetime_p.h

@@ -140,10 +140,6 @@ public:
     // Inlined for its one caller in qdatetime.cpp
     inline void setUtcOffsetByTZ(qint64 atMSecsSinceEpoch);
 #endif // timezone
-
-    // ### Qt 5.14: expose publicly in QDateTime
-    // The first and last years of which QDateTime can represent some part:
-    enum class YearRange : qint32 { First = -292275056,  Last = +292278994 };
 };
 
 QT_END_NAMESPACE

src/corelib/time/qtimezoneprivate_tz.cpp

@@ -39,7 +39,6 @@
 
 #include "qtimezone.h"
 #include "qtimezoneprivate_p.h"
-#include "qdatetime_p.h" // ### Qt 5.14: remove once YearRange is on QDateTime
 #include "private/qlocale_tools_p.h"
 
 #include <QtCore/QFile>
@@ -589,8 +588,8 @@ static QVector<QTimeZonePrivate::Data> calculatePosixTransitions(const QByteArra
         stdTime = QTime(2, 0, 0);
 
     // Limit year to the range QDateTime can represent:
-    const int minYear = int(QDateTimePrivate::YearRange::First);
+    const int minYear = int(QDateTime::YearRange::First);
-    const int maxYear = int(QDateTimePrivate::YearRange::Last);
+    const int maxYear = int(QDateTime::YearRange::Last);
     startYear = qBound(minYear, startYear, maxYear);
     endYear = qBound(minYear, endYear, maxYear);
     Q_ASSERT(startYear <= endYear);

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

@@ -147,6 +147,7 @@ private slots:
     void systemTimeZoneChange() const;
 
     void invalid() const;
+    void range() const;
 
     void macTypes();
 
@@ -3475,6 +3476,15 @@ void tst_QDateTime::invalid() const
     QCOMPARE(tzDate.timeSpec(), Qt::TimeZone);
 }
 
+void tst_QDateTime::range() const
+{
+    using Bounds = std::numeric_limits<qint64>;
+    QCOMPARE(QDateTime::fromMSecsSinceEpoch(Bounds::min() + 1, Qt::UTC).date().year(),
+             int(QDateTime::YearRange::First));
+    QCOMPARE(QDateTime::fromMSecsSinceEpoch(Bounds::max() - 1, Qt::UTC).date().year(),
+             int(QDateTime::YearRange::Last));
+}
+
 void tst_QDateTime::macTypes()
 {
 #ifndef Q_OS_MAC