A time zone is a system that is used for relating local times in different geographical areas to one another. For example, in the United States, Pacific Time is three hours earlier than Eastern Time; when it‘s 6 P.M. in San Francisco, it’s 9 P.M. in Brooklyn. To make things simple, instead of relating time zones to one another, all time zones are related to a common reference point.
For historical reasons, the reference point is Greenwich, England. Local time in Greenwich is referred to as Greenwich Mean Time, or GMT. (This is similar, but not precisely identical, to Universal Coordinated Time, or UTC. We use the two terms interchangeably in ICU since ICU does not concern itself with either leap seconds or historical behavior.) Using this system, Pacific Time is expressed as GMT-8:00, or GMT-7:00 in the summer. The offset -8:00 indicates that Pacific Time is obtained from GMT by adding -8:00, that is, by subtracting 8 hours.
The offset differs in the summer because of daylight savings time, or DST. At this point it is useful to define three different flavors of local time:
ICU supports time zones through two classes:
TimeZoneis an abstract base class that defines the time zone API. This API supports conversion between GMT and local time.
SimpleTimeZoneis a concrete subclass of TimeZone that implements the standard time zones used today internationally.
Timezone classes are related to
Calendar classes, and the
TimeZone is an abstract base class. It defines common protocol for a hierarchy of classes. This protocol includes:
The TimeZone factory method
createTimeZone() creates and returns a
TimeZone object given a programmatic ID. The user does not know what the class of the returned object is, other than that it is a subclass of
createAvailableIDs() methods return lists of the programmatic IDs of all zones known to the system. These IDs may then be passed to
createTimeZone() to create the actual time zone objects. ICU maintains a comprehensive list of current international time zones, as derived from the Olson data.
TimeZone maintains a static time zone object known as the default time zone. This is the time zone that is used implicitly when the user does not specify one. ICU attempts to match this to the host OS time zone. The user may obtain a clone of the default time zone by calling
createDefault() and may change the default time zone by calling
When displaying the name of a time zone to the user, use the display name, not the programmatic ID. The display name is returned by the
getDisplayName() method. A time zone may have three display names:
Furthermore, each of these names may be LONG or SHORT. The SHORT form is typically an abbreviation, e.g., “PST”, “PDT”.
In addition to being available directly from the
TimeZone API, the display name is used by the date format classes to format and parse time zones.
TimeZone defines the API
getOffset() by which the caller can determine the difference between local time and GMT. This is a pure virtual API, so it is implemented in the concrete subclasses of
Time zone data changes often in response to governments around the world changing their local rules and the areas where they apply. ICU derives its tz data from the IANA Time Zone Database.
The ICU project publishes updated timezone resource data in response to IANA updates, and these can be used to patch existing ICU installations. Several update strategies are possible, depending on the ICU version and configuration.
The ICU Data section of this user guide gives more information on how ICU loads resources.
The ICU resource files required for time zone data updates are posted at https://github.com/unicode-org/icu-data/tree/master/tzdata/icunew. The required resource files for ICU version 44 and newer are
For ICU configurations that load data from a .dat package file, replace the time zone resources in that file.
https://github.com/unicode-org/icu-data/tree/master/tzdata/icunew/<IANA tz version>/44/<platform directory>.
<IANA tz version>is a combination of year and letter, such as “2019c”.
<platform directory>is “le” for little endian processors, including all Intel processors.
<platform directory>is “be” for big endian processors, including IBM Power and Sparc.
<platform directory>is “ee” for IBM mainframes using EBCDIC character sets.
icupkg -a zoneinfo64.res icudt55l.dat icupkg -a windowsZones.res icudt55l.dat icupkg -a timezoneTypes.res icudt55l.dat icupkg -a metaZones.res icudt55l.dat
In ICU versions older than 4.4 some of the time zone resources have slightly different names. The update procedure is the same, but substitute the names found in the desired download directory - 42, 40, 38 or 36.
With this approach, the four individual .res files are dropped in any convenient location in the file system, and ICU is given an absolute path to the directory containing them. For the time zone resources only, ICU will check this directory first when loading data. This approach will work even when all other ICU data loading is from a shared library or .dat file.
There are two ways to specify the directory:
U_TIMEZONE_FILES_DIRto the run time path to the directory containing the .res files.
ICU_TIMEZONE_FILES_DIRto the absolute path of the directory containing the .res files.
If both are defined, the environment variable
ICU_TIMEZONE_FILES_DIR take precedence. If either is defined, the time zone directory will be checked first, meaning that time zone resource files placed there will override time zone resources that may exist in other ICU data locations.
To do the update, download the .res files appropriate for the platform, as described for the .dat file update above, and copy them into the time zone res file directory.
If the ICU-using application sets an ICU data path (or can be changed to set one), then the time zone .res file can be placed there. Download the files as described above and copy them to the specified directory. See the ICU Data page of the user guide for more information about the ICU data path.
https://github.com/unicode-org/icu-data/tree/master/tzdata/icunew/<IANA tz version>/44
:point_right: Note: The standard ICU download package contains pre-built ICU data. To rebuild ICU data from .txt files, you will need to replace the contents of
icu4c/source/datawith the contents of ICU4C data.zip. See ICU Data Build Tool for more details.
There are too many possible platform variations to be more specific about how to rebuild ICU4C in these instructions. See the ReadMe file included with the ICU sources for general information on building ICU.
The updater will work with ICU version 3.4.2 and newer.
See the Date and Time Zone Examples subpage.