KTimeZone Class Reference

from PyKDE4.kdecore import *

Subclasses: KSystemTimeZone, KTzfileTimeZone

Detailed Description

Base class representing a time zone.

The KTimeZone base class contains general descriptive data about the time zone, and provides an interface for methods to read and parse time zone definitions, and to translate between UTC and local time. Derived classes must implement these methods, and may also hold the actual details of the dates and times of daylight savings changes, offsets from UTC, etc. They should be tailored to deal with the type and format of data held by a particular type of time zone database.

If this base class is instantiated as a valid instance, it always represents the UTC time zone.

KTimeZone is designed to work in partnership with KTimeZoneSource. KTimeZone provides access to individual time zones, while classes derived from KTimeZoneSource read and parse a particular format of time zone definition. Because time zone sources can differ in what information they provide about time zones, the parsed data retured by KTimeZoneSource can vary between different sources, resulting in the need to create different KTimeZone classes to handle the data.

KTimeZone instances are often grouped into KTimeZones collections.

Copying KTimeZone instances is very efficient since the class data is explicitly shared, meaning that only a pointer to the data is actually copied. To achieve this, each class inherited from KTimeZone must have a corresponding backend class derived from KTimeZoneBackend.

Note:: Classes derived from KTimeZone should not have their own d-pointer. The d-pointer is instead contained in their backend class (derived from KTimeZoneBackend). This allows KTimeZone's reference-counting of private data to take care of the derived class's data as well, ensuring that instance data is not deleted while any references to the class instance remains. All virtual methods which override KTimeZone virtual methods must be defined in the backend class instead.

Base class representing a time zone

See also:: KTimeZoneBackend, KTimeZoneSource, KTimeZoneData

Author:: David Jarvie <djarvie@kde.org>.

Author:: S.R.Haque <srhaque@iee.org>.

Attributes
int	InvalidOffset
time_t	InvalidTime_t
float	UNKNOWN
Methods
	__init__ (self, QString name)
	__init__ (self, KTimeZone tz)
	__init__ (self, KTimeZoneBackend impl)
QByteArray	abbreviation (self, QDateTime utcDateTime)
[QByteArray]	abbreviations (self)
QString	comment (self)
QDateTime	convert (self, KTimeZone newZone, QDateTime zoneDateTime)
QString	countryCode (self)
int	currentOffset (self, Qt::TimeSpec basis=Qt.UTC)
KTimeZoneData	data (self, bool create=0)
bool	hasTransitions (self)
bool	isDst (self, time_t t)
bool	isDstAtUtc (self, QDateTime utcDateTime)
bool	isValid (self)
float	latitude (self)
[KTimeZone.LeapSeconds]	leapSecondChanges (self)
float	longitude (self)
QString	name (self)
int	offset (self, time_t t)
int	offsetAtUtc (self, QDateTime utcDateTime)
int, int secondOffset	offsetAtZoneTime (self, QDateTime zoneDateTime)
bool	operator != (self, KTimeZone rhs)
bool	operator == (self, KTimeZone rhs)
bool	parse (self)
[KTimeZone.Phase]	phases (self)
	setData (self, KTimeZoneData data, KTimeZoneSource source=0)
KTimeZoneSource	source (self)
QDateTime	toUtc (self, QDateTime zoneDateTime)
QDateTime, bool secondOccurrence	toZoneTime (self, QDateTime utcDateTime)
int, int secondIndex, bool validTime	transitionIndex (self, QDateTime dt)
[QDateTime]	transitionTimes (self, KTimeZone.Phase phase, QDateTime start=QDateTime(), QDateTime end=QDateTime())
[KTimeZone.Transition]	transitions (self, QDateTime start=QDateTime(), QDateTime end=QDateTime())
QByteArray	type (self)
bool	updateBase (self, KTimeZone other)
[int]	utcOffsets (self)
Static Methods
QDateTime	fromTime_t (time_t t)
time_t	toTime_t (QDateTime utcDateTime)
KTimeZone	utc ()

Method Documentation

__init__	(	self,
		QString	name
	)

Constructs a UTC time zone.

Parameters:

name

name of the UTC time zone

__init__	(	self,
		KTimeZone	tz
	)

__init__	(	self,
		KTimeZoneBackend	impl
	)

A representation for unknown locations; this is a float that does not represent a real latitude or longitude.

QByteArray abbreviation	(	self,
		QDateTime	utcDateTime
	)

Returns the time zone abbreviation current at a specified time.

Parameters:

utcDateTime

