1--- 2layout: default 3title: Date/Time 4nav_order: 6 5has_children: true 6--- 7<!-- 8© 2020 and later: Unicode, Inc. and others. 9License & terms of use: http://www.unicode.org/copyright.html 10--> 11 12# Date/Time Services 13{: .no_toc } 14 15## Contents 16{: .no_toc .text-delta } 17 181. TOC 19{:toc} 20 21--- 22 23## Overview of ICU System Time Zones 24 25A time zone represents an offset applied to Greenwich Mean Time (GMT) to obtain 26local time. The offset might vary throughout the year, if daylight savings time 27(DST) is used, or might be the same all year long. Typically, regions closer to 28the equator do not use DST. If DST is in use, then specific rules define the 29point at which the offset changes and the amount by which it changes. Thus, a 30time zone is described by the following information: 31 32* An identifying string, or ID. This consists only of invariant characters 33 (see the file `utypes.h`). It typically has the format continent / city. The 34 city chosen is not the only city in which the zone applies, but rather a 35 representative city for the region. Some IDs consist of three or four 36 uppercase letters; these are legacy zone names that are aliases to standard 37 zone names. 38 39* An offset from GMT, either positive or negative. Offsets range from 40 approximately minus half a day to plus half a day. 41 42If DST is observed, then three additional pieces of information are needed: 43 441. The precise date and time during the year when DST begins. In the first half 45 of the year it's in the northern hemisphere, and in the second half of the 46 year it's in the southern hemisphere. 47 482. The precise date and time during the year when DST ends. In the first half 49 of the year it's in the southern hemisphere, and in the second half of the 50 year it's in the northern hemisphere. 51 523. The amount by which the GMT offset changes when DST is in effect. This is 53 almost always one hour. 54 55### System and User Time Zones 56 57ICU supports local time zones through the classes `TimeZone` and `SimpleTimeZone` in 58the C++ API. In the C API, time zones are designated by their ID strings. 59 60Users can construct their own time zone objects by specifying the above 61information to the C++ API. However, it is more typical for users to use a 62pre-existing system time zone since these represent all current international 63time zones in use. This document lists the system time zones, both in order of 64GMT offset and in alphabetical order of ID. 65 66Since this list changes one or more times a year, *this document only represents 67a snapshot*. For the most current list of ICU system zones, use the method 68`TimeZone::getAvailableIDs()`. 69 70*The zones are listed in binary sort order (that is, 'A' through 'Z' come before 71'a' through 'z'). This is the same order in which the zones are stored 72internally, and the same order in which they are returned by 73`TimeZone::getAvailableIDs()`. The reason for this is that ICU locates zones using 74a binary search, and the binary search relies on this sort order.* 75*You might notice that zones such as Etc/GMT+1 appear to have the wrong sign for 76their GMT offset. In fact, their sign is inverted since the the Etc zones follow 77the POSIX sign conventions. This is the way the original Olson data is set up, 78and ICU reproduces the Olson data faithfully. See the Olson files for more 79details.* 80 81### References 82 83The ICU system time zones are derived from the tz database (also known as the 84“Olson” database) at [ftp://elsie.nci.nih.gov/pub](ftp://elsie.nci.nih.gov/pub). 85This is the data used across much of the industry, including by UNIX systems, 86and is usually updated several times each year. ICU (since version 2.8) and base 87Java (since Java 1.4) contain code and tz data supporting both current and 88historic time zone usage. 89 90## How ICU Represents Dates/Times 91 92ICU represents dates and times using `UDate`s. A `UDate` is a scalar value that 93indicates a specific point in time, independent of calendar system and local 94time zone. It is stored as the number of milliseconds from a reference point 95known as the epoch. The epoch is midnight Universal Time Coordinated (UTC) 96January 1, 1970 A.D. Negative `UDate` values indicate times before the epoch. 97 98*These classes have the same architecture as the Java classes.* 99 100Most people only need to use the `DateFormat` classes for parsing and formatting 101dates and times. However, for those who need to convert dates and times or 102perform numeric calculations, the services described in this section can be very 103useful. 104 105To translate a `UDate` to a useful form, a calendar system and local time zone 106must be specified. These are specified in the form of objects of the `Calendar` 107and `TimeZone` classes. Once these two objects are specified, they can be used to 108convert the `UDate` to and from its corresponding calendar fields. The different 109fields are defined in the `Calendar` class and include the year, month, day, hour, 110minute, second, and so on. 111 112Specific `Calendar` objects correspond to calendar systems (such as Gregorian) and 113conventions (such as the first day of the week) in use in different parts of the 114world. To obtain a `Calendar` object for France, for example, call 115`Calendar::createInstance(Locale::getFrance(), status)`. 116 117The `TimeZone` class defines the conversion between universal coordinated time 118(UTC), and local time, according to real-world rules. Different `TimeZone` 119objects correspond to different real-world time zones. For example, call 120`TimeZone::createTimeZone("America/Los_Angeles")` to obtain an object that 121implements the U.S. Pacific time zone, both Pacific Standard Time (PST) and 122Pacific Daylight Time (PDT). 123 124As previously mentioned, the `Calendar` and `TimeZone` objects must be specified 125correctly together. One way of doing so is to create each independently, then 126use the `Calendar::setTimeZone()` method to associate the time zone with the 127calendar. Another is to use the `Calendar::createInstance()` method that takes a 128`TimeZone` object. For example, call `Calendar::createInstance( 129TimeZone::createInstance( "America/Los_Angeles"), Locale:getUS(), status)` to 130obtain a `Calendar` appropriate for use in the U.S. Pacific time zone. 131 132ICU has four classes pertaining to calendars and timezones: 133 134* [`Calendar`](calendar/index.md) 135 136 `Calendar` is an abstract base class that represents a calendar system. 137 `Calendar` objects map `UDate` values to and from the individual fields used in 138 a particular calendar system. `Calendar` also performs field computations such 139 as advancing a date by two months. 140 141* [`Gregorian Calendar`](calendar/index.md) 142 143 `GregorianCalendar` is a concrete subclass of `Calendar` that implements the 144 rules of the Julian calendar and the Gregorian calendar, which is the common 145 calendar in use internationally today. 146 147* [`TimeZone`](timezone/index.md) 148 149 `TimeZone` is an abstract base class that represents a time zone. `TimeZone` 150 objects map between universal coordinated time (UTC) and local time. 151 152* [`SimpleTimeZone`](timezone/index.md) 153 154 `SimpleTimeZone` is a concrete subclass of `TimeZone` that implements standard 155 time and daylight savings time according to real-world rules. Individual 156 `SimpleTimeZone` objects correspond to real-world time zones. 157