
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.
![]() | 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. |
Copyright (c) 2000 - 2004 IBM and Others - PDF Version - Feedback: icu-issues@oss.software.ibm.com
User Guide for ICU v3.2 Generated 2004-11-22.