QTimeZone Class

QTimeZone identifies how a time representation relates to UTC. More...

Header: #include <QTimeZone>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

This class is equality-comparable.

Note: All functions in this class are thread-safe.

Public Types

(since 6.5) enum Initialization { LocalTime, UTC }

Public Functions

QTimeZone()
(since 6.5) QTimeZone(QTimeZone::Initialization spec)
QTimeZone(const QTimeZone &other)
QTimeZone(QTimeZone &&other)
~QTimeZone()
(since 6.5) int fixedSecondsAheadOfUtc() const
(since 6.5) bool isUtcOrFixedOffset() const
bool isValid() const
void swap(QTimeZone &other)
(since 6.5) Qt::TimeSpec timeSpec() const
QTimeZone &operator=(QTimeZone &&other)
QTimeZone &operator=(const QTimeZone &other)

Static Public Members

const int MaxUtcOffsetSecs
const int MinUtcOffsetSecs
(since 6.5) QTimeZone fromDurationAheadOfUtc(std::chrono::seconds offset)
(since 6.5) QTimeZone fromSecondsAheadOfUtc(int offset)
(since 6.5) bool isUtcOrFixedOffset(Qt::TimeSpec spec)
bool operator!=(const QTimeZone &lhs, const QTimeZone &rhs)
bool operator==(const QTimeZone &lhs, const QTimeZone &rhs)

Detailed Description

When dates and times are combined, the meaning of the result depends on how time is being represented. There are various international standards for representing time; one of these, UTC, corresponds to the traditional standard of solar mean time at Greenwich (a.k.a. GMT). All other time systems supported by Qt are ultimately specified in relation to UTC. An instance of this class provides a stateless calculator for conversions between UTC and other time representations.

Some time representations are simply defined at a fixed offset to UTC. Others are defined by governments for use within their jurisdictions. The latter are properly known as time zones, but QTimeZone (since Qt 6.5) is unifies their representation with that of general time systems. One time zone generally supported on most operating systems is designated local time; this is presumed to correspond to the time zone within which the user is living.

For time zones other than local time, UTC and those at fixed offsets from UTC, Qt can only provide support when the operating system provides some way to access that information. When Qt is built, the timezone feature controls whether such information is available. When it is not, some constructors and methods of QTimeZone are excluded from its API; these are documented as depending on feature timezone. Note that, even when Qt is built with this feature enabled, it may be unavailable to users whose systems are misconfigured, or where some standard packages (for example, the tzdata package on Linux) are not installed. This feature is enabled by default when time zone information is available.

This class is primarily designed for use in QDateTime; most applications will not need to access this class directly and should instead use an instance of it when constructing a QDateTime.

Note: For consistency with QDateTime, QTimeZone does not account for leap seconds.

Remarks

QTimeZone, like QDateTime, measures offsets from UTC in seconds. This contrasts with their measurement of time generally, which they do in milliseconds. Real-world time zones generally have UTC offsets that are whole-number multiples of five minutes (300 seconds), at least since well before 1970. A positive offset from UTC gives a time representation puts noon on any given day before UTC noon on that day; a negative offset puts noon after UTC noon on the same day.

Lightweight Time Representations

QTimeZone can represent UTC, local time and fixed offsets from UTC even when feature timezone is disabled. The form in which it does so is also available when the feature is enabled; it is a more lightweight form and processing using it will typically be more efficient, unless methods only available when feature timezone is enabled are being exercised. See Initialization and QTimeZone::fromSecondsAheadOfUtc(int) for how to construct these representations.

This documentation distinguishes between "time zone", used to describe a time representation described by system-supplied or standard information, and time representations more generally, which include these lightweight forms. The methods available only when feature timezone is enabled are apt to be cheaper for time zones than for lightweight time representations, for which these methods may construct a suitable transient time zone object to which to forward the query.

IANA Time Zone IDs