UTC date/time. An error occurs if utcDateTime.timeSpec() is not Qt.UTC.

Returns:: time zone abbreviation, or empty string if error

See also:: abbreviations()

[QByteArray] abbreviations ( self )

Returns the list of time zone abbreviations used by the time zone. This may include historical ones which are no longer in use or have been superseded.

Returns:: list of abbreviations

See also:: abbreviation()

QString comment ( self )

Returns any comment for the time zone.

Returns:: comment, may be empty

QDateTime convert	(	self,
		KTimeZone	newZone,
		QDateTime	zoneDateTime
	)

Converts a date/time, which is interpreted as being local time in this time zone, into local time in another time zone.

Parameters:

	newZone	other time zone which the time is to be converted into
	zoneDateTime	local date/time. An error occurs if zoneDateTime.timeSpec() is not Qt.LocalTime.

Returns:: converted date/time, or invalid date/time if error

See also:: toUtc(), toZoneTime()

QString countryCode ( self )

Returns the two-letter country code of the time zone.

Returns:: upper case ISO 3166 2-character country code, empty if unknown

int currentOffset	(	self,
		Qt::TimeSpec	basis=Qt.UTC
	)

Returns the current offset of this time zone to UTC or the local system time zone. The offset is the number of seconds which you must add to UTC or the local system time to get local time in this time zone.

Take care if you cache the results of this routine; that would break if the result were stored across a daylight savings change.

Parameters:

basis

Qt.UTC to return the offset to UTC, Qt.LocalTime to return the offset to local system time

Returns:: offset in seconds

See also:: offsetAtZoneTime(), offsetAtUtc()

KTimeZoneData data	(	self,
		bool	create=0
	)

Returns the detailed parsed data for the time zone. This will return null unless either parse() has been called beforehand, or create is true.

Parameters:

create

true to parse the zone's data first if not already parsed

Returns:: pointer to data, or null if data has not been parsed

bool hasTransitions ( self )

Return whether daylight saving transitions are available for the time zone.

The base class returns false.

Returns:: true if transitions are available, false if not

See also:: transitions(), transition()

bool isDst	(	self,
		time_t	t
	)

Returns whether daylight savings time is in operation at a specified UTC time.

Note that time_t has a more limited range than QDateTime, so consider using isDstAtUtc() instead.

Parameters:

the UTC time, measured in seconds since 00:00:00 UTC 1st January 1970 (as returned by time(2))

Returns:: true if daylight savings time is in operation, false otherwise

See also:: isDstAtUtc()

bool isDstAtUtc	(	self,
		QDateTime	utcDateTime
	)

Returns whether daylight savings time is in operation at the given UTC date/time.

If a derived class needs to work in terms of time_t (as when accessing the system time functions, for example), it should override both this method and isDst() so as to implement its offset calculations in isDst(), and reimplement this method simply as

     isDst(toTime_t(utcDateTime));

Parameters:

utcDateTime

the UTC date/time. An error occurs if utcDateTime.timeSpec() is not Qt.UTC.

Returns:: true if daylight savings time is in operation, false otherwise

See also:: isDst()

bool isValid ( self )

Checks whether the instance is valid.

Returns:: true if valid, false if invalid

float latitude ( self )

Returns the latitude of the time zone.

Returns:: latitude in degrees, UNKNOWN if not known

[KTimeZone.LeapSeconds] leapSecondChanges ( self )

Return all leap second adjustments, in time order.

Note that some time zone data sources (such as system time zones accessed via the system libraries) may not provide information on leap second adjustments. In such cases, this method will return an empty list.

Returns:: list of adjustments

float longitude ( self )

Returns the latitude of the time zone.

Returns:: latitude in degrees, UNKNOWN if not known

QString name ( self )

Returns the name of the time zone. If it is held in a KTimeZones container, the name is the time zone's unique identifier within that KTimeZones instance.

Returns:: name in system-dependent format

int offset	(	self,
		time_t	t
	)

Returns the offset of this time zone to UTC at a specified UTC time.

The offset is the number of seconds which you must add to UTC to get local time in this time zone.

Note that time_t has a more limited range than QDateTime, so consider using offsetAtUtc() instead.

Parameters:

the UTC time at which the offset is to be calculated, measured in seconds since 00:00:00 UTC 1st January 1970 (as returned by time(2))

Returns:: offset in seconds, or 0 if error

See also:: offsetAtUtc()

int offsetAtUtc	(	self,
		QDateTime	utcDateTime
	)

