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.
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.
- 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.
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.
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:
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:
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:
The other NewTimeZoneBackend methods would work in an analogous way to NewTimeZoneBackend::offsetAtUtc() and NewTimeZoneBackend::offset().