QTimeZone uses the IANA time zone IDs as defined in the IANA Time Zone Database (http://www.iana.org/time-zones). This is to ensure a standard ID across all supported platforms. Most platforms support the IANA IDs and the IANA Database natively, but for Windows a mapping is required to the native IDs. See below for more details.

The IANA IDs can and do change on a regular basis, and can vary depending on how recently the host system data was updated. As such you cannot rely on any given ID existing on any host system. You must use availableTimeZoneIds() to determine what IANA IDs are available.

The IANA IDs and database are also know as the Olson IDs and database, named after the original compiler of the database.

UTC Offset Time Zones

A default UTC time zone backend is provided which is always available when feature timezone is enabled. This provides a set of generic Offset From UTC time zones in the range UTC-16:00 to UTC+16:00. These time zones can be created using either the standard ISO format names, such as "UTC+00:00", as listed by availableTimeZoneIds(), or using a name of similar form in combination with the number of offset seconds.

Windows Time Zones

Windows native time zone support is severely limited compared to the standard IANA TZ Database. Windows time zones cover larger geographic areas and are thus less accurate in their conversions. They also do not support as much historical data and so may only be accurate for the current year. In particular, when MS's zone data claims that DST was observed prior to 1900 (this is historically known to be untrue), the claim is ignored and the standard time (allegedly) in force in 1900 is taken to have always been in effect.

QTimeZone uses a conversion table derived from the Unicode CLDR data to map between IANA IDs and Windows IDs. Depending on your version of Windows and Qt, this table may not be able to provide a valid conversion, in which "UTC" will be returned.

QTimeZone provides a public API to use this conversion table. The Windows ID used is the Windows Registry Key for the time zone which is also the MS Exchange EWS ID as well, but is different to the Time Zone Name (TZID) and COD code used by MS Exchange in versions before 2007.

Note: When Qt is built with the ICU library, it is used in preference to the Windows system APIs, bypassing all problems with those APIs using different names.

System Time Zone

The method systemTimeZoneId() returns the current system IANA time zone ID which on Unix-like systems will always be correct. On Windows this ID is translated from the Windows system ID using an internal translation table and the user's selected country. As a consequence there is a small chance any Windows install may have IDs not known by Qt, in which case "UTC" will be returned.

Creating a new QTimeZone instance using the system time zone ID will only produce a fixed named copy of the time zone, it will not change if the system time zone changes. QTimeZone::systemTimeZone() will return an instance representing the zone named by this system ID. Note that constructing a QDateTime using this system zone may behave differently than constructing a QDateTime that uses Qt::LocalTime as its Qt::TimeSpec, as the latter directly uses system APIs for accessing local time information, which may behave differently (and, in particular, might adapt if the user adjusts the system zone setting).

Time Zone Offsets

The difference between UTC and the local time in a time zone is expressed as an offset in seconds from UTC, i.e. the number of seconds to add to UTC to obtain the local time. The total offset is comprised of two component parts, the standard time offset and the daylight-saving time offset. The standard time offset is the number of seconds to add to UTC to obtain standard time in the time zone. The daylight-saving time offset is the number of seconds to add to the standard time offset to obtain daylight-saving time (abbreviated DST and sometimes called "daylight time" or "summer time") in the time zone. The usual case for DST (using standard time in winter, DST in summer) has a positive daylight-saving time offset. However, some zones have negative DST offsets, used in winter, with summer using standard time.

Note that the standard and DST offsets for a time zone may change over time as countries have changed DST laws or even their standard time offset.

License

This class includes data obtained from the CLDR data files under the terms of the Unicode Data Files and Software License. See Unicode Common Locale Data Repository (CLDR) for details.

See also QDateTime and QCalendar.

Member Type Documentation

[since 6.5] enum QTimeZone::Initialization

The type of the simplest lightweight time representations.

This enumeration identifies a type of lightweight time representation to pass to a QTimeZone constructor, where no further data are required. They correspond to the like-named members of Qt::TimeSpec.

ConstantValueDescription
QTimeZone::LocalTime0This time representation corresponds to the one implicitly used by system functions using time_t and struct tm value to map between local time and UTC time.
QTimeZone::UTC1This time representation, Coordinated Universal Time, is the base representation to which civil time is referred in all supported time representations. It is defined by the International Telecommunication Union.

This enum was introduced in Qt 6.5.

Member Function Documentation

[static, since 6.5] QTimeZone QTimeZone::fromDurationAheadOfUtc(std::chrono::seconds offset)

[static, since 6.5] QTimeZone QTimeZone::fromSecondsAheadOfUtc(int offset)

Returns a time representation at a fixed offset, in seconds, ahead of UTC.

The offset from UTC must be in the range -16 hours to +16 hours otherwise an invalid time zone will be returned. The returned QTimeZone is a lightweight time representation, not a time zone (backed by system-supplied or standard data).

If the offset is 0, the timeSpec() of the returned instance will be Qt::UTC. Otherwise, if offset is valid, timeSpec() is Qt::OffsetFromUTC. An invalid time zone, when returned, has Qt::TimeZone as its timeSpec().

This function was introduced in Qt 6.5.

See also QTimeZone(int), asBackendZone(), fixedSecondsAheadOfUtc(), MinUtcOffsetSecs, and MaxUtcOffsetSecs.

[noexcept] QTimeZone::QTimeZone()

Create a null/invalid time zone instance.

[noexcept, since 6.5] QTimeZone::QTimeZone(QTimeZone::Initialization spec)

Creates a lightweight instance describing UTC or local time.

This function was introduced in Qt 6.5.

See also fromSecondsAheadOfUtc(), asBackendZone(), utc(), and systemTimeZone().

[noexcept] QTimeZone::QTimeZone(const QTimeZone &other)

Copy constructor: copy other to this.

[noexcept] QTimeZone::QTimeZone(QTimeZone &&other)

Move constructor of this from other.

[noexcept] QTimeZone::~QTimeZone()

Destroys the time zone.

[constexpr noexcept, since 6.5] int QTimeZone::fixedSecondsAheadOfUtc() const

For a lightweight time representation whose timeSpec() is Qt::OffsetFromUTC, this returns the fixed offset from UTC that it describes. For any other time representation it returns 0, even if that time representation does have a constant offset from UTC.

This function was introduced in Qt 6.5.

[constexpr noexcept, since 6.5] bool QTimeZone::isUtcOrFixedOffset() const

Returns true if timeSpec() is Qt::UTC or Qt::OffsetFromUTC.

When it is true, the time description does not change over time, such as having seasonal daylight-saving changes, as may happen for local time or a time zone. Knowing this may save the calling code to need for various other checks.

This function was introduced in Qt 6.5.

[static constexpr noexcept, since 6.5] bool QTimeZone::isUtcOrFixedOffset(Qt::TimeSpec spec)

Returns true if spec is Qt::UTC or Qt::OffsetFromUTC.

This function was introduced in Qt 6.5.

bool QTimeZone::isValid() const

Returns true if this time zone is valid.

[noexcept] void QTimeZone::swap(QTimeZone &other)

Swaps this time zone instance with other. This operation is very fast and never fails.

[constexpr noexcept, since 6.5] Qt::TimeSpec QTimeZone::timeSpec() const

Returns a Qt::TimeSpec identifying the type of time representation.

If the result is Qt::TimeZone, this time description is a time zone (backed by system-supplied or standard data); otherwise, it is a lightweight time representation. If the result is Qt::LocalTime it describes local time: see Qt::TimeSpec for details.

This function was introduced in Qt 6.5.

See also fixedSecondsAheadOfUtc() and asBackendZone().

[noexcept] QTimeZone &QTimeZone::operator=(QTimeZone &&other)

Move-assigns other to this QTimeZone instance, transferring the ownership of its data to this instance.

QTimeZone &QTimeZone::operator=(const QTimeZone &other)

Assignment operator, assign other to this.

Member Variable Documentation

const int QTimeZone::MaxUtcOffsetSecs

Timezone offsets from UTC are expected to be no higher than this.

The highest UTC offset of any early 21st century timezone is +14 hours (Christmas Island, Kiribati, Kiritimati), or 14 hours east of Greenwich.

Historically, before 1867, when Russia sold Alaska to America, Alaska used the same date as Russia, so had offsets over 15 hours east of Greenwich. As Alaska was using local solar mean time, its offsets varied, but all were less than 16 hours east of Greenwich.

See also MinUtcOffsetSecs.

const int QTimeZone::MinUtcOffsetSecs

Timezone offsets from UTC are expected to be no lower than this.

The lowest UTC offset of any early 21st century timezone is -12 hours (Baker Island, USA), or 12 hours west of Greenwich.

Historically, until 1844, The Philippines (then controlled by Spain) used the same date as Spain's American holdings, so had offsets close to 16 hours west of Greenwich. As The Philippines was using local solar mean time, it is possible some outlying territory of it may have been operating at more than 16 hours west of Greenwich, but no early 21st century timezone traces its history back to such an extreme.

See also MaxUtcOffsetSecs.

Related Non-Members

[noexcept] bool operator!=(const QTimeZone &lhs, const QTimeZone &rhs)

Returns true if lhs time zone is not equal to the rhs time zone.

Two representations are different if they are internally described differently, even if they agree in their representation of all moments of time. In particular, a lightweight time representation may coincide with a time zone but the two will not be equal.

[noexcept] bool operator==(const QTimeZone &lhs, const QTimeZone &rhs)

Returns true if lhs time zone is equal to the rhs time zone.

Two representations are different if they are internally described differently, even if they agree in their representation of all moments of time. In particular, a lightweight time representation may coincide with a time zone but the two will not be equal.