Returns the offset of this time zone to UTC at the given UTC date/time.

The offset is the number of seconds which you must add to UTC to get local time in this time zone.

If a derived class needs to work in terms of time_t (as when accessing the system time functions, for example), it should override both this method and offset() so as to implement its offset calculations in offset(), and reimplement this method simply as

     offset(toTime_t(utcDateTime));

Parameters:

utcDateTime

the UTC date/time at which the offset is to be calculated. An error occurs if utcDateTime.timeSpec() is not Qt.UTC.

Returns:: offset in seconds, or 0 if error

See also:: offset(), offsetAtZoneTime(), currentOffset()

int, int secondOffset offsetAtZoneTime	(	self,
		QDateTime	zoneDateTime
	)

Returns the offset of this time zone to UTC at the given local date/time. Because of daylight savings time shifts, the date/time may occur twice. Optionally, the offsets at both occurrences of dateTime are calculated.

The offset is the number of seconds which you must add to UTC to get local time in this time zone.

Parameters:

	zoneDateTime	the date/time at which the offset is to be calculated. This is interpreted as a local time in this time zone. An error occurs if zoneDateTime.timeSpec() is not Qt.LocalTime.
	secondOffset	if non-null, and the zoneDateTime occurs twice, receives the UTC offset for the second occurrence. Otherwise, it is set the same as the return value.

Returns:: offset in seconds. If zoneDateTime occurs twice, it is the offset at the first occurrence which is returned. If zoneDateTime does not exist because of daylight savings time shifts, InvalidOffset is returned. If any other error occurs, 0 is returned.

See also:: offsetAtUtc(), currentOffset()

bool operator !=	(	self,
		KTimeZone	rhs
	)

bool operator ==	(	self,
		KTimeZone	rhs
	)

Checks whether this is the same instance as another one. Note that only the pointers to the time zone data are compared, not the contents. So it will only return equality if one instance was copied from the other.

Parameters:

rhs

other instance

Returns:: true if the same instance, else false

bool parse ( self )

Extracts time zone detail information for this time zone from the source database.

Returns:: false if the parse encountered errors, true otherwise

[KTimeZone.Phase] phases ( self )

Return all daylight savings time phases for the time zone.

Note that some time zone data sources (such as system time zones accessed via the system libraries) may not allow a list of daylight savings time changes to be compiled easily. In such cases, this method will return an empty list.

Returns:: list of phases

setData	(	self,
		KTimeZoneData	data,
		KTimeZoneSource	source=0
	)

Sets the detailed parsed data for the time zone, and optionally a new time zone source object.

Parameters:

	data	parsed data
	source	if non-null, the new source object for the time zone

See also:: data()

KTimeZoneSource source ( self )

Returns the source reader/parser for the time zone's source database.

Returns:: reader/parser

QDateTime toUtc	(	self,
		QDateTime	zoneDateTime
	)

Converts a date/time, which is interpreted as local time in this time zone, into UTC.

Because of daylight savings time shifts, the date/time may occur twice. In such cases, this method returns the UTC time for the first occurrence. If you need the UTC time of the second occurrence, use offsetAtZoneTime().

Parameters:

zoneDateTime

local date/time. An error occurs if zoneDateTime.timeSpec() is not Qt.LocalTime.

Returns:: UTC date/time, or invalid date/time if error

See also:: toZoneTime(), convert()

QDateTime, bool secondOccurrence toZoneTime	(	self,
		QDateTime	utcDateTime
	)

Converts a UTC date/time into local time in this time zone.

Because of daylight savings time shifts, some local date/time values occur twice. The secondOccurrence parameter may be used to determine whether the time returned is the first or second occurrence of that time.

Parameters:

	utcDateTime	UTC date/time. An error occurs if utcDateTime.timeSpec() is not Qt.UTC.
	secondOccurrence	if non-null, returns true if the return value is the second occurrence of that time, else false

Returns:: local date/time, or invalid date/time if error

See also:: toUtc(), convert()

int, int secondIndex, bool validTime transitionIndex	(	self,
		QDateTime	dt
	)

Find the index to the last daylight savings time transition at or before a given UTC or local time. The return value is the index into the transition list returned by transitions().

Because of daylight savings time shifts, a local time may occur twice or may not occur at all. In the former case, the transitions at or before both occurrences of dt may optionally be calculated and returned in secondIndex. The latter case may optionally be detected by use of validTime.

