Time zone classes

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.

Warning

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
{
    public:
        NewTimeZoneSource(...);  // parameters might include location of data source ...
        ~NewTimeZoneSource();

        // 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
{
    public:
        NewTimeZone(NewTimeZoneSource *source, const QString &name, ...);
        ~NewTimeZone();

        // Methods implementing KTimeZone virtual methods are implemented
        // in NewTimeZoneBackend, not here.

        // Anything else which you need
    private:
        // No d-pointer !
};

class NewTimeZoneBackend : public KTimeZoneBackend
{
    public:
        NewTimeZoneBackend(NewTimeZoneSource *source, const QString &name, ...);
        ~NewTimeZoneBackend();

        KTimeZoneBackend *clone() const;

        // 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
    private:
        NewTimeZonePrivate *d;   // non-const !
};

class NewTimeZoneData : public KTimeZoneData
{
        friend class NewTimeZoneSource;

    public:
        NewTimeZoneData();
        ~NewTimeZoneData();

        // Virtual methods which need to be reimplemented
        KTimeZoneData *clone() const;
        QList<QByteArray> abbreviations() 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().