AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Overhaul Q(Date|Time)+ documentation

Browse Source 
Various things were out of date, misdescribed or just plain wrong.

Change-Id: I11b7bd419604067fce2577a42882ebf126629016
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
This commit is contained in:
Edward Welbourne 2019-05-24 14:20:43 +02:00
parent 8c7589d992
commit ff4ef79e0d
1 changed files with 99 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -326,19 +326,17 @@ static int fromOffsetString(const QStringRef &offsetString, bool *valid) Q_DECL_
\brief The QDate class provides date functions. \brief The QDate class provides date functions.
A QDate object encodes a calendar date, i.e. year, month, and day numbers, A QDate object represents a particular date. This can be expressed as a
in the proleptic Gregorian calendar by default. It can read the current date calendar date, i.e. year, month, and day numbers, in the proleptic Gregorian
from the system clock. It provides functions for comparing dates, and for calendar.
manipulating dates. For example, it is possible to add and subtract days,
months, and years to dates.
A QDate object is typically created by giving the year, month, and day A QDate object is typically created by giving the year, month, and day
numbers explicitly. Note that QDate interprets two digit years as presented, numbers explicitly. Note that QDate interprets year numbers less than 100 as
i.e., as years 0 through 99, without adding any offset. A QDate can also be presented, i.e., as years 1 through 99, without adding any offset. The
constructed with the static function currentDate(), which creates a QDate static function currentDate() creates a QDate object containing the date
object containing the system clock's date. An explicit date can also be set read from the system clock. An explicit date can also be set using
using setDate(). The fromString() function returns a QDate given a string setDate(). The fromString() function returns a QDate given a string and a
and a date format which is used to interpret the date within the string. date format which is used to interpret the date within the string.
The year(), month(), and day() functions provide access to the The year(), month(), and day() functions provide access to the
year, month, and day numbers. Also, dayOfWeek() and dayOfYear() year, month, and day numbers. Also, dayOfWeek() and dayOfYear()
@ -372,7 +370,7 @@ static int fromOffsetString(const QStringRef &offsetString, bool *valid) Q_DECL_
every day in a contiguous range, with 24 November 4714 BCE in the Gregorian every day in a contiguous range, with 24 November 4714 BCE in the Gregorian
calendar being Julian Day 0 (1 January 4713 BCE in the Julian calendar). calendar being Julian Day 0 (1 January 4713 BCE in the Julian calendar).
As well as being an efficient and accurate way of storing an absolute date, As well as being an efficient and accurate way of storing an absolute date,
it is suitable for converting a Date into other calendar systems such as it is suitable for converting a date into other calendar systems such as
Hebrew, Islamic or Chinese. The Julian Day number can be obtained using Hebrew, Islamic or Chinese. The Julian Day number can be obtained using
QDate::toJulianDay() and can be set using QDate::fromJulianDay(). QDate::toJulianDay() and can be set using QDate::fromJulianDay().
@ -1434,12 +1432,10 @@ bool QDate::isLeapYear(int y)
Unlike QDateTime, QTime knows nothing about time zones or Unlike QDateTime, QTime knows nothing about time zones or
daylight-saving time (DST). daylight-saving time (DST).
A QTime object is typically created either by giving the number A QTime object is typically created either by giving the number of hours,
of hours, minutes, seconds, and milliseconds explicitly, or by minutes, seconds, and milliseconds explicitly, or by using the static
using the static function currentTime(), which creates a QTime function currentTime(), which creates a QTime object that represents the
object that contains the system's local time. Note that the system's local time.
accuracy depends on the accuracy of the underlying operating
system; not all systems provide 1-millisecond accuracy.
The hour(), minute(), second(), and msec() functions provide The hour(), minute(), second(), and msec() functions provide
access to the number of hours, minutes, seconds, and milliseconds access to the number of hours, minutes, seconds, and milliseconds
@ -1899,6 +1895,12 @@ int QTime::msecsTo(const QTime &t) const
Note that the accuracy depends on the accuracy of the underlying Note that the accuracy depends on the accuracy of the underlying
operating system; not all systems provide 1-millisecond accuracy. operating system; not all systems provide 1-millisecond accuracy.
Furthermore, currentTime() only increases within each day; it shall drop by
24 hours each time midnight passes; and, beside this, changes in it may not
correspond to elapsed time, if a daylight-saving transition intervenes.
\sa QDateTime::currentDateTime(), QDateTime::curentDateTimeUtc()
*/ */
#if QT_CONFIG(datestring) #if QT_CONFIG(datestring)
@ -3027,15 +3029,30 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT
provides functions for comparing datetimes and for manipulating a provides functions for comparing datetimes and for manipulating a
datetime by adding a number of seconds, days, months, or years. datetime by adding a number of seconds, days, months, or years.
A QDateTime object is typically created either by giving a date QDateTime can describe datetimes with respect to \l{Qt::LocalTime}{local
and time explicitly in the constructor, or by using the static time}, to \l{Qt::UTC}{UTC}, to a specified \l{{Qt::OffsetFromUTC}{offset
function currentDateTime() that returns a QDateTime object set from UTC} or to a specified \l{{Qt::TimeZone}{time zone}, in conjunction
to the system clock's time. The date and time can be changed with with the QTimeZone class. For example, a time zone of "Europe/Berlin" will
setDate() and setTime(). A datetime can also be set using the apply the daylight-saving rules as used in Germany since 1970. In contrast,
setTime_t() function that takes a POSIX-standard "number of an offset from UTC of +3600 seconds is one hour ahead of UTC (usually
seconds since 00:00:00 on January 1, 1970" value. The fromString() written in ISO standard notation as "UTC+01:00"), with no daylight-saving
function returns a QDateTime, given a string and a date format offset or changes. When using either local time or a specified time zone,
used to interpret the date within the string. 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
datetime is described as its "timespec".
A QDateTime object is typically created either by giving a date and time
explicitly in the constructor, or by using a static function such as
currentDateTime() or fromMSecsSinceEpoch(). The date and time can be changed
with setDate() and setTime(). A datetime can also be set using the
setMSecsSinceEpoch() function that takes the time, in milliseconds, since
00:00:00 on January 1, 1970. The fromString() function returns a QDateTime,
given a string and a date format used to interpret the date within the
string.
QDateTime::currentDateTime() returns a QDateTime that expresses the current
time with respect to local time. QDateTime::currentDateTimeUtc() returns a
QDateTime that expresses the current time with respect to UTC.
The date() and time() functions provide access to the date and The date() and time() functions provide access to the date and
time parts of the datetime. The same information is provided in time parts of the datetime. The same information is provided in
@ -3046,18 +3063,20 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT
later. later.
You can increment (or decrement) a datetime by a given number of You can increment (or decrement) a datetime by a given number of
milliseconds using addMSecs(), seconds using addSecs(), or days milliseconds using addMSecs(), seconds using addSecs(), or days using
using addDays(). Similarly, you can use addMonths() and addYears(). addDays(). Similarly, you can use addMonths() and addYears(). The daysTo()
The daysTo() function returns the number of days between two datetimes, function returns the number of days between two datetimes, secsTo() returns
secsTo() returns the number of seconds between two datetimes, and the number of seconds between two datetimes, and msecsTo() returns the
msecsTo() returns the number of milliseconds between two datetimes. number of milliseconds between two datetimes. These operations are aware of
daylight-saving time (DST) and other time-zone transitions, where
applicable.
QDateTime can store datetimes as \l{Qt::LocalTime}{local time} or Use toTimeSpec() to express a datetime in local time or UTC,
as \l{Qt::UTC}{UTC}. QDateTime::currentDateTime() returns a toOffsetFromUtc() to express in terms of an offset from UTC, or toTimeZone()
QDateTime expressed as local time; use toUTC() to convert it to to express it with respect to a general time zone. You can use timeSpec() to
UTC. You can also use timeSpec() to find out if a QDateTime find out what time-spec a QDateTime object stores its time relative to. When
object stores a UTC time or a local time. Operations such as that is Qt::TimeZone, you can use timeZone() to find out which zone it is
addSecs() and secsTo() are aware of daylight-saving time (DST). using.
\note QDateTime does not account for leap seconds. \note QDateTime does not account for leap seconds.
@ -3071,67 +3090,55 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT
\section2 Range of Valid Dates \section2 Range of Valid Dates
The range of valid values able to be stored in QDateTime is dependent on The range of values that QDateTime can represent is dependent on the
the internal storage implementation. QDateTime is currently stored in a internal storage implementation. QDateTime is currently stored in a qint64
qint64 as a serial msecs value encoding the date and time. This restricts as a serial msecs value encoding the date and time. This restricts the date
the date range to about +/- 292 million years, compared to the QDate range range to about +/- 292 million years, compared to the QDate range of +/- 2
of +/- 2 billion years. Care must be taken when creating a QDateTime with billion years. Care must be taken when creating a QDateTime with extreme
extreme values that you do not overflow the storage. The exact range of values that you do not overflow the storage. The exact range of supported
supported values varies depending on the Qt::TimeSpec and time zone. values varies depending on the Qt::TimeSpec and time zone.
\section2 Use of System Timezone \section2 Use of Timezones
QDateTime uses the system's time zone information to determine the QDateTime uses the system's time zone information to determine the current
offset of local time from UTC. If the system is not configured local time zone and its offset from UTC. If the system is not configured
correctly or not up-to-date, QDateTime will give wrong results as correctly or not up-to-date, QDateTime will give wrong results.
well.
QDateTime likewise uses system-provided information to determine the offsets
of other timezones from UTC. If this information is incomplete or out of
date, QDateTime will give wrong results. See the QTimeZone documentation for
more details.
On modern Unix systems, this means QDateTime usually has accurate
information about historical transitions (including DST, see below) whenever
possible. On Windows, where the system doesn't support historical timezone
data, historical accuracy is not maintained with respect to timezone
transitions, notably including DST.
\section2 Daylight-Saving Time (DST) \section2 Daylight-Saving Time (DST)
QDateTime takes into account the system's time zone information QDateTime takes into account transitions between Standard Time and
when dealing with DST. On modern Unix systems, this means it Daylight-Saving Time. For example, if the transition is at 2am and the clock
applies the correct historical DST data whenever possible. On goes forward to 3am, then there is a "missing" hour from 02:00:00 to
Windows, where the system doesn't support historical DST data, 02:59:59.999 which QDateTime considers to be invalid. Any date arithmetic
historical accuracy is not maintained with respect to DST. performed will take this missing hour into account and return a valid
result. For example, adding one minute to 01:59:59 will get 03:00:00.
The range of valid dates taking DST into account is 1970-01-01 to The range of valid dates taking DST into account is 1970-01-01 to the
the present, and rules are in place for handling DST correctly present, and rules are in place for handling DST correctly until 2037-12-31,
until 2037-12-31, but these could change. For dates falling but these could change. For dates falling outside that range, QDateTime
outside that range, QDateTime makes a \e{best guess} using the makes a \e{best guess} using the rules for year 1970 or 2037, but we can't
rules for year 1970 or 2037, but we can't guarantee accuracy. This guarantee accuracy. This means QDateTime doesn't take into account changes
means QDateTime doesn't take into account changes in a locale's in a time zone before 1970, even if the system's time zone database provides
time zone before 1970, even if the system's time zone database that information.
supports that information.
QDateTime takes into consideration the Standard Time to Daylight-Saving Time \section2 Offsets From UTC
transition. For example if the transition is at 2am and the clock goes
forward to 3am, then there is a "missing" hour from 02:00:00 to 02:59:59.999
which QDateTime considers to be invalid. Any date maths performed
will take this missing hour into account and return a valid result.
\section2 Offset From UTC There is no explicit size restriction on an offset from UTC, but there is an
implicit limit imposed when using the toString() and fromString() methods
A Qt::TimeSpec of Qt::OffsetFromUTC is also supported. This allows you which use a [+|-]hh:mm format, effectively limiting the range to +/- 99
to define a QDateTime relative to UTC at a fixed offset of a given number hours and 59 minutes and whole minutes only. Note that currently no time
of seconds from UTC. For example, an offset of +3600 seconds is one hour zone lies outside the range of +/- 14 hours.
ahead of UTC and is usually written in ISO standard notation as
"UTC+01:00". Daylight-Saving Time never applies with this TimeSpec.
There is no explicit size restriction to the offset seconds, but there is
an implicit limit imposed when using the toString() and fromString()
methods which use a format of [+|-]hh:mm, effectively limiting the range
to +/- 99 hours and 59 minutes and whole minutes only. Note that currently
no time zone lies outside the range of +/- 14 hours.
\section2 Time Zone Support
A Qt::TimeSpec of Qt::TimeZone is also supported in conjunction with the
QTimeZone class. This allows you to define a datetime in a named time zone
adhering to a consistent set of daylight-saving transition rules. For
example a time zone of "Europe/Berlin" will apply the daylight-saving
rules as used in Germany since 1970. Note that the transition rules
applied depend on the platform support. See the QTimeZone documentation
for more details.
\sa QDate, QTime, QDateTimeEdit, QTimeZone \sa QDate, QTime, QDateTimeEdit, QTimeZone
*/ */
@ -4254,7 +4261,7 @@ qint64 QDateTime::msecsTo(const QDateTime &other) const
Example: Example:
\snippet code/src_corelib_tools_qdatetime.cpp 16 \snippet code/src_corelib_tools_qdatetime.cpp 16
\sa timeSpec(), toTimeZone(), toUTC(), toLocalTime() \sa timeSpec(), toTimeZone(), toOffsetFromUtc()
*/ */
QDateTime QDateTime::toTimeSpec(Qt::TimeSpec spec) const QDateTime QDateTime::toTimeSpec(Qt::TimeSpec spec) const