diff options
Diffstat (limited to 'src/corelib/tools/qdatetime.cpp')
| -rw-r--r-- | src/corelib/tools/qdatetime.cpp | 199 |
1 files changed, 103 insertions, 96 deletions
diff --git a/src/corelib/tools/qdatetime.cpp b/src/corelib/tools/qdatetime.cpp index 511dbf0db8..56f74135d4 100644 --- a/src/corelib/tools/qdatetime.cpp +++ b/src/corelib/tools/qdatetime.cpp @@ -329,19 +329,17 @@ static int fromOffsetString(const QStringRef &offsetString, bool *valid) Q_DECL_ \brief The QDate class provides date functions. - A QDate object encodes a calendar date, i.e. year, month, and day numbers, - in the proleptic Gregorian calendar by default. It can read the current date - from the system clock. It provides functions for comparing dates, and for - manipulating dates. For example, it is possible to add and subtract days, - months, and years to dates. + A QDate object represents a particular date. This can be expressed as a + calendar date, i.e. year, month, and day numbers, in the proleptic Gregorian + calendar. A QDate object is typically created by giving the year, month, and day - numbers explicitly. Note that QDate interprets two digit years as presented, - i.e., as years 0 through 99, without adding any offset. A QDate can also be - constructed with the static function currentDate(), which creates a QDate - object containing the system clock's date. An explicit date can also be set - using setDate(). The fromString() function returns a QDate given a string - and a date format which is used to interpret the date within the string. + numbers explicitly. Note that QDate interprets year numbers less than 100 as + presented, i.e., as years 1 through 99, without adding any offset. The + static function currentDate() creates a QDate object containing the date + read from the system clock. An explicit date can also be set using + setDate(). The fromString() function returns a QDate given a string and a + date format which is used to interpret the date within the string. The year(), month(), and day() functions provide access to the year, month, and day numbers. Also, dayOfWeek() and dayOfYear() @@ -375,7 +373,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 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, - 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 QDate::toJulianDay() and can be set using QDate::fromJulianDay(). @@ -1437,12 +1435,10 @@ bool QDate::isLeapYear(int y) Unlike QDateTime, QTime knows nothing about time zones or daylight-saving time (DST). - A QTime object is typically created either by giving the number - of hours, minutes, seconds, and milliseconds explicitly, or by - using the static function currentTime(), which creates a QTime - object that contains the system's local time. Note that the - accuracy depends on the accuracy of the underlying operating - system; not all systems provide 1-millisecond accuracy. + A QTime object is typically created either by giving the number of hours, + minutes, seconds, and milliseconds explicitly, or by using the static + function currentTime(), which creates a QTime object that represents the + system's local time. The hour(), minute(), second(), and msec() functions provide access to the number of hours, minutes, seconds, and milliseconds @@ -1902,6 +1898,12 @@ int QTime::msecsTo(const QTime &t) const Note that the accuracy depends on the accuracy of the underlying 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) @@ -3020,15 +3022,30 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT provides functions for comparing datetimes and for manipulating a datetime by adding a number of seconds, days, months, or years. - A QDateTime object is typically created either by giving a date - and time explicitly in the constructor, or by using the static - function currentDateTime() that returns a QDateTime object set - to the system clock's time. The date and time can be changed with - setDate() and setTime(). A datetime can also be set using the - setTime_t() function that takes a POSIX-standard "number of - seconds since 00:00:00 on January 1, 1970" value. The fromString() - function returns a QDateTime, given a string and a date format - used to interpret the date within the string. + 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 + 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 time parts of the datetime. The same information is provided in @@ -3039,18 +3056,20 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT later. You can increment (or decrement) a datetime by a given number of - milliseconds using addMSecs(), seconds using addSecs(), or days - using addDays(). Similarly, you can use addMonths() and addYears(). - The daysTo() function returns the number of days between two datetimes, - secsTo() returns the number of seconds between two datetimes, and - msecsTo() returns the number of milliseconds between two datetimes. - - QDateTime can store datetimes as \l{Qt::LocalTime}{local time} or - as \l{Qt::UTC}{UTC}. QDateTime::currentDateTime() returns a - QDateTime expressed as local time; use toUTC() to convert it to - UTC. You can also use timeSpec() to find out if a QDateTime - object stores a UTC time or a local time. Operations such as - addSecs() and secsTo() are aware of daylight-saving time (DST). + milliseconds using addMSecs(), seconds using addSecs(), or days using + addDays(). Similarly, you can use addMonths() and addYears(). The daysTo() + function returns the number of days between two datetimes, secsTo() returns + the number of seconds between two datetimes, and msecsTo() returns the + number of milliseconds between two datetimes. These operations are aware of + daylight-saving time (DST) and other time-zone transitions, where + applicable. + + Use toTimeSpec() to express a datetime in local time or UTC, + toOffsetFromUtc() to express in terms of an offset from UTC, or toTimeZone() + to express it with respect to a general time zone. You can use timeSpec() to + find out what time-spec a QDateTime object stores its time relative to. When + that is Qt::TimeZone, you can use timeZone() to find out which zone it is + using. \note QDateTime does not account for leap seconds. @@ -3064,67 +3083,55 @@ inline qint64 QDateTimePrivate::zoneMSecsToEpochMSecs(qint64 zoneMSecs, const QT \section2 Range of Valid Dates - The range of valid values able to be stored in QDateTime is dependent on - the internal storage implementation. QDateTime is currently stored in a - qint64 as a serial msecs value encoding the date and time. This restricts - the date range to about +/- 292 million years, compared to the QDate range - of +/- 2 billion years. Care must be taken when creating a QDateTime with - extreme values that you do not overflow the storage. The exact range of - supported values varies depending on the Qt::TimeSpec and time zone. + The range of values that QDateTime can represent is dependent on the + internal storage implementation. QDateTime is currently stored in a qint64 + as a serial msecs value encoding the date and time. This restricts the date + range to about +/- 292 million years, compared to the QDate range of +/- 2 + billion years. Care must be taken when creating a QDateTime with extreme + values that you do not overflow the storage. The exact range of supported + values varies depending on the Qt::TimeSpec and time zone. + + \section2 Use of Timezones + + QDateTime uses the system's time zone information to determine the current + 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. - \section2 Use of System Timezone + 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. - QDateTime uses the system's time zone information to determine the - offset of local time from UTC. If the system is not configured - correctly or not up-to-date, QDateTime will give wrong results as - well. + 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) - QDateTime takes into account the system's time zone information - when dealing with DST. On modern Unix systems, this means it - applies the correct historical DST data whenever possible. On - Windows, where the system doesn't support historical DST data, - historical accuracy is not maintained with respect to DST. - - 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 locale's - time zone before 1970, even if the system's time zone database - supports that information. - - QDateTime takes into consideration the Standard Time to Daylight-Saving Time - 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 - - A Qt::TimeSpec of Qt::OffsetFromUTC is also supported. This allows you - to define a QDateTime relative to UTC at a fixed offset of a given number - of seconds from UTC. For example, an offset of +3600 seconds is one hour - 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. + QDateTime takes into account transitions between Standard Time and + Daylight-Saving Time. 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 arithmetic + 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 + 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. + + \section2 Offsets 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 + which use a [+|-]hh:mm format, 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. \sa QDate, QTime, QDateTimeEdit, QTimeZone */ @@ -4247,7 +4254,7 @@ qint64 QDateTime::msecsTo(const QDateTime &other) const Example: \snippet code/src_corelib_tools_qdatetime.cpp 16 - \sa timeSpec(), toTimeZone(), toUTC(), toLocalTime() + \sa timeSpec(), toTimeZone(), toOffsetFromUtc() */ QDateTime QDateTime::toTimeSpec(Qt::TimeSpec spec) const |