From c6bde29e143b1fadac97f656ba6c3059135d4a11 Mon Sep 17 00:00:00 2001 From: Edward Welbourne Date: Mon, 9 Sep 2019 16:20:47 +0200 Subject: Doc-fix: correct some misinformation about QDateTime's handling of DST Tidy up QDateTime::offsetFromUtc's doc, in the process. We don't take DST into account for dates before the epoch; that should be mentioned when saying we take DST into account. Also, referring to *this as the "current" time begs to be misunderstood. The \class comment also misleadingly claimed that we don't take into account any changes to time-zone before DST; where, in fact, we only ignore DST changes before 1970, not changes to standard offset. Change-Id: I090e668edf0338c825f5afcc67f894579a129c46 Reviewed-by: Paul Wicking --- src/corelib/time/qdatetime.cpp | 53 ++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 23 deletions(-) (limited to 'src/corelib') diff --git a/src/corelib/time/qdatetime.cpp b/src/corelib/time/qdatetime.cpp index 8b1665e7dd..13a54c1210 100644 --- a/src/corelib/time/qdatetime.cpp +++ b/src/corelib/time/qdatetime.cpp @@ -3432,15 +3432,15 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT datetime by adding a number of seconds, days, months, or years. QDateTime can describe datetimes with respect to \l{Qt::LocalTime}{local - time}, to \l{Qt::UTC}{UTC}, to a specified \l{Qt::OffsetFromUTC}{offset - from UTC} or to a specified \l{Qt::TimeZone}{time zone}, in conjunction - with the QTimeZone class. For example, a time zone of "Europe/Berlin" will - apply the daylight-saving rules as used in Germany since 1970. In contrast, - an offset from UTC of +3600 seconds is one hour ahead of UTC (usually - written in ISO standard notation as "UTC+01:00"), with no daylight-saving - offset or changes. When using either local time or a specified time zone, - time-zone transitions such as the starts and ends of daylight-saving time - (DST) are taken into account. The choice of system used to represent a + time}, to \l{Qt::UTC}{UTC}, to a specified \l{Qt::OffsetFromUTC}{offset from + UTC} or to a specified \l{Qt::TimeZone}{time zone}, in conjunction with the + QTimeZone class. For example, a time zone of "Europe/Berlin" will apply the + daylight-saving rules as used in Germany since 1970. In contrast, an offset + from UTC of +3600 seconds is one hour ahead of UTC (usually written in ISO + standard notation as "UTC+01:00"), with no daylight-saving offset or + changes. When using either local time or a specified time zone, time-zone + transitions such as the starts and ends of daylight-saving time (DST; but + see below) are taken into account. The choice of system used to represent a datetime is described as its "timespec". A QDateTime object is typically created either by giving a date and time @@ -3528,11 +3528,13 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT The range of valid dates taking DST into account is 1970-01-01 to the present, and rules are in place for handling DST correctly until 2037-12-31, - but these could change. For dates falling outside that range, QDateTime - makes a \e{best guess} using the rules for year 1970 or 2037, but we can't - guarantee accuracy. This means QDateTime doesn't take into account changes - in a time zone before 1970, even if the system's time zone database provides - that information. + but these could change. For dates after 2037, QDateTime makes a \e{best + guess} using the rules for year 2037, but we can't guarantee accuracy; + indeed, for \e{any} future date, the time-zone may change its rules before + that date comes around. For dates before 1970, QDateTime doesn't take DST + changes into account, even if the system's time zone database provides that + information, although it does take into account changes to the time-zone's + standard offset, where this information is available. \section2 Offsets From UTC @@ -3797,17 +3799,22 @@ QTimeZone QDateTime::timeZone() const /*! \since 5.2 - Returns the current Offset From UTC in seconds. + Returns this date-time's Offset From UTC in seconds. - If the timeSpec() is Qt::OffsetFromUTC this will be the value originally set. - - If the timeSpec() is Qt::TimeZone this will be the offset effective in the - Time Zone including any Daylight-Saving Offset. - - If the timeSpec() is Qt::LocalTime this will be the difference between the - Local Time and UTC including any Daylight-Saving Offset. + The result depends on timeSpec(): + \list + \li \c Qt::UTC The offset is 0. + \li \c Qt::OffsetFromUTC The offset is the value originally set. + \li \c Qt::LocalTime The local time's offset from UTC is returned. + \li \c Qt::TimeZone The offset used by the time-zone is returned. + \endlist - If the timeSpec() is Qt::UTC this will be 0. + For the last two, the offset at this date and time will be returned, taking + account of Daylight-Saving Offset unless the date precedes the start of + 1970. The offset is the difference between the local time or time in the + given time-zone and UTC time; it is positive in time-zones ahead of UTC + (East of The Prime Meridian), negative for those behind UTC (West of The + Prime Meridian). \sa setOffsetFromUtc() */ -- cgit v1.2.3