Delphi/FPC Time Zone Database
TZDB is an offline, in-process compiled database for IANA's (https://www.iana.org/time-zones) TZDB project.
The source code is compatible with Delphi XE+ and FreePascal 3+, though some components are only available for Delphi.
The current version of TZDB is compiled with 2024a version of IANA TZDB and the latest Windows alias translation table (from CLDR project).
API Documentation and Code Examples.
This project follows the IANA releases quite closely, usually with 1-2 weeks delay. If you are inclined to update the library manually use the shell script located in the repository: update-compile.sh.
The shell script runs under MacOS, Linux or Windows WSL. You will need Free Pascal compiler installed though.
To use TZDB you only require one file: TZDB.pas. Download it and simply add it to your uses
clause. This unit contains the whole pre-compiled TZ database and all the code required to interpret it.
All the other files in the project are optional.
After you download the files to your local project, simply include the TZDB unit in the uses
clause.
Simplest example looks like:
uses TZDB;
begin
LTimeZone := TBundledTimeZone.GetTimeZone('Africa/Cairo');
WriteLn(LTimeZone.ToUniversalTime(Now));
end.
A large number of methods are provided on the TBundledTimeZone
class that allow date/time manipulation.
There are a large number of misconceptions when it comes to time zones in general. And TZDB tries to deal with them in specific ways. The following list should shed some light on issue one might encounter during the use of this library:
TBundledTimeZone.Create
accepts both normal timezone IDs as well as Windows aliases such as European Standard Time
. The method will throw an ETimeZoneInvalid
if the given ID is unknown.EUnknownTimeZoneYear
exception. This can happen if one supplies a date/time that is not covered by the database. Example would be a date in 1800s
when such data is not available. One needs to catch such exceptions pro-actively.AForceDaylight
that defaults true
. This is due to local times potentially being ambiguous in some time periods (between daylight time and standard time, there is an hour (s) that appear twice). This argument allows the code to assign the hour to either the daylight period or the standard period.ELocalTimeInvalid
exception if the give local time is in the invalid period (between standard time and daylight time there is the missing hour(s)). Use GetLocalTimeType
to check the type of the local time before trying to operate on it.HasDaylightTime
to detect whether this is the case.AmbiguousTimeStart
or StandardTimeStart
off.DisplayName
, Abbreviation
and especially UtcOffset
properties of the TBundledTimeZone
class. These are provided for information only and will change during the year.The Time Zone Visualizer is a development tool we use to display time zone details. It is currently only supported on Windows: