Time zone classes


class  KSystemTimeZone
class  KSystemTimeZoneBackend
class  KSystemTimeZoneData
class  KSystemTimeZones
class  KSystemTimeZoneSource
class  KSystemTimeZoneSourceWindows
class  KSystemTimeZoneWindows
class  KTimeZone
class  KTimeZoneBackend
class  KTimeZoneData
class  KTimeZones
class  KTimeZoneSource
class  KTzfileTimeZone
class  KTzfileTimeZoneBackend
class  KTzfileTimeZoneData
class  KTzfileTimeZoneSource

Detailed Description

The time zone classes provide a framework for accessing time zone data, and converting times and dates between different time zones. They provide access to the system time zone database, and also allow developers to derive classes to access custom sources of time zone information such as calendar files.

A time zone is represented by the KTimeZone class. This provides access to the time zone's detailed definition and contains methods to convert times to and from that zone. In order to save processing, KTimeZone obtains its time zone details only when they are actually required. Each KTimeZone class has a corresponding KTimeZoneBackend backend class which implements reference counting of the time zone's data.

A collection of time zones is represented by the KTimeZones class, which acts as a container of KTimeZone objects. Within any KTimeZones object, each KTimeZone instance is uniquely identified by its name. Typically, each individual source of time zone information would be represented by a different KTimeZones object. This scheme allows conflicting time zone definitions between the different sources to be handled, since KTimeZone names need only be unique within a single KTimeZones object. Note that KTimeZone instances do not have to belong to any KTimeZones container.

Time zone source data can come in all sorts of different forms: TZFILE format for a UNIX system time zone database, definitions within calendar files, calls to libraries (e.g. libc), etc. The KTimeZoneSource class provides reading and parsing functions to access such data, handing off the parsed data for a specific time zone in a KTimeZoneData object. Both of these are base classes from which should be derived other classes which know about the particular access method and data format (KTimeZoneSource) and which details are actually provided (KTimeZoneData). When a KTimeZone instance needs its time zone's definition, it calls KTimeZoneSource::parse() and receives the data back in a KTimeZoneData object which it keeps for reference.

KTimeZoneData holds the definitions of the different daylight saving time and standard time phases in KTimeZone::Phase objects, and the timed sequence of daylight saving time changes in KTimeZone::Transition objects. Leap seconds adjustments are held in KTimeZone::LeapSeconds objects. You can access this data directly via KTimeZone and KTimeZoneData methods if required.

The mapping of the different classes to external data is as follows:

  • Each different source data format or access method is represented by a different KTimeZoneSource class.
  • Each different set of data provided from source data is represented by a different KTimeZoneData class. For example, some time zone sources provide only the absolute basic information about time zones, i.e. name, transition times and offsets from UTC. Others provide information on leap second adjustments, while still others might contain information on which countries use the time zone. To allow for this variation, KTimeZoneData is made available for inheritance. When the necessary information is not available, the KTimeZone::Phase, KTimeZone::Transition and KTimeZone::LeapSeconds data will be empty.
  • Each KTimeZoneData class will have a corresponding KTimeZone class, and related KTimeZoneBackend class, which can interpret its data.
  • Each different source database will typically be represented by a different KTimeZones instance, to avoid possible conflicts between time zone definitions. If it is known that two source databases are definitely compatible, they can be grouped together into the same KTimeZones instance.

System time zones

Access to system time zones is provided by the KSystemTimeZones class, which reads the zone.tab file to obtain the list of system time zones, and creates a KSystemTimeZone instance for each one. KSystemTimeZone has a KSystemTimeZoneBackend backend class, and uses the KSystemTimeZoneSource and KSystemTimeZoneData classes to obtain time zone data via libc library functions.

Normally, KSystemTimeZoneSource and KSystemTimeZoneData operate in the background and you will not need to use them directly.

The KSystemTimeZone class uses the standard system libraries to access time zone data, and its functionality is limited to what these libraries provide. On many systems, dates earlier than 1902 are not handled, and on non-GNU systems there is no guarantee that the time zone abbreviation returned for a given date will be correct if the abbreviations applicable then were not those currently in use. The KSystemTimeZones::readZone() method overcomes these restrictions by reading the time zone definition directly from the system time zone database files.

Tzfile access

The KTzfileTimeZone class provides access to tzfile(5) time zone definition files, which are used to form the time zone database on UNIX systems. Usually, for current information, it is easier to use the KSystemTimeZones class to access system tzfile data. However, for dealing with past data the KTzfileTimeZone class provides better guarantees of accurary, although it cannot handle dates earlier than 1902. It also provides more detailed information, and allows you to read non-system tzfile files. Alternatively, the KSystemTimeZones::readZone() method uses the KTzfileTimeZone class to read system time zone definition files.

KTzfileTimeZone has a KTzfileTimeZoneBackend backend class, and uses the KTzfileTimeZoneSource and KTzfileTimeZoneData classes to obtain time zone data from tzfile files.

Handling time zone data from other sources

To implement time zone classes to access a new time zone data source, you need as a minimum to derive a new class from KTimeZoneSource, and implement one or more parse() methods. If you can know in advance what KTimeZone instances to create without having to parse the source data, you should reimplement the virtual method KTimeZoneSource::parse(const KTimeZone&). Otherwise, you need to define your own parse() methods with appropriate signatures, to both read and parse the new data, and create new KTimeZone instances.

If the data for each time zone which is available from the new source happens to be the same as for another source for which KTimeZone classes already exist, you could simply use the existing KTimeZone, KTimeZoneBackend and KTimeZoneData derived classes to receive the parsed data from your new KTimeZoneSource class:

