timezone

The interface ITimeZoneProvider and ITimeZone are helpful to make timezone relevant time calculation.

File information

Filecommon/interface/timezone.h

Classes ITimeZoneProvider
ITimeZone
ITimeZoneDSTRange
Examples Code Example
Data types Timezone IDs
Windows timezone mapping
Copyright

Classes

ITimeZoneProvider

class ITimeZoneProvider {
public:
    static ITimeZone * GetTimeZone(const char * tzid, class IInstanceLog * const log);
};

Public functions

GetTimeZone
Returns the ITimeZone instance for the given timezone id. It it will be the first time that timezone instance is requested, ITimeZoneProvider creates the instance and stores it to an internal list for later use. The instance also will be released automatically on application shutdown, so there is no need to release it from within your app (what acutally is not possible).

Parameters

const char * tzidOne of the timezone ids (see below)
IInstanceLog * const logAn IInstance log instance used for logging in case of an error.

ITimeZone

class ITimeZone {
protected:
    virtual ~ITimeZone() {}
    
public:
    virtual const char * TimeZoneName();
    virtual const char * UTCName();
    virtual long64 UTCDiff();
    virtual long64 DSTDiff();
    virtual long64 ToLocalTime(long64 utcTime);
    virtual long64 ToUTCTime(long64 localTime);
    virtual long64 RemoveDST(long64 timeStamp);
    virtual long64 AddDST(long64 timeStamp);
    virtual bool IsDST(long64 timeStamp, bool isLocalTime = false);
    virtual bool IsDST(ITimeZoneDSTRange * dstRange, long64 timeStamp, bool isLocalTime = false);
    virtual ITimeZoneDSTRange * GetDSTRange(long64 rangeStartDate, long64 rangeEndDate);
};

Provides functionality for timezone handling. The idea of that interface is to provide some basic functions so that the application can make the necessary calculations.

Public functions

TimeZoneName

Return value

Returns the name of the timezone which is the same as the TZ id used to get the timezone.
UTCName

Return value

Returns the utc name of the timezone, which actually is UTC + the time difference (e. G. "UTC+01:00").
UTCDiff

Return value

Returns the difference of the timezone to UTC in milliseconds.
DSTDiff

Return value

Returns the difference during active daylight saving time of the timezone to UTC in milliseconds. A value of 0 indicates, that the timezone has not daylightsaving time.
ToLocalTime
Converts the given time stamp to the timezones local time. The function considers daylightsaving time.

Parameters

long64 utcTimeThe timestamp in UTC to convert to local time. Make sure that the timestamp given is UTC, or the result will be wrong.
ToUTCTime
Converts the given local time to UTC using the rules defined by the timezone. The function considers daylightsaving time.

Parameters

long64 localTimeThe timestamp in the timezones local time to convert to UTC. Make sure that the timestamp given is realy local time for the timezone, or the result will be wrong.
RemoveDST
Removes the daylightsa ving time from the given timestamp, if the timestamp is during active daylight saving time. If not, the return value will be the same as the value given.

Parameters

long64 timeStampThe timestamp to remove the daylight saving time value.
AddDST
Add the daylight saving time difference to the given timestamp, if the timestamp points to active daylight saving time. If not, the return value is the same asa the value given.

Parameters

long64 timeStampThe timestamp to add the daylightsaving time difference.
IsDST (overloaded)
Checks if the given timestamp is during daylightsaving time or not.

Parameters

long64 timeStampThe timeStamp to check.
bool isLocalTime(Default false) If true, the given timestamp is in local time, else in UTC.
IsDST (overloaded)
Checks if the given timestamp is during daylightsaving time or not. Becuase some timezones have a lot of daylightsaving time transitions, you can pass an ITimeZoneDSTRange instance which only provides a range of it. This can optimize the check if there is need to call it frequently.

Parameters

ITimeZoneDSTRange * dstRangeAn ITimeZoneDSTRange instance to provide the time range for the checks.
long64 timeStampThe timeStamp to check.
bool isLocalTime(Default false) If true, the given timestamp is in local time, else in UTC.
GetDSTRange
If there is need to check a lot of timestamps calling IsDST(), it can be better to make the check only in a specified timerange (e. G. the timezone for Europe/Berlin provides timezone transitions back to 1900). So if the range of the minimum and maximum time to make a check is known, this can help to minimize the checks to be done. This function will create an ITimeZoneDSTRange instance which must be given to the overloaded IsDST() version.

Parameters

long64 rangeStartDateThe start timestamp for the desired range.
long64 rangeStartDateThe end timestamp for the desired range.

Return value

The ITimeZoneDSTRange instance for the desired range. It must be released by the app when now longer used.

ITimeZoneDSTRange

class ITimeZoneDSTRange {
public:
    ITimeZoneDSTRange() {};
    virtual ~ITimeZoneDSTRange() {};

    virtual class ITimeZone * TimeZone() = 0;
    virtual long64 RangeStart() = 0;
    virtual long64 RangeEnd() = 0;
};

Some timezones have a lot of daylightsaving time transitions. But when there is need to a lot of ITimeZone::IsDST() checks, it can be helpful to define a range of minimum and maximum transition to make the checks. This can be done by the help of ITimeZoneDSTRange. To get a valid instance, use ITimeZone::GetDSTRange(). However, the instance must be released by the application.

Public functions

TimeZone

Return value

Returns the instance of the ITimeZone instance the instance was created with. The daylightsaving time range is only valid for that timezone.
RangeStart

Return value

The end timestamp of the range.
RangeStart

Return value

Returns the end timestamp of the range.

Code Example

long64 now = ITime::TimeStampMilliseconds();

char tstr[21];
ITime::FormatTimeStampISO(tstr, sizeof(tstr), now);
printf("Current time UTC: %s\n", tstr);

ITimeZone * tzDE = ITimeZoneProvider::GetTimeZone(TZ_EUROPE_BERLIN, myLogInstance);
ITime::FormatTimeStampISO(tstr, sizeof(tstr), tzDE->ToLocalTime(now));
printf("Current time in Germany: %s\n", tstr);

// Output:
// Current time UTC: 2017-08-22T16:15:00
// Current time in Germany: 2017-08-22T18:15:00

Timezone IDs

The ITimeZone interface makes use of the tz database, provided by the underlying Linux OS. For each timezone exists an identifier. The list below is a set of defines to use for that ids. The names of the defines are selfexplaining.

List of tz-ids used by the tz database

Some additional items for the tz database

Windows TimeZone Mapping

Microsoft Windows uses an other type of TimeZone naming which ends up in less items. The following list of defines helps to build up a proper mapping. However, such a mapping always will be a compromise (the tz database is more detailed). The name of the defines are corespondig with the name of the Windows timezone, which should be selfexplaining. Because + and - are forbitten for define names, + had been replaced by P and - by M. Colons had been remove. So UTC+01:00 becomes UTC_M0100. The names like used by Windows itself can be found in the comments behind the mapping inside the timezone.h file.

Copyright information

The tzdb to Windows TimeZone mapping is based on the mapping made by the unicode group ( http://unicode.org/repos/cldr/trunk/common/supplemental/windowsZones.xml, the terms of use can be found under http://www.unicode.org/copyright.html), with some adjustment based on the english wikipedia artikel (http://cldr.unicode.org/development/development-process/design-proposals/extended-windows-olson-zid-mapping)