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.

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.

The time zone data in ICU is generated from the industry-standard TZ database using the tzcode (http://source.icu-project.org/repos/icu/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/icu/ .

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 icudt38l.dat (ICU4C 3.8 data file for little endian platforms) updated with the newer time zone data.

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

2. Unzip the binaries and set up environment variables.

Unix

mkdir icu
cd icu
tar -xzvf icu4c-3_8_1-RHEL5-gcc4_1_1.tgz
cd ..
export LD_LIBRARY_PATH=~/icu/usr/local/lib:$LD_LIBRARY_PATH
export PATH=~/icu/usr/local/sbin:$PATH

Windows

mkdir c:\work\icu
cd icu
unzip icu4c-3_8_1-Win32-msvc8.zip
cd ..
SET PATH=c:\work\icu\lib;c:\work\icu\bin;%PATH%

3. Download the appropriate time zone data resource file(s) from http://source.icu-project.org/repos/icu/data/trunk/tzdata/icu/ . Each directory contains the ICU time zone data for the tzdata version, e.g.: data for tzdata version 2008e is in directory named “2008e”. 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/2008e/le/zoneinfo.res for little endian systems, http://source.icu-project.org/repos/icu/data/trunk/tzdata/icu/2008e/be/zoneinfo.res for big endian systems and  http://source.icu-project.org/repos/icu/data/trunk/tzdata/icu/2008e/ee/zoneinfo.res for EBCIDIC systems.  For ICU4C 3.8.1 or later releases, you will also need metazoneInfo.res in the same directory if exists.

4. Replace the resource zoneinfo.res in icudt38l.dat with the downloaded version.

icupkg -a zoneinfo.res icudt38l.dat

5. Replace the resource metazoneInfo.res in icudt38l.dat with the downloaded version. (ICU4C 3.8.1 or later releases only)

icupkg -a metazoneInfo.res icudt38l.dat

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 ~/work
cd ~/work
cp <dir>/icu4j.jar .
jar xvf icu4j.jar 

Windows

mkdir c:\work
cd c:\work
copy <dir>\icu4j.jar .
jar xvf icu4j.jar

2. Download the appropriate time zone data resource file(s) from http://source.icu-project.org/repos/icu/data/trunk/tzdata/icu/ . Each directory contains the ICU time zone data for the tzdata version, e.g.: data for tzdata version 2008e is in directory named “2008e”.  Note that ICU4J can only load big endian version of the resource files. 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/2008e/be/zoneinfo.res for 2008e version.  For ICU4J 3.8.1 or later releases, you will also need metazoneInfo.res in the same directory if exists.

3. Replace the zoneinfo.res file in com/ibm/icu/impl/data/icudt<icu_version>b/ directory with the downloaded zoneinfo.res.  For ICU4J 3.8.1 or later release, replace metazoneInfo.res in the same directory with the downloaded version.

4. Replace the resource zoneinfo.res in icu4j.jar with the downloaded version.

Unix

jar uvf icu4j.jar com/ibm/icu/impl/data/icudt38b/zoneinfo.res

Windows

jar uvf icu4j.jar com\ibm\icu\impl\data\icudt38b\zoneinfo.res

5. Replace the resource metazoneInfo.res in icu4j.jar with the downloaded verson. (ICU4J 3.8.1 or later releases only)

Unix

jar uvf icu4j.jar com/ibm/icu/impl/data/icudt38b/metazoneInfo.res

Windows

jar uvf icu4j.jar com\ibm\icu\impl\data\icudt38b\metazoneInfo.res

Copyright (c) 2000 - 2008 IBM and Others - PDF Version - Feedback: http://icu-project.org/contacts.html

User Guide for ICU v4.0 Generated 2008-08-20.