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:

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.

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

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:

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.

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


Copyright (c) 2000 - 2005 IBM and Others - PDF Version - Feedback: http://icu.sourceforge.net/contacts.html

User Guide for ICU v3.4 Generated 2005-07-27.