Languages Around The World

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:

  1. 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.

  2. 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.

  3. 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:

  1. TimeZone
    TimeZone is an abstract base class that defines the time zone API. This API supports conversion between GMT and local time.

  1. 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:

  1. 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.

  2. 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.

  3. Factory methods and methods for handling the default time zone.

  4. Display name methods.

  5. 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:

  1. Generic name, such as "Pacific Time". Currently, this is not supported by ICU.

  2. Standard name, such as "Pacific Standard Time".

  3. 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.

NoteNote: 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

ICU4J 3.4.1 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 3.4.1

ICU reflects Java JRE time zone data. Updates to ICU are not possible. Updates to the JRE show through to ICU.

ICU4C 2.6 and earlier

ICU4J 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.icu-project.org/download/ .

The time zone data in ICU is generated from the industry-standard TZ database using the tzcode (nhttp://source.icu-project.org/vc/icu/trunk/source/tools/tzcode/ ) tool. The ICU data files with recent time zone data can be downloaded from http://source.icu-project.org/repos/icu/data/trunk/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.

NoteNote: The example in the procedure below shows icudt32 - replace as appropriate

1. Download ICU4C binaries for latest release of from http://www.icu-project.org/download/ .

2. Unzip the binaries and run decmn.

Unix

NoteNote: 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".

3. Download the appropriate zoneinfo.res from http://source.icu-project.org/repos/icu/data/trunk/tzdata/ . The directories under directory named “icu” are named with the version of the timezone database, e.g.: data for 2006a will be in directory 2006a. Now traverse to the directory under version directory that is appropriate to your system, e.g.: download http://source.icu-project.org/repos/icu/data/trunk/tzdata/icu/2006a/le/zoneinfo.res for little endian systems, http://source.icu-project.org/repos/icu/data/trunk/tzdata/icu/2006a/be/zoneinfo.res for big endian systems and http://source.icu-project.org/repos/icu/data/trunk/tzdata/icu/2006a/ee/zoneinfo.res for EBCIDIC systems.

4. Replace the file zoneinfo.res in "icudt32(endian/codepage)/" directory with the downloaded zoneinfo.res.

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

NoteNote: “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. 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

2. Download the appropriate zoneinfo.res from http://source.icu-project.org/repos/icu/data/trunk/tzdata/ . The directories under directory named “icu” are named with the version of the timezone database, e.g.: data for 2006a will be in directory 2006a. Note that ICU4J can only load big endian version o the zoneinfo.res file. Now traverse to the directory under version directory that is appropriate to ICU4J, e.g.: download http://source.icu-project.org/repos/icu/data/trunk/tzdata/icu/2006a/be/zoneinfo.res for 2006a version.

3. Replace the zoneinfo.res file in com/ibm/icu/impl/data/icudt<icu_version>b/ directory with the downloaded zoneinfo.res.

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 - 2008 IBM and Others - PDF Version - Feedback: http://icu-project.org/contacts.html

User Guide for ICU v4.0 Generated 2008-06-02.