1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc-fix: correct some misinformation about QDateTime's handling of DST

Browse Source 
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.
(Conflict resolution also pulled in a typo-fix from 5.14.)

Change-Id: I090e668edf0338c825f5afcc67f894579a129c46
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit c6bde29e143b1fadac97f656ba6c3059135d4a11)
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
This commit is contained in:
Edward Welbourne 2019-09-09 16:20:47 +02:00
parent 3a71e387d9
commit b207332b93
1 changed files with 30 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
src/corelib/tools/qdatetime.cpp
View File

@ -3028,15 +3028,15 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT
datetime by adding a number of seconds, days, months, or years. datetime by adding a number of seconds, days, months, or years.
QDateTime can describe datetimes with respect to \l{Qt::LocalTime}{local QDateTime can describe datetimes with respect to \l{Qt::LocalTime}{local
time}, to \l{Qt::UTC}{UTC}, to a specified \l{Qt::OffsetFromUTC}{offset time}, to \l{Qt::UTC}{UTC}, to a specified \l{Qt::OffsetFromUTC}{offset from
from UTC} or to a specified \l{{Qt::TimeZone}{time zone}, in conjunction UTC} or to a specified \l{Qt::TimeZone}{time zone}, in conjunction with the
with the QTimeZone class. For example, a time zone of "Europe/Berlin" will QTimeZone class. For example, a time zone of "Europe/Berlin" will apply the
apply the daylight-saving rules as used in Germany since 1970. In contrast, daylight-saving rules as used in Germany since 1970. In contrast, an offset
an offset from UTC of +3600 seconds is one hour ahead of UTC (usually from UTC of +3600 seconds is one hour ahead of UTC (usually written in ISO
written in ISO standard notation as "UTC+01:00"), with no daylight-saving standard notation as "UTC+01:00"), with no daylight-saving offset or
offset or changes. When using either local time or a specified time zone, changes. When using either local time or a specified time zone, time-zone
time-zone transitions such as the starts and ends of daylight-saving time transitions such as the starts and ends of daylight-saving time (DST; but
(DST) are taken into account. The choice of system used to represent a see below) are taken into account. The choice of system used to represent a
datetime is described as its "timespec". datetime is described as its "timespec".
A QDateTime object is typically created either by giving a date and time A QDateTime object is typically created either by giving a date and time
@ -3124,11 +3124,13 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT
The range of valid dates taking DST into account is 1970-01-01 to the 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, 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 but these could change. For dates after 2037, QDateTime makes a \e{best
makes a \e{best guess} using the rules for year 1970 or 2037, but we can't guess} using the rules for year 2037, but we can't guarantee accuracy;
guarantee accuracy. This means QDateTime doesn't take into account changes indeed, for \e{any} future date, the time-zone may change its rules before
in a time zone before 1970, even if the system's time zone database provides that date comes around. For dates before 1970, QDateTime doesn't take DST
that information. 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 \section2 Offsets From UTC
@ -3374,17 +3376,22 @@ QTimeZone QDateTime::timeZone() const
/*! /*!
\since 5.2 \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. 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::TimeZone this will be the offset effective in the For the last two, the offset at this date and time will be returned, taking
Time Zone including any Daylight-Saving Offset. 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
If the timeSpec() is Qt::LocalTime this will be the difference between the given time-zone and UTC time; it is positive in time-zones ahead of UTC
Local Time and UTC including any Daylight-Saving Offset. (East of The Prime Meridian), negative for those behind UTC (West of The
Prime Meridian).
If the timeSpec() is Qt::UTC this will be 0.
\sa setOffsetFromUtc() \sa setOffsetFromUtc()
*/ */