Parameters:

	dt	date/time. dt.timeSpec() may be set to Qt.UTC or Qt.LocalTime.
	secondIndex	if non-null, and the dt occurs twice, receives the index to the transition for the second occurrence. Otherwise, it is set the same as the return value.
	validTime	if non-null, is set to false if dt does not occur, or to true otherwise

Returns:: index into the time zone transition list, or -1 either if dt is either outside the defined range of the transition data or if dt does not occur

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

[QDateTime] transitionTimes	(	self,
		KTimeZone.Phase	phase,
		QDateTime	start=QDateTime(),
		QDateTime	end=QDateTime()
	)

Return the times of all daylight saving transitions to a given time zone phase, in time order. If desired, the times returned may be restricted to a specified time range.

Note that some time zone data sources (such as system time zones accessed via the system libraries) may not allow a list of daylight saving time changes to be compiled easily. In such cases, this method will return an empty list.

Parameters:

	phase	time zone phase
	start	start UTC date/time, or invalid date/time to return all transitions up to end. start.timeSpec() must be Qt.UTC, else start will be considered invalid.
	end	end UTC date/time, or invalid date/time for no end. end.timeSpec() must be Qt.UTC, else end will be considered invalid.

Returns:: ordered list of transition times

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

[KTimeZone.Transition] transitions	(	self,
		QDateTime	start=QDateTime(),
		QDateTime	end=QDateTime()
	)

Return all daylight saving transitions, in time order. If desired, the transitions returned may be restricted to a specified time range.

Parameters:

	start	start UTC date/time, or invalid date/time to return all transitions up to end. start.timeSpec() must be Qt.UTC, else start will be considered invalid.
	end	end UTC date/time, or invalid date/time for no end. end.timeSpec() must be Qt.UTC, else end will be considered invalid.

Returns:: list of transitions, in time order

See also:: hasTransitions(), transition(), transitionTimes()

QByteArray type ( self )

Returns the class name of the data represented by this instance. If a derived class object has been assigned to this instance, this method will return the name of that class.

Returns:: "KTimeZone" or the class name of a derived class

bool updateBase	(	self,
		KTimeZone	other
	)

Update the definition of the time zone to be identical to another KTimeZone instance. A prerequisite is that the two instances must have the same name.

The main purpose of this method is to allow updates of the time zone definition by derived classes without invalidating pointers to the instance (particularly pointers held by KDateTime objects). Note that the KTimeZoneData object and KTimeZoneSource pointer are not updated: the caller class should do this itself by calling setData().

Parameters:

other

time zone whose definition is to be used

Returns:: true if definition was updated (i.e. names are the same)

See also:: setData()

[int] utcOffsets ( self )

Returns the complete list of UTC offsets used by the time zone. This may include historical ones which are no longer in use or have been superseded.

A UTC offset is the number of seconds which you must add to UTC to get local time in this time zone.

If due to the nature of the source data for the time zone, compiling a complete list would require significant processing, an empty list is returned instead.

Returns:: sorted list of UTC offsets, or empty list if not readily available.

Static Method Documentation

QDateTime fromTime_t	(	time_t	t
	)

Converts a UTC time, measured in seconds since 00:00:00 UTC 1st January 1970 (as returned by time(2)), to a UTC QDateTime value. QDateTime.setTime_t() is limited to handling t >= 0, since its parameter is unsigned. This method takes a parameter of time_t which is signed.

Returns:: converted time

See also:: toTime_t()

time_t toTime_t	(	QDateTime	utcDateTime
	)

Converts a UTC QDateTime to a UTC time, measured in seconds since 00:00:00 UTC 1st January 1970 (as returned by time(2)). QDateTime.toTime_t() returns an unsigned value. This method returns a time_t value, which is signed.

Parameters:

utcDateTime

date/time. An error occurs if utcDateTime.timeSpec() is not Qt.UTC.

Returns:: converted time, or -1 if the date is out of range for time_t or

utcDateTime.timeSpec() is not Qt.UTC

See also:: fromTime_t()

KTimeZone utc ( )

Returns a standard UTC time zone, with name "UTC".

Note:: The KTimeZone returned by this method does not belong to any KTimeZones collection. Any KTimeZones instance may contain its own UTC KTimeZone defined by its time zone source data, but that will be a different instance than this KTimeZone.

Returns:: UTC time zone

Attribute Documentation

int InvalidOffset

time_t InvalidTime_t

float UNKNOWN

KTimeZone Class Reference

Detailed Description

Attributes

Methods

Static Methods

Method Documentation

Static Method Documentation

Attribute Documentation

Modules