QDateTime Class

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 time representation used.

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.

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. However, building Qt with the ICU library will equip QTimeZone with the same timezone database as is used on Unix.

QDateTime takes into account timezone transitions, both the transitions between Standard Time and Daylight-Saving Time (DST) and the transitions that arise when a zone changes its standard offset. 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. Such a transition is known as a "spring forward" and the times skipped over have no meaning. When a transition goes the other way, known as a "fall back", a time interval is repeated, first in the old zone (usually DST), then in the new zone (usually Standard Time), so times in this interval are ambiguous.

Some zones use "reversed" DST, using standard time in summer and daylight-saving time (with a lowered offset) in winter. For such zones, the spring forward still happens in spring and skips an hour, but is a transition out of daylight-saving time, while the fall back still repeats an autumn hour but is a transition to daylight-saving time.

When converting from a UTC time (or a time at fixed offset from UTC), there is always an unambiguous valid result in any timezone. However, when combining a date and time to make a datetime, expressed with respect to local time or a specific time-zone, the nominal result may fall in a transition, making it either invalid or ambiguous. Methods where this situation may arise take a resolve parameter: this is always ignored if the requested datetime is valid and unambiguous. See TransitionResolution for the options it lets you control. Prior to Qt 6.7, the equivalent of its LegacyBehavior was selected.

For a spring forward's skipped interval, interpreting the requested time with either offset yields an actual time at which the other offset was in use; so passing TransitionResolution::RelativeToBefore for resolve will actually result in a time after the transition, that would have had the requested representation had the transition not happened. Likewise, TransitionResolution::RelativeToAfter for resolve results in a time before the transition, that would have had the requested representation, had the transition happened earlier.

When QDateTime performs arithmetic, as with addDay() or addSecs(), it takes care to produce a valid result. For example, on a day when there is a spring forward from 02:00 to 03:00, adding one second to 01:59:59 will get 03:00:00. Adding one day to 02:30 on the preceding day will get 03:30 on the day of the transition, while subtracting one day, by calling addDay(-1), to 02:30 on the following day will get 01:30 on the day of the transition. While addSecs() will deliver a time offset by the given number of seconds, addDays() adjusts the date and only adjusts time if it would otherwise get an invalid result. Applying addDays(1) to 03:00 on the day before the spring-forward will simply get 03:00 on the day of the transition, even though the latter is only 23 hours after the former; but addSecs(24 * 60 * 60) will get 04:00 on the day of the transition, since that's 24 hours later. Typical transitions make some days 23 or 25 hours long.

For datetimes that the system time_t can represent (from 1901-12-14 to 2038-01-18 on systems with 32-bit time_t; for the full range QDateTime can represent if the type is 64-bit), the standard system APIs are used to determine local time's offset from UTC. For datetimes not handled by these system APIs (potentially including some within the time_t range), QTimeZone::systemTimeZone() is used, if available, or a best effort is made to estimate. In any case, the offset information used depends on the system and may be incomplete or, for past times, historically inaccurate. Furthermore, for future dates, the local time zone's offsets and DST rules may change before that date comes around.

Whole day transitions▲

Offsets from UTC are measured in seconds east of Greenwich. The moment described by a particular date and time, such as noon on a particular day, depends on the time representation used. Those with a higher offset from UTC describe an earlier moment, and those with a lower offset a later moment, by any given combination of date and time.

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 has an offset outside the range of ±14 hours and all known offsets are multiples of five minutes. Historical time zones have a wider range and may have offsets including seconds; these last cannot be faithfully represented in strings.