1--- 2layout: default 3title: TimeZone Classes 4nav_order: 3 5parent: Date/Time 6--- 7<!-- 8© 2020 and later: Unicode, Inc. and others. 9License & terms of use: http://www.unicode.org/copyright.html 10--> 11 12# ICU TimeZone Classes 13{: .no_toc } 14 15## Contents 16{: .no_toc .text-delta } 17 181. TOC 19{:toc} 20 21--- 22 23## Overview 24 25A time zone is a system that is used for relating local times in different 26geographical areas to one another. For example, in the United States, Pacific 27Time is three hours earlier than Eastern Time; when it's 6 P.M. in San 28Francisco, it's 9 P.M. in Brooklyn. To make things simple, instead of relating 29time zones to one another, all time zones are related to a common reference 30point. 31 32For historical reasons, the reference point is Greenwich, England. Local time in 33Greenwich is referred to as Greenwich Mean Time, or GMT. (This is similar, but 34not precisely identical, to Universal Coordinated Time, or UTC. We use the two 35terms interchangeably in ICU since ICU does not concern itself with either leap 36seconds or historical behavior.) Using this system, Pacific Time is expressed as 37GMT-8:00, or GMT-7:00 in the summer. The offset -8:00 indicates that Pacific 38Time is obtained from GMT by adding -8:00, that is, by subtracting 8 hours. 39 40The offset differs in the summer because of daylight savings time, or DST. At 41this point it is useful to define three different flavors of local time: 42 43* **Standard Time**: 44 Standard Time is local time without a daylight savings time offset. For 45 example, in California, standard time is GMT-8:00; that is, 8 hours before 46 GMT. 47* **Daylight Savings Time**: 48 Daylight savings time is local time with a daylight savings time offset. 49 This offset is typically one hour, but is sometimes less. In California, 50 daylight savings time is GMT-7:00. Daylight savings time is observed in most 51 non-equatorial areas. 52* **Wall Time**: 53 Wall time is what a local clock on the wall reads. In areas that observe 54 daylight savings time for part of the year, wall time is either standard 55 time or daylight savings time, depending on the date. In areas that do not 56 observe daylight savings time, wall time is equivalent to standard time. 57 58## Time Zones in ICU 59 60ICU supports time zones through two classes: 61 62* **TimeZone**: 63 `TimeZone` is an abstract base class that defines the time zone API. This API 64 supports conversion between GMT and local time. 65* **SimpleTimeZone**: 66 `SimpleTimeZone` is a concrete subclass of TimeZone that implements the 67 standard time zones used today internationally. 68 69Timezone classes are related to `UDate`, the `Calendar` classes, and the 70`DateFormat` classes. 71 72### Timezone Class in ICU 73 74`TimeZone` is an abstract base class. It defines common protocol for a hierarchy 75of classes. This protocol includes: 76 77* A programmatic ID, for example, "America/Los_Angeles". This ID is used to 78 call up a specific real-world time zone. It corresponds to the IDs defined 79 in the [IANA Time Zone datbase](https://www.iana.org/time-zones) used by UNIX 80 and other systems, and has the format continent/city or ocean/city. 81* A raw offset. This is the difference, in milliseconds, between a time zone's 82 standard time and GMT. Positive raw offsets are east of Greenwich. 83* Factory methods and methods for handling the default time zone. 84* Display name methods. 85* An API to compute the difference between local wall time and GMT. 86 87#### Factory Methods and the Default Timezone 88 89The TimeZone factory method `createTimeZone()` creates and returns a `TimeZone` 90object given a programmatic ID. The user does not know what the class of the 91returned object is, other than that it is a subclass of `TimeZone`. 92 93The `createAvailableIDs()` methods return lists of the programmatic IDs of all 94zones known to the system. These IDs may then be passed to `createTimeZone()` to 95create the actual time zone objects. ICU maintains a comprehensive list of 96current international time zones, as derived from the Olson data. 97 98`TimeZone` maintains a static time zone object known as the *default time zone*. 99This is the time zone that is used implicitly when the user does not specify 100one. ICU attempts to match this to the host OS time zone. The user may obtain a 101clone of the default time zone by calling `createDefault()` and may change the 102default time zone by calling `setDefault()` or `adoptDefault()`. 103 104#### Display Name 105 106When displaying the name of a time zone to the user, use the display name, not 107the programmatic ID. The display name is returned by the `getDisplayName()` 108method. A time zone may have three display names: 109 110* Generic name, such as "Pacific Time". 111* Standard name, such as "Pacific Standard Time". 112* Daylight savings name, such as "Pacific Daylight Time". 113 114Furthermore, each of these names may be LONG or SHORT. The SHORT form is 115typically an abbreviation, e.g., "PST", "PDT". 116 117In addition to being available directly from the `TimeZone` API, the display name 118is used by the date format classes to format and parse time zones. 119 120#### getOffset() API 121 122`TimeZone` defines the API `getOffset()` by which the caller can determine the 123difference between local time and GMT. This is a pure virtual API, so it is 124implemented in the concrete subclasses of `TimeZone`. 125 126## Updating the Time Zone Data 127 128Time zone data changes often in response to governments around the world 129changing their local rules and the areas where they apply. ICU derives its tz 130data from the [IANA Time Zone Database](http://www.iana.org/time-zones). 131 132The ICU project publishes updated timezone resource data in response to IANA 133updates, and these can be used to patch existing ICU installations. Several 134update strategies are possible, depending on the ICU version and configuration. 135 136* ICU4J: Use the time zone update utility. 137* ICU4C 54 and newer: Drop in the binary update files. 138* ICU4C 36 and newer: the best update strategy will depend on how ICU data 139 loading is configured for the specific ICU installation. 140 * Data is loaded from a .dat package file: replace the time zone resources 141 in the .dat file using the icupkg tool. 142 * Data is loaded from a .dll or .so shared library: obtain the updated 143 sources for the tz resources and rebuild the data library. 144 * Data is loaded from individual files: drop in the updated binary .res 145 files. 146 147The [ICU Data](../../icudata.md) section of this user guide gives more 148information on how ICU loads resources. 149 150The ICU resource files required for time zone data updates are posted at 151<https://github.com/unicode-org/icu-data/tree/master/tzdata/icunew>. The 152required resource files for ICU version 44 and newer are 153 154* zoneinfo64.res 155* windowsZones.res 156* timezoneTypes.res 157* metaZones.res 158 159### ICU4C TZ update of a .dat Package File 160 161For ICU configurations that load data from a .dat package file, replace the time 162zone resources in that file. 163 1641. Download the new .res files from 165 `https://github.com/unicode-org/icu-data/tree/master/tzdata/icunew/<IANA tz version>/44/<platform directory>`. 166 * `<IANA tz version>` is a combination of year and letter, such as "2019c". 167 * *"44"* is the directory for updates to ICU version 4.4 and newer. 168 * `<platform directory>` is "le" for little endian processors, including 169 all Intel processors. 170 * `<platform directory>` is "be" for big endian processors, including IBM 171 Power and Sparc. 172 * `<platform directory>` is "ee" for IBM mainframes using EBCDIC character 173 sets. 1742. Check that the tool "icupkg" is available. If not already on your system, 175 you can get it by [downloading](https://github.com/unicode-org/icu/releases) 176 and building ICU, following the instructions in the ReadMe file included in 177 the download. Alternatively, on many Linux systems, "apt-get install 178 icu-devtools" will install the tool. 1793. Locate the .dat file to be updated, and do the update. The commands below 180 are for a .dat file named icudt55l.dat. 181 182```shell 183icupkg -a zoneinfo64.res icudt55l.dat 184icupkg -a windowsZones.res icudt55l.dat 185icupkg -a timezoneTypes.res icudt55l.dat 186icupkg -a metaZones.res icudt55l.dat 187``` 188 189In ICU versions older than 4.4 some of the time zone resources have slightly 190different names. The update procedure is the same, but substitute the names 191found in the desired download directory - 42, 40, 38 or 36. 192 193### ICU4C TZ Update with Drop-in .res files (ICU 54 and newer) 194 195With this approach, the four individual .res files are dropped in any convenient 196location in the file system, and ICU is given an absolute path to the directory 197containing them. For the time zone resources only, ICU will check this directory 198first when loading data. This approach will work even when all other ICU data 199loading is from a shared library or .dat file. 200 201There are two ways to specify the directory: 202 203* At ICU build time, by defining the C pre-processor variable 204 `U_TIMEZONE_FILES_DIR` to the run time path to the directory containing the 205 .res files. 206* At run time, by setting the environment variable `ICU_TIMEZONE_FILES_DIR` to 207 the absolute path of the directory containing the .res files. 208 209If both are defined, the environment variable `ICU_TIMEZONE_FILES_DIR` take 210precedence. If either is defined, the time zone directory will be checked first, 211meaning that time zone resource files placed there will override time zone 212resources that may exist in other ICU data locations. 213 214To do the update, download the .res files appropriate for the platform, as 215described for the .dat file update above, and copy them into the time zone res 216file directory. 217 218### ICU4C TZ update when ICU is configured for individual files 219 220If the ICU-using application sets an ICU data path (or can be changed to set 221one), then the time zone .res file can be placed there. Download the files as 222described above and copy them to the specified directory. See the 223[ICU Data](../../icudata.md) page of the user guide for more information about 224the ICU data path. 225 226### ICU4C TZ update when ICU data is built into a shared library 227 2281. Set up the environment necessary to rebuild your specific configuration of 229 ICU. 2302. Download the .txt file sources for the updated resources from 231 `https://github.com/unicode-org/icu-data/tree/master/tzdata/icunew/<IANA tz version>/44` 2323. Copy the downloaded .txt files into the ICU sources for your installation, 233 in the subdirectory source/data/misc/ 2344. Rebuid ICU. 2355. Copy the freshly built ICU data shared library to the desired destination. 236 237> :point_right: **Note**: The standard ICU download package contains pre-built 238> ICU data. To rebuild ICU data from .txt files, you will need to replace the 239> contents of `icu4c/source/data` with the contents of ICU4C data.zip. See 240> [ICU Data Build Tool](../../icu_data/buildtool.md) for more details. 241 242There are too many possible platform variations to be more specific about how to 243rebuild ICU4C in these instructions. See the ReadMe file included with the ICU 244sources for general information on building ICU. 245 246### Update the time zone data for ICU4J 247 248The [ICU4J Time Zone Update Update 249Utility](http://site.icu-project.org/download/icutzu) automates the process of 250updating ICU4J jar files with the latest time zone data. Instructions for use 251are [here](https://htmlpreview.github.io/?https://github.com/unicode-org/icu-data/blob/master/tzdata/tzu/readme.html). 252 253The updater will work with ICU version 3.4.2 and newer. 254 255## Sample Code 256 257See the [Date and Time Zone Examples](examples.md) subpage. 258