Converts a QDateTime between UTC and local time for a given time zone. More...

Classes
class	OffsetData
	Stores time zone offset data for a transition More...

Public Typedefs
using	OffsetDataList = QVector< OffsetData >

Public Types
enum	NameType

enum	TimeType

Public Methods
	QTimeZone (const QByteArray &zoneId)

	QTimeZone (const QByteArray &zoneId, int offsetSeconds, const QString &name, const QString &abbreviation, QLocale::Country country=QLocale::AnyCountry, const QString &comment=QString ())

	QTimeZone (const QTimeZone &other)

	QTimeZone (int offsetSeconds)

	QTimeZone (QTimeZone &&other)

	~QTimeZone ()

QString	abbreviation (const QDateTime &atDateTime) const

QString	comment () const

QLocale::Country	country () const

int	daylightTimeOffset (const QDateTime &atDateTime) const

QString	displayName (const QDateTime &atDateTime, QTimeZone::NameType nameType=QTimeZone::DefaultName, const QLocale &locale=QLocale ()) const

QString	displayName (QTimeZone::TimeType timeType, QTimeZone::NameType nameType=QTimeZone::DefaultName, const QLocale &locale=QLocale ()) const

bool	hasDaylightTime () const

bool	hasTransitions () const

QByteArray	id () const

bool	isDaylightTime (const QDateTime &atDateTime) const

bool	isValid () const

OffsetData	nextTransition (const QDateTime &afterDateTime) const

OffsetData	offsetData (const QDateTime &forDateTime) const

int	offsetFromUtc (const QDateTime &atDateTime) const

bool	operator!= (const QTimeZone &other) const

QTimeZone &	operator= (const QTimeZone &other)

QTimeZone &	operator= (QTimeZone &&other)

bool	operator== (const QTimeZone &other) const

OffsetData	previousTransition (const QDateTime &beforeDateTime) const

int	standardTimeOffset (const QDateTime &atDateTime) const

void	swap (QTimeZone &other)

OffsetDataList	transitions (const QDateTime &fromDateTime, const QDateTime &toDateTime) const

Static Public Methods
static QList< QByteArray >	availableTimeZoneIds ()

static QList< QByteArray >	availableTimeZoneIds (int offsetSeconds)

static QList< QByteArray >	availableTimeZoneIds (QLocale::Country country)

static QByteArray	ianaIdToWindowsId (const QByteArray &zoneId)

static bool	isTimeZoneIdAvailable (const QByteArray &zoneId)

static QTimeZone	systemTimeZone ()

static QByteArray	systemTimeZoneId ()

static QTimeZone	utc ()

static QByteArray	windowsIdToDefaultIanaId (const QByteArray &windowsId)

static QByteArray	windowsIdToDefaultIanaId (const QByteArray &windowsId, QLocale::Country country)

static QList< QByteArray >	windowsIdToIanaIds (const QByteArray &windowsId)

static QList< QByteArray >	windowsIdToIanaIds (const QByteArray &windowsId, QLocale::Country country)

Friends
QDataStream &	operator<< (QDataStream &stream, const QTimeZone &tz)

class	QDateTime

Related Functions
These are not member functions
QDataStream &	operator>> (QDataStream &stream, QTimeZone &tz)

Detailed Description

This class converts a QDateTime between UTC and local time for a given time zone.

UTC Defined

The abbreviation UTC stands for "Coordinated Universal Time". It is odd for an abbreviation not to match the full phrase. The reason this happened is the committee which established UTC wanted to use the same abbreviation in all languages.

UTC does not refer to a time zone. It represents a clock which is located in London and is never adjusted for Daylight Saving Time. The UTC clock accounts for leap seconds. It is the primary time standard by which the world regulates clocks and time. Coordinated Universal Time is considered a successor to Greenwich Mean Time.

A time zone is defined by a positive or negative offset from UTC. If a given time zone observes Daylight Saving Time this offset will change, usually by one hour.

IANA Time Zone

QTimeZone uses the IANA time zone name as defined in the IANA Time Zone Database (https://www.iana.org/time-zones). Using this IANA name ensures consistency across all supported OS platforms. Windows is the only platform which does not provide native support for IANA time zone names. A special mapping exists between the IANA name and the Microsoft id.

The IANA names change on a regular basis and can vary depending on how recently the host system data was updated. You should not assume a given name will exist. Use the method availableTimeZoneIds() to determine what IANA name are available.

System Time Zone

The method systemTimeZoneId() returns the current IANA time zone name based on the OS settings. Since on Windows the IANA name must be looked up in a translation table, there is a small chance the name will not be found. If this happens "UTC" will be returned.

Time Zone Offsets

The difference between UTC and the local time in a QTimeZone is expressed as an offset in seconds from UTC. The total offset is comprised of two 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

The Daylight Saving time offset is the number of seconds to add to the Standard Time offset to obtain Daylight Saving Time

See also: QDateTime

Member Typedef Documentation

QTimeZone::OffsetDataList

Equivalent to QVector<OffsetData>.

Member Enumeration Documentation

enum QTimeZone::NameType

The type of time zone name.

Constant	Value	Description
QTimeZone::DefaultName	0	The default form of the time zone name, e.g. LongName, ShortName or OffsetName
QTimeZone::LongName	1	The long form of the time zone name, e.g. "Central European Time"
QTimeZone::ShortName	2	The short form of the time zone name, usually an abbreviation, e.g. "CET"
QTimeZone::OffsetName	3	The standard ISO offset form of the time zone name, e.g. "UTC+01:00"e

enum QTimeZone::TimeType

The type of time zone time, for example when requesting the name. In time zones that do not apply DST, all three values may return the same result.

Constant	Value	Description
QTimeZone::StandardTime	0	The standard time in a time zone, i.e. when Daylight-Saving is not in effect. For example when formatting a display name this will show something like "Pacific Standard Time".
QTimeZone::DaylightTime	1	A time when Daylight-Saving is in effect. For example when formatting a display name this will show something like "Pacific daylight-saving time".
QTimeZone::GenericTime	2	A time which is not specifically Standard or Daylight-Saving time, either an unknown time or a neutral form. For example when formatting a display name this will show something like "Pacific Time".

Constructor & Destructor Documentation

QTimeZone::QTimeZone ( const QByteArray & zoneId )

explicit

Creates a QTimeZone with the given time zone zoneId. The zoneId must match a time zone name that is available on the current operating system. If there is no match an invalid QTimeZone will be returned.

For example, if the zoneId is "America/New_York" the QTimeZone will contain the QTimeZone::OffsetData indicating if and when Daylight Saving Time is observed.

In contrast, if the zoneId is "UTC-05:00" then the QTimeZone will not contain any offset data. In this example the QTimeZone is simply an offset from UTC. The value in the string must be in the range UTC-14:00 to UTC+14:00.

See also: availableTimeZoneIds()

QTimeZone::QTimeZone ( int offsetSeconds )

explicit

Creates a QTimeZone with an offset from UTC of offsetSeconds. The offset must be in the range of -14 hours to +14 hours, otherwise an invalid QTimeZone will be returned.

QTimeZone::QTimeZone	(	const QByteArray &	zoneId,
		int	offsetSeconds,
		const QString &	name,
		const QString &	abbreviation,
		QLocale::Country	country = `QLocale::AnyCountry`,
		const QString &	comment = `QString()`
	)

Creates a custom time zone with a zoneId and an offset from UTC of offsetSeconds. The name will be used by displayName() for the LongName, the abbreviation will be used by displayName() for the ShortName and by abbreviation(). The country and comment are both optional.

The zoneId must not be one of the available system IDs returned by availableTimeZoneIds(). The offsetSeconds from UTC must be in the range -14 hours to +14 hours. If the custom time zone does not have a specific country then set it to the default value of QLocale::AnyCountry.

QTimeZone::QTimeZone ( const QTimeZone & other )

Copy constructs a QTimeZone from other.

QTimeZone::QTimeZone ( QTimeZone && other )

Move constructs a new QTimeZone from other.

QTimeZone::~QTimeZone ( )

Destroys this QTimeZone.

Method Documentation

QString QTimeZone::abbreviation ( const QDateTime & atDateTime ) const

Returns the Time Zone Abbreviation at the given atDateTime. The abbreviation may change depending on Daylight Saving Time or even historical events. The abbreviation is not guaranteed to be unique to a particular time zone.

For example, the abbreviation for India is IST which stands for "Indian Standard Time". In Dublin they also use the abbreviation IST however in this region it means "Irish Standard Time".

See also: displayName()

QList< QByteArray > QTimeZone::availableTimeZoneIds ( )

static

Returns a list of all available IANA time zone name found on this system.

See also: isTimeZoneIdAvailable()

QList< QByteArray > QTimeZone::availableTimeZoneIds ( int offsetSeconds )

static

Returns a list of all available IANA time zone names with a given standard time offset of offsetSeconds.

See also: isTimeZoneIdAvailable()

QList< QByteArray > QTimeZone::availableTimeZoneIds ( QLocale::Country country )

static

Returns a list of all available IANA time zone names for a given country.

As a special case, a country of Qt::AnyCountry returns those time zones that do not have any country related to them, such as UTC. If you require a list of all time zone names for all countries then use the standard availableTimeZoneIds() method.

See also: isTimeZoneIdAvailable()

QString QTimeZone::comment ( ) const

Returns any comment for the time zone. A comment may be provided by the host platform to assist users in choosing the correct time zone. Depending on the platform this may not be localized.

QLocale::Country QTimeZone::country ( ) const

Returns the country for this QTimeZone.

int QTimeZone::daylightTimeOffset ( const QDateTime & atDateTime ) const

Returns the Daylight Saving Time offset at the given atDateTime. This is the number of seconds to add to the Standard Time offset to obtain the local Daylight Saving time.

For example, for the time zone "Europe/Berlin" the DST offset is +3600 seconds. During Standard Time daylightTimeOffset() will return 0 and when Daylight Saving is in effect it will return +3600.

See also: offsetFromUtc(), standardTimeOffset()

QString QTimeZone::displayName	(	const QDateTime &	atDateTime,
		QTimeZone::NameType	nameType = `QTimeZone::DefaultName`,
		const QLocale &	locale = `QLocale()`
	)		const

Returns the localized time zone display name at the given atDateTime for the given nameType in the given locale. The nameType and locale requested may not be supported on all platforms, in which case the best available option will be returned.

If the locale is not provided then the application default locale will be used. The display name may change depending on Daylight Saving Time or historical events.

See also: abbreviation()

QString QTimeZone::displayName	(	QTimeZone::TimeType	timeType,
		QTimeZone::NameType	nameType = `QTimeZone::DefaultName`,
		const QLocale &	locale = `QLocale()`
	)		const

Returns the localized time zone display name for the given timeType and nameType in the given locale. The nameType and locale requested may not be supported on all platforms, in which case the best available option will be returned.

If the locale is not provided then the application default locale will be used. Where the time zone display names have changed at any point, then the most recent names will be used.

See also: abbreviation()

bool QTimeZone::hasDaylightTime ( ) const

Returns true if the time zone has used daylight saving time, at any point

See also: daylightTimeOffset(), isDaylightTime()

bool QTimeZone::hasTransitions ( ) const

Returns true if the system backend supports transitions. A transition occurs when Daylight Saving Time turns on or off. It can also happen when a country alters the offset for a given time zone.

See also: nextTransition(), previousTransition(), transitions()

QByteArray QTimeZone::ianaIdToWindowsId ( const QByteArray & zoneId )

static

Returns the Windows Id equivalent to the given zoneId.

See also: windowsIdToDefaultIanaId(), windowsIdToIanaIds()

QByteArray QTimeZone::id ( ) const

Returns the IANA name for the current QTimeZone. IANA names are used on all platforms. On Windows the name will be translated to the closest IANA name for the fiven time zone and country.

bool QTimeZone::isDaylightTime ( const QDateTime & atDateTime ) const

Returns true if Daylight Saving Time was in effect at the given atDateTime.

See also: daylightTimeOffset(), hasDaylightTime()

bool QTimeZone::isTimeZoneIdAvailable ( const QByteArray & zoneId )

static

Returns true if a given zoneId is available on this system.

See also: availableTimeZoneIds()

bool QTimeZone::isValid ( ) const

Returns true if this QTimeZone is valid.

QTimeZone::OffsetData QTimeZone::nextTransition ( const QDateTime & afterDateTime ) const

Returns the first time zone transition after the given afterDateTime. This is useful when you have a QDateTime and want to find when the next transition will occur.

If there is no transition after afterDateTime then an invalid OffsetData will be returned.

See also: hasTransitions(), previousTransition(), transitions()

QTimeZone::OffsetData QTimeZone::offsetData ( const QDateTime & forDateTime ) const

Returns the offset data for the given forDateTime.

See also: abbreviation(), daylightTimeOffset(), offsetFromUtc(), standardTimeOffset()

int QTimeZone::offsetFromUtc ( const QDateTime & atDateTime ) const

Returns the total offset at the given atDateTime. This is the number of seconds to add to UTC to obtain the local time. The offset includes any DST offset that may be in effect.

For example, for the time zone "Europe/Berlin" the standard time offset is +3600 seconds and the DST offset is +3600 seconds. During standard time offsetFromUtc() will return +3600 (UTC+01:00), and during DST it will return +7200 (UTC+02:00).

See also: daylightTimeOffset(), standardTimeOffset()

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

Returns true if this time zone is not equal to the other time zone.

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

Copy assigns from other and returns a reference to this object.

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

inline

Move assigns from other and returns a reference to this object.

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

Returns true if this time zone is equal to the other time zone.

QTimeZone::OffsetData QTimeZone::previousTransition ( const QDateTime & beforeDateTime ) const

Returns the first time zone transition before the given beforeDateTime. This is useful when you have a QDateTime and want to find when the previous transition occurred.

If there is no transition prior to beforeDateTime then an invalid OffsetData will be returned.

See also: hasTransitions(), nextTransition(), transitions()

int QTimeZone::standardTimeOffset ( const QDateTime & atDateTime ) const

Returns the number of seconds between this QTimeZone and UTC as of the given atDateTime, ignoring Daylight Saving Time.

For example, for the QTimeZone "America/New_York" the offset from UTC is minus 5 hours which is -18,000 seconds. During both standard and DST this method will return -18000.

If the QTimeZone is "Pacific/Asia" which is the capitol of Samoa, the standard time offset changed at the end of the calendar year 2011. If atDateTime is a value prior to this date the offset was UTC minus 11 and this method will return -39600. If atDateTime is a value after Dec 31 2011 the UTC offset is plus 13 and this method returns 46800.

Refer to UTC Defined for additional information.

See also: daylightTimeOffset(), offsetFromUtc()

void QTimeZone::swap ( QTimeZone & other )

inline

Swaps this QTimeZone with other.

QTimeZone QTimeZone::systemTimeZone ( )

static

Constructs a new QTimeZone which represents the local system time as specified by systemTimeZoneId().

See also: utc()

QByteArray QTimeZone::systemTimeZoneId ( )

static

Returns the current system time zone IANA name.

On Windows the ID is mapped to an IANA name based on the system country setting. For example, if the system is set to "Eastern Standard Time" in the United States the IANA ID will be "America/New_York". If the translation fails then a value of "UTC" will be returned.

QTimeZone::OffsetDataList QTimeZone::transitions	(	const QDateTime &	fromDateTime,
		const QDateTime &	toDateTime
	)		const

Returns a list of all time zone transitions between the specified fromDateTime and toDateTime.

See also: hasTransitions(), nextTransition(), previousTransition()

QTimeZone QTimeZone::utc ( )

static

Constructs a new QTimeZone which has a zero offset from UTC.

Refer to UTC Defined for additional information.

See also: systemTimeZone()

QByteArray QTimeZone::windowsIdToDefaultIanaId ( const QByteArray & windowsId )

static

Returns the default IANA name for a given windowsId. Because a Windows ID can cover several IANA names in several different countries this method returns the most frequently used IANA name without considering the country.

For example, if the Window ID is set to "Eastern Standard Time", the IANA name will be "America/New_York". However, if the user is in Jamaica this name would be incorrect. As an alternative there is an overload of this method which accepts a country for the second parameter.

See also: ianaIdToWindowsId(), windowsIdToIanaIds()

QByteArray QTimeZone::windowsIdToDefaultIanaId	(	const QByteArray &	windowsId,
		QLocale::Country	country
	)

static

Returns the default IANA name for a given windowsId and country. Because a Windows ID can cover several IANA names within a given country, the most frequently used IANA ID in that country will be returned.

As a special case, QLocale::AnyCountry returns the default of those IANA IDs that do not have any specific country.

See also: ianaIdToWindowsId(), windowsIdToIanaIds()

QList< QByteArray > QTimeZone::windowsIdToIanaIds ( const QByteArray & windowsId )

static

Returns all the IANA names for a given windowsId. The returned list is sorted alphabetically.

See also: ianaIdToWindowsId(), windowsIdToDefaultIanaId()

QList< QByteArray > QTimeZone::windowsIdToIanaIds	(	const QByteArray &	windowsId,
		QLocale::Country	country
	)

static

Returns all the IANA names for a given windowsId and country. The list is in order of frequency of usage, where larger zones within a country are listed first.

As a special case QLocale::AnyCountry returns those IANA names that do not have any specific country.

See also: ianaIdToWindowsId(), windowsIdToDefaultIanaId()

Friends And Related Function Documentation

QDataStream & operator<<	(	QDataStream &	stream,
		const QTimeZone &	tz
	)

friend

Writes the given tz to the stream. Returns a reference to the stream.

Refer to Serializing Data Types for additional information.

QDataStream & operator>>	(	QDataStream &	stream,
		QTimeZone &	tz
	)

Refer to Serializing Data Types for additional information.

Classes

Public Typedefs

Public Types

Public Methods

Static Public Methods

Friends

Related Functions

Detailed Description

UTC Defined

IANA Time Zone

System Time Zone

Time Zone Offsets

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Method Documentation

Friends And Related Function Documentation