class NewTimeZoneSource : public KTimeZoneSource
NewTimeZoneSource(...); // parameters might include location of data source ...
// Option 1: reimplement KTimeZoneSource::parse() if you can
// pre-create the KTimeZone instances.
KTimeZoneData *parse(const KTimeZone &zone) const;
// Option 2: implement new parse() methods if you don't know
// in advance what KTimeZone instances to create.
void parse(..., KTimeZones *zones) const;
NewTimeZone *parse(...) const;
// Option 1:
KTimeZoneData *NewTimeZoneSource::parse(const KTimeZone &zone) const
QString zoneName = zone.name();
ExistingTimeZoneData* data = new ExistingTimeZoneData();
// Read the data for 'zoneName' from the new data source.
// Parse what we have read, and write it into 'data'.
// Compile the sequence of daylight savings changes and leap
// seconds adjustments (if available) and write into 'data'.
return data;

If the data from the new source is different from what any existing KTimeZoneData class contains, you will need to implement new KTimeZone, KTimeZoneBackend and KTimeZoneData classes in addition to the KTimeZoneSource class illustrated above:

class NewTimeZone : public KTimeZone
NewTimeZone(NewTimeZoneSource *source, const QString &name, ...);
// Methods implementing KTimeZone virtual methods are implemented
// in NewTimeZoneBackend, not here.
// Anything else which you need
// No d-pointer !
class NewTimeZoneBackend : public KTimeZoneBackend
NewTimeZoneBackend(NewTimeZoneSource *source, const QString &name, ...);
// Virtual methods which need to be reimplemented
int offsetAtZoneTime(const KTimeZone *caller, const QDateTime &zoneDateTime, int *secondOffset = 0) const;
int offsetAtUtc(const KTimeZone *caller, const QDateTime &utcDateTime) const;
int offset(const KTimeZone *caller, time_t t) const;
int isDstAtUtc(const KTimeZone *caller, const QDateTime &utcDateTime) const;
bool isDst(const KTimeZone *caller, time_t t) const;
// Anything else which you need
NewTimeZonePrivate *d; // non-const !
class NewTimeZoneData : public KTimeZoneData
friend class NewTimeZoneSource;
// Virtual methods which need to be reimplemented
KTimeZoneData *clone() const;
QByteArray abbreviation(const QDateTime &utcDateTime) const;
// Data members containing whatever is read by NewTimeZoneSource

Here is a guide to implementing the offset() and offsetAtUtc() methods, in the case where the source data does not use time_t for its time measurement:

int NewTimeZoneBackend::offsetAtUtc(const KTimeZone *caller, const QDateTime &utcDateTime) const
// Access this time zone's data. If we haven't already read it,
// force a read from source now.
NewTimeZoneData *zdata = caller->data(true);
// Use 'zdata' contents to work out the UTC offset
return offset;
int NewTimeZoneBackend::offset(const KTimeZone *caller, time_t t) const
return offsetAtUtc(KTimeZone::fromTime_t(t));

The other NewTimeZoneBackend methods would work in an analogous way to NewTimeZoneBackend::offsetAtUtc() and NewTimeZoneBackend::offset().

QString name() const
Returns the name of the time zone.
Definition: ktimezone.cpp:662
static 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))...
Definition: ktimezone.cpp:921
virtual int offsetAtZoneTime(const KTimeZone *caller, const QDateTime &zoneDateTime, int *secondOffset) const
Implements KTimeZone::offsetAtZoneTime().
Definition: ktimezone.cpp:464
virtual KTimeZoneData * parse(const KTimeZone &zone) const
Extracts detail information for one time zone from the source database.
Definition: ktimezone.cpp:979
virtual int offsetAtUtc(const KTimeZone *caller, const QDateTime &utcDateTime) const
Implements KTimeZone::offsetAtUtc().
Definition: ktimezone.cpp:525
virtual bool isDstAtUtc(const KTimeZone *caller, const QDateTime &utcDateTime) const
Implements KTimeZone::isDstAtUtc().
Definition: ktimezone.cpp:561
virtual QList< QByteArray > abbreviations() const
Returns the complete list of time zone abbreviations.
Definition: ktimezone.cpp:1174
virtual int offset(const KTimeZone *caller, time_t t) const
Implements KTimeZone::offset().
Definition: ktimezone.cpp:556
const KTimeZoneData * data(bool create=false) const
Returns the detailed parsed data for the time zone.
Definition: ktimezone.cpp:756
The KTimeZones class represents a time zone database which consists of a collection of individual tim...
Definition: ktimezone.h:308
Base class representing a source of time zone information.
Definition: ktimezone.h:1231
virtual KTimeZoneData * clone() const
Creates a new copy of this object.
Definition: ktimezone.cpp:1169
Base class for the parsed data returned by a KTimeZoneSource class.
Definition: ktimezone.h:1302
Base backend class for KTimeZone classes.
Definition: ktimezone.h:1121
virtual KTimeZoneBackend * clone() const
Creates a copy of this instance.
Definition: ktimezone.cpp:459
virtual QByteArray abbreviation(const QDateTime &utcDateTime) const
Returns the time zone abbreviation current at a specified time.
Definition: ktimezone.cpp:1191
virtual bool isDst(const KTimeZone *caller, time_t t) const
Implements KTimeZone::isDst().
Definition: ktimezone.cpp:573
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Dec 1 2023 03:59:53 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.