
ICU TimeZone Classes
Overview
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:
-
Standard Time
Standard Time is local time without a daylight savings time offset. For example, in California, standard time is GMT-8:00; that is, 8 hours before GMT. -
Daylight Savings Time
Daylight savings time is local time with a daylight savings time offset. This offset is typically one hour, but is sometimes less. In California, daylight savings time is GMT-7:00. Daylight savings time is observed in most non-equatorial areas. -
Wall Time
Wall time is what a local clock on the wall reads. In areas that observe daylight savings time for part of the year, wall time is either standard time or daylight savings time, depending on the date. In areas that do not observe daylight savings time, wall time is equivalent to standard time.
Time Zones in ICU
ICU supports time zones through two classes:
-
TimeZone
TimeZone is an abstract base class that defines the time zone API. This API supports conversion between GMT and local time.
-
SimpleTimeZone
SimpleTimeZone is a concrete subclass of TimeZone that implements the standard time zones used today internationally.
Timezone classes are related to UDate, the Calendar classes, and the DateFormat classes.
Timezone Class in ICU
TimeZone is an abstract base class. It defines common protocol for a hierarchy of classes. This protocol includes:
-
A programmatic ID, for example, "America/Los_Angeles". This ID is used to call up a specific real-world time zone. It corresponds to the IDs defined in the standard Olson data used by UNIX systems, and has the format continent/city or ocean/city.
-
A raw offset. This is the difference, in milliseconds, between a time zone's standard time and GMT. Positive raw offsets are east of Greenwich.
-
Factory methods and methods for handling the default time zone.
-
Display name methods.
-
An API to compute the difference between local wall time and GMT.
Factory Methods and the Default Timezone
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 TimeZone.
The 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 setDefault() or adoptDefault().
Display Name
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:
-
Generic name, such as "Pacific Time". Currently, this is not supported by ICU.
-
Standard name, such as "Pacific Standard Time".
-
Daylight savings name, such as "Pacific Daylight Time".
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.
getOffset() API
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 TimeZone.
![]() | Note: Users should not call getOffset() directly. This API is intended for use by the Calendar classes. To convert between local and GMT time, create an appropriate Calendar object, link it to the desired TimeZone object, and use the Calendar API. |
Updating the Time Zone Data
Time zone data changes often in response to governments around the world changing their local rules and the areas where they apply. The ICU time zone data is updated for each release, and the easiest way to stay up to date may be to upgrade to the latest ICU release, which also provides bug fixes, code improvements and additional features.
If an ICU upgrade is not practical, then an old ICU installation needs to be updated. As with other systems (and very similar to with currency changes), it is only possible to update a system either after the new rules are already in effect, or if the system supports historical time zones, that is, for a given time zone ID it supports different rules for different years. For example, if a system is updated in 2006 with time zone data that includes the 2007 changes to US daylight savings time rules, then it needs to apply the old rules in 2006 and earlier years and the new rules in 2007 and later. Please use the following table to figure out whether time zone data can be updated for the version of ICU that you are using.
ICU4C 2.8 and newer |
Time zone data can be updated. Updates may include changes that do not take effect until a date in the future. |
ICU4J 2.8 to ICU4J 3.4.1 |
ICU reflects Java JRE time zone data. Updates to ICU are not possible. Updates to the JRE show through to ICU. |
ICU4J 2.6 and earlier ICU4C 2.6 and earlier |
Time zone data cannot be updated in these versions |
We are providing ICU4C 3.4.1 and ICU4J 3.4.3 maintenance releases with the updated version 2006a of Olson time zone data and bug fixes. Please see the download page for more details at http://www.ibm.com/software/globalization/icu/downloads.jsp .
The time zone data in ICU is generated from the industry-standard TZ database using the tzcode (http://dev.icu-project.org/cgi-bin/viewcvs.cgi/icu/source/tools/tzcode/ ) tool. The ICU data files with recent time zone data can be downloaded from ftp://ftp.software.ibm.com/software/globalization/icu/tzdata .
Update the time zone data for ICU4C
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. (It needs to have the proper platform endianness.)
Otherwise, if the ICU data is installed as a .dat package file, the .res file can be integrated using the new icupkg tool.
Otherwise - if the data is packaged into a DLL and the data path is not set - the .txt source data file can be used to rebuild the data DLL.
![]() | Note: The example in the procedure below shows icudt32 - replace as appropriate |
1. Download the timezone data file tzdata.zip/tar.gz from ftp://ftp.software.ibm.com/software/globalization/icu/tzdata and unzip.
Unix
cd /temp |
Windows
mkdir c:\work\temp cd c:\work\temp unzip tzdata.zip . |
2. Download ICU4C binaries for latest release of from http://www.ibm.com/software/globalization/icu/downloads.jsp .
3. Unzip the binaries and run decmn.
Unix
![]() | Note: Try running “icu-config –invoke” for the command to invoke decmn |
mkdir icu cd icu tar -xzvf icu-3.4.1-RHEL3-gcc3.2.3.tgz cd .. export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/icu/usr/local/lib export PATH=$PATH:~/icu/usr/local/bin cd <the directory where icudt32.dat is located> decmn icudt32l.dat |
Windows
mkdir c:\work\icu cd icu unzip icu-3.4.1-Win32-msvc7.1.zip cd .. SET PATH=$PATH;c:\work\icu\lib;c:\work\icu\bin cd <the directory where icudt32.dat is located> decmn icudt32l.dat > icudt32l.lst |
This will produce a directory, for example, "icudt32b".
4. Replace the file zoneinfo.res in "icudt32(endian/codepage)/" directory with Select apropos to your system zoneinfo.res (BE, LE, EBCDIC BE) from the unzipped directory.
Unix
cd icudt32l cp /temp/le/zoneinfo.res . |
Windows
cd icudt32l copy c:\work\temp\le\zoneinfo.res . |
5. Create a list file.
Unix
find icudt32l -type f > icudt32l.lst |
Windows
Edit the icudt32l.lst file that was created in step 4 by decmn and replace “.\icudt32l/” with “icudt32l/” and make sure that it only contains lines such as “icudt32l/<names of files>”.
6. Rebuild the dat file.
gencmn -v -n icudt32l 0 < icudt32l.lst |
![]() | Note: “0” after the data file name is the digit zero and is an argument to gencm. This command will generate a new dat file. Make sure you back up your old dat file. |
7. Download testtz.zip file from ftp://ftp.software.ibm.com/software/globalization/icu/tzdata and unzip.
8. Compile and run the test program to verify that the data file works.
There will probably be failures of tests that are run against the updated dat file due to change in rules for Daylight Saving Time.
Update the time zone data for ICU4J 3.4.2 and later
Follow the procedure below:
1. Download the time zone data file from ftp://ftp.software.ibm.com/software/globalization/icu/tzdata and unzip.
Unix
cd /temp tar -xzvf ~/tzdata.tar.gz |
Windows
mkdir c:\work\temp cd c:\work\temp unzip tzdata.zip . |
2. Extract the contents of ICU4J .jar file into a temporary directory.
Unix
mkdir ~/bin cd ~/bin /java/bin/jar -xvf <dir>/icu4j.jar |
Windows
mkdir c:\work\bin cd c:\work\bin c:\java\bin\jar -xvf <dir>\icu4j.jar |
3. Replace the zoneinfo.res file in com/ibm/icu/impl/data/icudt<icu_version>b/ directory.
Unix
cd ~/bin/com/ibm/icu/impl/data/icudt32b/ cp /temp/be/zoneinfo.res . |
Windows
cd c:\work\bin\com\ibm\icu\impl\data\icudt32b\ copy c:\temp\be\zoneinfo.res . |
4. Repackage icu4j.jar
jar cvf icu4j.jar mymanifest . |
Copyright (c) 2000 - 2006 IBM and Others - PDF Version - Feedback: http://icu.sourceforge.net/contacts.html
User Guide for ICU v3.6 Generated 2006-08-31.