A time zone represents an offset applied to Greenwich Mean Time (GMT) to obtain local time. The offset might vary throughout the year, if daylight savings time (DST) is used, or might be the same all year long. Typically, regions closer to the equator do not use DST. If DST is in use, then specific rules define the point at which the offset changes and the amount by which it changes. Thus, a time zone is described by the following information:
If DST is observed, then three additional pieces of information are needed:
ICU supports local time zones through the classes TimeZone and SimpleTimeZone in the C++ API. In the C API, time zones are designated by their ID strings.
Users can construct their own time zone objects by specifying the above information to the C++ API. However, it is more typical for users to use a pre-existing system time zone since these represent all current international time zones in use. This document lists the system time zones, both in order of GMT offset and in alphabetical order of ID.
Since this list changes one or more times a year, this document only represents a snapshot. For the most current list of ICU system zones, use the method TimeZone::getAvailableIDs().
The ICU system time zones are derived from the tz database (also known as the “Olson” database) at ftp://elsie.nci.nih.gov/pub . This is the data used across much of the industry, including by UNIX systems, and is usually updated several times each year. ICU (since version 2.8) and base Java (since Java 1.4) contain code and tz data supporting both current and historic time zone usage.
ICU represents dates and times using UDates. A UDate is a scalar value that indicates a specific point in time, independent of calendar system and local time zone. It is stored as the number of milliseconds from a reference point known as the epoch. The epoch is midnight Universal Time Coordinated (UTC) January 1, 1970 A.D. Negative UDate values indicate times before the epoch.
Most people only need to use the DateFormat classes for parsing and formatting dates and times. However, for those who need to convert dates and times or perform numeric calculations, the services described in this section can be very useful.
To translate a UDate to a useful form, a calendar system and local time zone must be specified. These are specified in the form of objects of the Calendar and TimeZone classes. Once these two objects are specified, they can be used to convert the UDate to and from its corresponding calendar fields. The different fields are defined in the Calendar class and include the year, month, day, hour, minute, second, and so on.
Specific Calendar objects correspond to calendar systems (such as Gregorian) and conventions (such as the first day of the week) in use in different parts of the world. To obtain a Calendar object for France, for example, call Calendar::createInstance(Locale::getFrance(), status).
The TimeZone class defines the conversion between universal coordinated time (UTC),, and local time, according to real-world rules. Different TimeZone objects correspond to different real-world time zones. For example, call TimeZone::createTimeZone("America/Los_Angeles") to obtain an object that implements the U.S. Pacific time zone, both Pacific Standard Time (PST) and Pacific Daylight Time (PDT).
As previously mentioned, the Calendar and TimeZone objects must be specified correctly together. One way of doing so is to create each independently, then use the Calendar::setTimeZone() method to associate the time zone with the calendar. Another is to use the Calendar::createInstance() method that takes a TimeZone object. For example, call Calendar::createInstance( TimeZone::createInstance( "America/Los_Angeles"), Locale:getUS(), status) to obtain a Calendar appropriate for use in the U.S. Pacific time zone.
ICU has four classes pertaining to calendars and timezones: