timezone.h (46682B)
1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /************************************************************************* 4 * Copyright (c) 1997-2016, International Business Machines Corporation 5 * and others. All Rights Reserved. 6 ************************************************************************** 7 * 8 * File TIMEZONE.H 9 * 10 * Modification History: 11 * 12 * Date Name Description 13 * 04/21/97 aliu Overhauled header. 14 * 07/09/97 helena Changed createInstance to createDefault. 15 * 08/06/97 aliu Removed dependency on internal header for Hashtable. 16 * 08/10/98 stephen Changed getDisplayName() API conventions to match 17 * 08/19/98 stephen Changed createTimeZone() to never return 0 18 * 09/02/98 stephen Sync to JDK 1.2 8/31 19 * - Added getOffset(... monthlen ...) 20 * - Added hasSameRules() 21 * 09/15/98 stephen Added getStaticClassID 22 * 12/03/99 aliu Moved data out of static table into icudata.dll. 23 * Hashtable replaced by new static data structures. 24 * 12/14/99 aliu Made GMT public. 25 * 08/15/01 grhoten Made GMT private and added the getGMT() function 26 ************************************************************************** 27 */ 28 29 #ifndef TIMEZONE_H 30 #define TIMEZONE_H 31 32 #include "unicode/utypes.h" 33 34 #if U_SHOW_CPLUSPLUS_API 35 36 /** 37 * \file 38 * \brief C++ API: TimeZone object 39 */ 40 41 #if !UCONFIG_NO_FORMATTING 42 43 #include "unicode/uobject.h" 44 #include "unicode/unistr.h" 45 #include "unicode/ures.h" 46 #include "unicode/ucal.h" 47 48 U_NAMESPACE_BEGIN 49 50 class StringEnumeration; 51 52 /** 53 * 54 * <code>TimeZone</code> represents a time zone offset, and also figures out daylight 55 * savings. 56 * 57 * <p> 58 * Typically, you get a <code>TimeZone</code> using <code>createDefault</code> 59 * which creates a <code>TimeZone</code> based on the time zone where the program 60 * is running. For example, for a program running in Japan, <code>createDefault</code> 61 * creates a <code>TimeZone</code> object based on Japanese Standard Time. 62 * 63 * <p> 64 * You can also get a <code>TimeZone</code> using <code>createTimeZone</code> along 65 * with a time zone ID. For instance, the time zone ID for the US Pacific 66 * Time zone is "America/Los_Angeles". So, you can get a Pacific Time <code>TimeZone</code> object 67 * with: 68 * \htmlonly<blockquote>\endhtmlonly 69 * <pre> 70 * TimeZone *tz = TimeZone::createTimeZone("America/Los_Angeles"); 71 * </pre> 72 * \htmlonly</blockquote>\endhtmlonly 73 * You can use the <code>createEnumeration</code> method to iterate through 74 * all the supported time zone IDs, or the <code>getCanonicalID</code> method to check 75 * if a time zone ID is supported or not. You can then choose a 76 * supported ID to get a <code>TimeZone</code>. 77 * If the time zone you want is not represented by one of the 78 * supported IDs, then you can create a custom time zone ID with 79 * the following syntax: 80 * 81 * \htmlonly<blockquote>\endhtmlonly 82 * <pre> 83 * GMT[+|-]hh[[:]mm] 84 * </pre> 85 * \htmlonly</blockquote>\endhtmlonly 86 * 87 * For example, you might specify GMT+14:00 as a custom 88 * time zone ID. The <code>TimeZone</code> that is returned 89 * when you specify a custom time zone ID uses the specified 90 * offset from GMT(=UTC) and does not observe daylight saving 91 * time. For example, you might specify GMT+14:00 as a custom 92 * time zone ID to create a TimeZone representing 14 hours ahead 93 * of GMT (with no daylight saving time). In addition, 94 * <code>getCanonicalID</code> can also be used to 95 * normalize a custom time zone ID. 96 * 97 * TimeZone is an abstract class representing a time zone. A TimeZone is needed for 98 * Calendar to produce local time for a particular time zone. A TimeZone comprises 99 * three basic pieces of information: 100 * <ul> 101 * <li>A time zone offset; that, is the number of milliseconds to add or subtract 102 * from a time expressed in terms of GMT to convert it to the same time in that 103 * time zone (without taking daylight savings time into account).</li> 104 * <li>Logic necessary to take daylight savings time into account if daylight savings 105 * time is observed in that time zone (e.g., the days and hours on which daylight 106 * savings time begins and ends).</li> 107 * <li>An ID. This is a text string that uniquely identifies the time zone.</li> 108 * </ul> 109 * 110 * (Only the ID is actually implemented in TimeZone; subclasses of TimeZone may handle 111 * daylight savings time and GMT offset in different ways. Currently we have the following 112 * TimeZone subclasses: RuleBasedTimeZone, SimpleTimeZone, and VTimeZone.) 113 * <P> 114 * The TimeZone class contains a static list containing a TimeZone object for every 115 * combination of GMT offset and daylight-savings time rules currently in use in the 116 * world, each with a unique ID. Each ID consists of a region (usually a continent or 117 * ocean) and a city in that region, separated by a slash, (for example, US Pacific 118 * Time is "America/Los_Angeles.") Because older versions of this class used 119 * three- or four-letter abbreviations instead, there is also a table that maps the older 120 * abbreviations to the newer ones (for example, "PST" maps to "America/Los_Angeles"). 121 * Anywhere the API requires an ID, you can use either form. 122 * <P> 123 * To create a new TimeZone, you call the factory function TimeZone::createTimeZone() 124 * and pass it a time zone ID. You can use the createEnumeration() function to 125 * obtain a list of all the time zone IDs recognized by createTimeZone(). 126 * <P> 127 * You can also use TimeZone::createDefault() to create a TimeZone. This function uses 128 * platform-specific APIs to produce a TimeZone for the time zone corresponding to 129 * the client's computer's physical location. For example, if you're in Japan (assuming 130 * your machine is set up correctly), TimeZone::createDefault() will return a TimeZone 131 * for Japanese Standard Time ("Asia/Tokyo"). 132 */ 133 class U_I18N_API TimeZone : public UObject { 134 public: 135 /** 136 * @stable ICU 2.0 137 */ 138 virtual ~TimeZone(); 139 140 /** 141 * Returns the "unknown" time zone. 142 * It behaves like the GMT/UTC time zone but has the 143 * <code>UCAL_UNKNOWN_ZONE_ID</code> = "Etc/Unknown". 144 * createTimeZone() returns a mutable clone of this time zone if the input ID is not recognized. 145 * 146 * @return the "unknown" time zone. 147 * @see UCAL_UNKNOWN_ZONE_ID 148 * @see createTimeZone 149 * @see getGMT 150 * @stable ICU 49 151 */ 152 static const TimeZone& U_EXPORT2 getUnknown(); 153 154 /** 155 * The GMT (=UTC) time zone has a raw offset of zero and does not use daylight 156 * savings time. This is a commonly used time zone. 157 * 158 * <p>Note: For backward compatibility reason, the ID used by the time 159 * zone returned by this method is "GMT", although the ICU's canonical 160 * ID for the GMT time zone is "Etc/GMT". 161 * 162 * @return the GMT/UTC time zone. 163 * @see getUnknown 164 * @stable ICU 2.0 165 */ 166 static const TimeZone* U_EXPORT2 getGMT(); 167 168 /** 169 * Creates a <code>TimeZone</code> for the given ID. 170 * @param ID the ID for a <code>TimeZone</code>, such as "America/Los_Angeles", 171 * or a custom ID such as "GMT-8:00". 172 * @return the specified <code>TimeZone</code>, or a mutable clone of getUnknown() 173 * if the given ID cannot be understood or if the given ID is "Etc/Unknown". 174 * The return result is guaranteed to be non-nullptr. 175 * If you require that the specific zone asked for be returned, 176 * compare the result with getUnknown() or check the ID of the return result. 177 * @stable ICU 2.0 178 */ 179 static TimeZone* U_EXPORT2 createTimeZone(const UnicodeString& ID); 180 181 /** 182 * Returns an enumeration over system time zone IDs with the given 183 * filter conditions. 184 * @param zoneType The system time zone type. 185 * @param region The ISO 3166 two-letter country code or UN M.49 186 * three-digit area code. When nullptr, no filtering 187 * done by region. 188 * @param rawOffset An offset from GMT in milliseconds, ignoring 189 * the effect of daylight savings time, if any. 190 * When nullptr, no filtering done by zone offset. 191 * @param ec Output param to filled in with a success or 192 * an error. 193 * @return an enumeration object, owned by the caller. 194 * @stable ICU 4.8 195 */ 196 static StringEnumeration* U_EXPORT2 createTimeZoneIDEnumeration( 197 USystemTimeZoneType zoneType, 198 const char* region, 199 const int32_t* rawOffset, 200 UErrorCode& ec); 201 202 #ifndef U_HIDE_DEPRECATED_API 203 /** 204 * Returns an enumeration over all recognized time zone IDs. (i.e., 205 * all strings that createTimeZone() accepts) 206 * 207 * @return an enumeration object, owned by the caller. 208 * @deprecated ICU 70 Use createEnumeration(UErrorCode&) instead. 209 */ 210 static StringEnumeration* U_EXPORT2 createEnumeration(); 211 #endif // U_HIDE_DEPRECATED_API 212 213 /** 214 * Returns an enumeration over all recognized time zone IDs. (i.e., 215 * all strings that createTimeZone() accepts) 216 * 217 * @param status Receives the status. 218 * @return an enumeration object, owned by the caller. 219 * @stable ICU 70 220 */ 221 static StringEnumeration* U_EXPORT2 createEnumeration(UErrorCode& status); 222 223 #ifndef U_HIDE_DEPRECATED_API 224 /** 225 * Returns an enumeration over time zone IDs with a given raw 226 * offset from GMT. There may be several times zones with the 227 * same GMT offset that differ in the way they handle daylight 228 * savings time. For example, the state of Arizona doesn't 229 * observe daylight savings time. If you ask for the time zone 230 * IDs corresponding to GMT-7:00, you'll get back an enumeration 231 * over two time zone IDs: "America/Denver," which corresponds to 232 * Mountain Standard Time in the winter and Mountain Daylight Time 233 * in the summer, and "America/Phoenix", which corresponds to 234 * Mountain Standard Time year-round, even in the summer. 235 * 236 * @param rawOffset an offset from GMT in milliseconds, ignoring 237 * the effect of daylight savings time, if any 238 * @return an enumeration object, owned by the caller 239 * @deprecated ICU 70 Use createEnumerationForRawOffset(int32_t,UErrorCode&) instead. 240 */ 241 static StringEnumeration* U_EXPORT2 createEnumeration(int32_t rawOffset); 242 #endif // U_HIDE_DEPRECATED_API 243 244 /** 245 * Returns an enumeration over time zone IDs with a given raw 246 * offset from GMT. There may be several times zones with the 247 * same GMT offset that differ in the way they handle daylight 248 * savings time. For example, the state of Arizona doesn't 249 * observe daylight savings time. If you ask for the time zone 250 * IDs corresponding to GMT-7:00, you'll get back an enumeration 251 * over two time zone IDs: "America/Denver," which corresponds to 252 * Mountain Standard Time in the winter and Mountain Daylight Time 253 * in the summer, and "America/Phoenix", which corresponds to 254 * Mountain Standard Time year-round, even in the summer. 255 * 256 * @param rawOffset an offset from GMT in milliseconds, ignoring 257 * the effect of daylight savings time, if any 258 * @param status Receives the status. 259 * @return an enumeration object, owned by the caller 260 * @stable ICU 70 261 */ 262 static StringEnumeration* U_EXPORT2 createEnumerationForRawOffset(int32_t rawOffset, UErrorCode& status); 263 264 #ifndef U_HIDE_DEPRECATED_API 265 /** 266 * Returns an enumeration over time zone IDs associated with the 267 * given region. Some zones are affiliated with no region 268 * (e.g., "UTC"); these may also be retrieved, as a group. 269 * 270 * @param region The ISO 3166 two-letter country code, or nullptr to 271 * retrieve zones not affiliated with any region. 272 * @return an enumeration object, owned by the caller 273 * @deprecated ICU 70 Use createEnumerationForRegion(const char*,UErrorCode&) instead. 274 */ 275 static StringEnumeration* U_EXPORT2 createEnumeration(const char* region); 276 #endif // U_HIDE_DEPRECATED_API 277 278 /** 279 * Returns an enumeration over time zone IDs associated with the 280 * given region. Some zones are affiliated with no region 281 * (e.g., "UTC"); these may also be retrieved, as a group. 282 * 283 * @param region The ISO 3166 two-letter country code, or nullptr to 284 * retrieve zones not affiliated with any region. 285 * @param status Receives the status. 286 * @return an enumeration object, owned by the caller 287 * @stable ICU 70 288 */ 289 static StringEnumeration* U_EXPORT2 createEnumerationForRegion(const char* region, UErrorCode& status); 290 291 /** 292 * Returns the number of IDs in the equivalency group that 293 * includes the given ID. An equivalency group contains zones 294 * that have the same GMT offset and rules. 295 * 296 * <p>The returned count includes the given ID; it is always >= 1. 297 * The given ID must be a system time zone. If it is not, returns 298 * zero. 299 * @param id a system time zone ID 300 * @return the number of zones in the equivalency group containing 301 * 'id', or zero if 'id' is not a valid system ID 302 * @see #getEquivalentID 303 * @stable ICU 2.0 304 */ 305 static int32_t U_EXPORT2 countEquivalentIDs(const UnicodeString& id); 306 307 /** 308 * Returns an ID in the equivalency group that 309 * includes the given ID. An equivalency group contains zones 310 * that have the same GMT offset and rules. 311 * 312 * <p>The given index must be in the range 0..n-1, where n is the 313 * value returned by <code>countEquivalentIDs(id)</code>. For 314 * some value of 'index', the returned value will be equal to the 315 * given id. If the given id is not a valid system time zone, or 316 * if 'index' is out of range, then returns an empty string. 317 * @param id a system time zone ID 318 * @param index a value from 0 to n-1, where n is the value 319 * returned by <code>countEquivalentIDs(id)</code> 320 * @return the ID of the index-th zone in the equivalency group 321 * containing 'id', or an empty string if 'id' is not a valid 322 * system ID or 'index' is out of range 323 * @see #countEquivalentIDs 324 * @stable ICU 2.0 325 */ 326 static UnicodeString U_EXPORT2 getEquivalentID(const UnicodeString& id, 327 int32_t index); 328 329 /** 330 * Creates an instance of TimeZone detected from the current host 331 * system configuration. If the host system detection routines fail, 332 * or if they specify a TimeZone or TimeZone offset which is not 333 * recognized, then the special TimeZone "Etc/Unknown" is returned. 334 * 335 * Note that ICU4C does not change the default time zone unless 336 * `TimeZone::adoptDefault(TimeZone*)` or 337 * `TimeZone::setDefault(const TimeZone&)` is explicitly called by a 338 * user. This method does not update the current ICU's default, 339 * and may return a different TimeZone from the one returned by 340 * `TimeZone::createDefault()`. 341 * 342 * <p>This function is not thread safe.</p> 343 * 344 * @return A new instance of TimeZone detected from the current host system 345 * configuration. 346 * @see adoptDefault 347 * @see setDefault 348 * @see createDefault 349 * @see getUnknown 350 * @stable ICU 55 351 */ 352 static TimeZone* U_EXPORT2 detectHostTimeZone(); 353 354 /** 355 * Creates a new copy of the default TimeZone for this host. Unless the default time 356 * zone has already been set using adoptDefault() or setDefault(), the default is 357 * determined by querying the host system configuration. If the host system detection 358 * routines fail, or if they specify a TimeZone or TimeZone offset which is not 359 * recognized, then the special TimeZone "Etc/Unknown" is instantiated and made the 360 * default. 361 * 362 * @return A default TimeZone. Clients are responsible for deleting the time zone 363 * object returned. 364 * @see getUnknown 365 * @stable ICU 2.0 366 */ 367 static TimeZone* U_EXPORT2 createDefault(); 368 369 #ifndef U_HIDE_INTERNAL_API 370 /** 371 * If the locale contains the timezone keyword, creates a copy of that TimeZone. 372 * Otherwise, create the default timezone. 373 * 374 * @param locale a locale which may contains 'timezone' keyword/value. 375 * @return A TimeZone. Clients are responsible for deleting the time zone 376 * object returned. 377 * @internal 378 */ 379 static TimeZone* U_EXPORT2 forLocaleOrDefault(const Locale& locale); 380 #endif /* U_HIDE_INTERNAL_API */ 381 382 /** 383 * Sets the default time zone (i.e., what's returned by createDefault()) to be the 384 * specified time zone. If nullptr is specified for the time zone, the default time 385 * zone is set to the default host time zone. This call adopts the TimeZone object 386 * passed in; the client is no longer responsible for deleting it. 387 * 388 * @param zone A pointer to the new TimeZone object to use as the default. 389 * @stable ICU 2.0 390 */ 391 static void U_EXPORT2 adoptDefault(TimeZone* zone); 392 393 #ifndef U_HIDE_SYSTEM_API 394 /** 395 * Same as adoptDefault(), except that the TimeZone object passed in is NOT adopted; 396 * the caller remains responsible for deleting it. 397 * 398 * @param zone The given timezone. 399 * @system 400 * @stable ICU 2.0 401 */ 402 static void U_EXPORT2 setDefault(const TimeZone& zone); 403 #endif /* U_HIDE_SYSTEM_API */ 404 405 /** 406 * Returns the timezone data version currently used by ICU. 407 * @param status Output param to filled in with a success or an error. 408 * @return the version string, such as "2007f" 409 * @stable ICU 3.8 410 */ 411 static const char* U_EXPORT2 getTZDataVersion(UErrorCode& status); 412 413 /** 414 * Returns the canonical system timezone ID or the normalized 415 * custom time zone ID for the given time zone ID. 416 * @param id The input time zone ID to be canonicalized. 417 * @param canonicalID Receives the canonical system time zone ID 418 * or the custom time zone ID in normalized format. 419 * @param status Receives the status. When the given time zone ID 420 * is neither a known system time zone ID nor a 421 * valid custom time zone ID, U_ILLEGAL_ARGUMENT_ERROR 422 * is set. 423 * @return A reference to the result. 424 * @stable ICU 4.0 425 */ 426 static UnicodeString& U_EXPORT2 getCanonicalID(const UnicodeString& id, 427 UnicodeString& canonicalID, UErrorCode& status); 428 429 /** 430 * Returns the canonical system time zone ID or the normalized 431 * custom time zone ID for the given time zone ID. 432 * @param id The input time zone ID to be canonicalized. 433 * @param canonicalID Receives the canonical system time zone ID 434 * or the custom time zone ID in normalized format. 435 * @param isSystemID Receives if the given ID is a known system 436 * time zone ID. 437 * @param status Receives the status. When the given time zone ID 438 * is neither a known system time zone ID nor a 439 * valid custom time zone ID, U_ILLEGAL_ARGUMENT_ERROR 440 * is set. 441 * @return A reference to the result. 442 * @stable ICU 4.0 443 */ 444 static UnicodeString& U_EXPORT2 getCanonicalID(const UnicodeString& id, 445 UnicodeString& canonicalID, UBool& isSystemID, UErrorCode& status); 446 447 448 /** 449 * Returns the preferred time zone ID in the IANA time zone database for the given time zone ID. 450 * There are two types of preferred IDs. The first type is the one defined in zone.tab file, 451 * such as "America/Los_Angeles". The second types is the one defined for zones not associated 452 * with a specific region, but not defined with "Link" syntax such as "Etc/GMT+10". 453 * 454 * <p>Note: For most of valid time zone IDs, this method returns an ID same as getCanonicalID(). 455 * getCanonicalID() is based on canonical time zone IDs defined in Unicode CLDR. 456 * These canonical time zone IDs in CLDR were based on very old version of the time zone database. 457 * In the IANA time zone database, some IDs were updated since then. This API returns a newer 458 * time zone ID. For example, CLDR defines "Asia/Calcutta" as the canonical time zone ID. This 459 * method returns "Asia/Kolkata" instead. 460 * <p> "Etc/Unknown" is a special time zone ID defined by CLDR. There are no corresponding zones 461 * in the IANA time zone database. Therefore, this API returns U_ILLEGAL_ARGUMENT_ERROR when the 462 * input ID is "Etc/Unknown". 463 * 464 * @param id The input time zone ID. 465 * @param ianaID Receives the preferred time zone ID in the IANA time zone database. When 466 * the given time zone ID is not a known time zone ID, this method sets an 467 * invalid (bogus) string. 468 * @param status Receives the status. When the given time zone ID is not a known time zone 469 * ID, U_ILLEGAL_ARGUMENT_ERROR is set. 470 * @return A reference to the result. 471 * @stable ICU 74 472 */ 473 static UnicodeString& U_EXPORT2 getIanaID(const UnicodeString&id, UnicodeString& ianaID, 474 UErrorCode& status); 475 476 /** 477 * Converts a system time zone ID to an equivalent Windows time zone ID. For example, 478 * Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles". 479 * 480 * <p>There are system time zones that cannot be mapped to Windows zones. When the input 481 * system time zone ID is unknown or unmappable to a Windows time zone, then the result will be 482 * empty, but the operation itself remains successful (no error status set on return). 483 * 484 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html"> 485 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes, 486 * please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data"> 487 * Updating the Time Zone Data</a>. 488 * 489 * @param id A system time zone ID. 490 * @param winid Receives a Windows time zone ID. When the input system time zone ID is unknown 491 * or unmappable to a Windows time zone ID, then an empty string is set on return. 492 * @param status Receives the status. 493 * @return A reference to the result (<code>winid</code>). 494 * @see getIDForWindowsID 495 * 496 * @stable ICU 52 497 */ 498 static UnicodeString& U_EXPORT2 getWindowsID(const UnicodeString& id, 499 UnicodeString& winid, UErrorCode& status); 500 501 /** 502 * Converts a Windows time zone ID to an equivalent system time zone ID 503 * for a region. For example, system time zone ID "America/Los_Angeles" is returned 504 * for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>), 505 * "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and 506 * region "CA". 507 * 508 * <p>Not all Windows time zones can be mapped to system time zones. When the input 509 * Windows time zone ID is unknown or unmappable to a system time zone, then the result 510 * will be empty, but the operation itself remains successful (no error status set on return). 511 * 512 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html"> 513 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes, 514 * please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data"> 515 * Updating the Time Zone Data</a>. 516 * 517 * @param winid A Windows time zone ID. 518 * @param region A NUL-terminated region code, or <code>nullptr</code> if no regional preference. 519 * @param id Receives a system time zone ID. When the input Windows time zone ID is unknown 520 * or unmappable to a system time zone ID, then an empty string is set on return. 521 * @param status Receives the status. 522 * @return A reference to the result (<code>id</code>). 523 * @see getWindowsID 524 * 525 * @stable ICU 52 526 */ 527 static UnicodeString& U_EXPORT2 getIDForWindowsID(const UnicodeString& winid, const char* region, 528 UnicodeString& id, UErrorCode& status); 529 530 /** 531 * Returns true if the two TimeZones are equal. (The TimeZone version only compares 532 * IDs, but subclasses are expected to also compare the fields they add.) 533 * 534 * @param that The TimeZone object to be compared with. 535 * @return true if the given TimeZone is equal to this TimeZone; false 536 * otherwise. 537 * @stable ICU 2.0 538 */ 539 virtual bool operator==(const TimeZone& that) const; 540 541 /** 542 * Returns true if the two TimeZones are NOT equal; that is, if operator==() returns 543 * false. 544 * 545 * @param that The TimeZone object to be compared with. 546 * @return true if the given TimeZone is not equal to this TimeZone; false 547 * otherwise. 548 * @stable ICU 2.0 549 */ 550 bool operator!=(const TimeZone& that) const {return !operator==(that);} 551 552 /** 553 * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add 554 * to GMT to get local time in this time zone, taking daylight savings time into 555 * account) as of a particular reference date. The reference date is used to determine 556 * whether daylight savings time is in effect and needs to be figured into the offset 557 * that is returned (in other words, what is the adjusted GMT offset in this time zone 558 * at this particular date and time?). For the time zones produced by createTimeZone(), 559 * the reference data is specified according to the Gregorian calendar, and the date 560 * and time fields are local standard time. 561 * 562 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload, 563 * which returns both the raw and the DST offset for a given time. This method 564 * is retained only for backward compatibility. 565 * 566 * @param era The reference date's era 567 * @param year The reference date's year 568 * @param month The reference date's month (0-based; 0 is January) 569 * @param day The reference date's day-in-month (1-based) 570 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) 571 * @param millis The reference date's milliseconds in day, local standard time 572 * @param status Output param to filled in with a success or an error. 573 * @return The offset in milliseconds to add to GMT to get local time. 574 * @stable ICU 2.0 575 */ 576 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, 577 uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const = 0; 578 579 /** 580 * Gets the time zone offset, for current date, modified in case of 581 * daylight savings. This is the offset to add *to* UTC to get local time. 582 * 583 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload, 584 * which returns both the raw and the DST offset for a given time. This method 585 * is retained only for backward compatibility. 586 * 587 * @param era the era of the given date. 588 * @param year the year in the given date. 589 * @param month the month in the given date. 590 * Month is 0-based. e.g., 0 for January. 591 * @param day the day-in-month of the given date. 592 * @param dayOfWeek the day-of-week of the given date. 593 * @param milliseconds the millis in day in <em>standard</em> local time. 594 * @param monthLength the length of the given month in days. 595 * @param status Output param to filled in with a success or an error. 596 * @return the offset to add *to* GMT to get local time. 597 * @stable ICU 2.0 598 */ 599 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, 600 uint8_t dayOfWeek, int32_t milliseconds, 601 int32_t monthLength, UErrorCode& status) const = 0; 602 603 /** 604 * Returns the time zone raw and GMT offset for the given moment 605 * in time. Upon return, local-millis = GMT-millis + rawOffset + 606 * dstOffset. All computations are performed in the proleptic 607 * Gregorian calendar. The default implementation in the TimeZone 608 * class delegates to the 8-argument getOffset(). 609 * 610 * @param date moment in time for which to return offsets, in 611 * units of milliseconds from January 1, 1970 0:00 GMT, either GMT 612 * time or local wall time, depending on `local'. 613 * @param local if true, `date' is local wall time; otherwise it 614 * is in GMT time. 615 * @param rawOffset output parameter to receive the raw offset, that 616 * is, the offset not including DST adjustments 617 * @param dstOffset output parameter to receive the DST offset, 618 * that is, the offset to be added to `rawOffset' to obtain the 619 * total offset between local and GMT time. If DST is not in 620 * effect, this value is zero; otherwise it is a positive value, 621 * typically one hour. 622 * @param ec input-output error code 623 * 624 * @stable ICU 2.8 625 */ 626 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset, 627 int32_t& dstOffset, UErrorCode& ec) const; 628 629 /** 630 * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add 631 * to GMT to get local time, before taking daylight savings time into account). 632 * 633 * @param offsetMillis The new raw GMT offset for this time zone. 634 * @stable ICU 2.0 635 */ 636 virtual void setRawOffset(int32_t offsetMillis) = 0; 637 638 /** 639 * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add 640 * to GMT to get local time, before taking daylight savings time into account). 641 * 642 * @return The TimeZone's raw GMT offset. 643 * @stable ICU 2.0 644 */ 645 virtual int32_t getRawOffset() const = 0; 646 647 /** 648 * Fills in "ID" with the TimeZone's ID. 649 * 650 * @param ID Receives this TimeZone's ID. 651 * @return A reference to 'ID' 652 * @stable ICU 2.0 653 */ 654 UnicodeString& getID(UnicodeString& ID) const; 655 656 /** 657 * Sets the TimeZone's ID to the specified value. This doesn't affect any other 658 * fields (for example, if you say< 659 * blockquote><pre> 660 * . TimeZone* foo = TimeZone::createTimeZone("America/New_York"); 661 * . foo.setID("America/Los_Angeles"); 662 * </pre>\htmlonly</blockquote>\endhtmlonly 663 * the time zone's GMT offset and daylight-savings rules don't change to those for 664 * Los Angeles. They're still those for New York. Only the ID has changed.) 665 * 666 * @param ID The new time zone ID. 667 * @stable ICU 2.0 668 */ 669 void setID(const UnicodeString& ID); 670 671 /** 672 * Enum for use with getDisplayName 673 * @stable ICU 2.4 674 */ 675 enum EDisplayType { 676 /** 677 * Selector for short display name 678 * @stable ICU 2.4 679 */ 680 SHORT = 1, 681 /** 682 * Selector for long display name 683 * @stable ICU 2.4 684 */ 685 LONG, 686 /** 687 * Selector for short generic display name 688 * @stable ICU 4.4 689 */ 690 SHORT_GENERIC, 691 /** 692 * Selector for long generic display name 693 * @stable ICU 4.4 694 */ 695 LONG_GENERIC, 696 /** 697 * Selector for short display name derived 698 * from time zone offset 699 * @stable ICU 4.4 700 */ 701 SHORT_GMT, 702 /** 703 * Selector for long display name derived 704 * from time zone offset 705 * @stable ICU 4.4 706 */ 707 LONG_GMT, 708 /** 709 * Selector for short display name derived 710 * from the time zone's fallback name 711 * @stable ICU 4.4 712 */ 713 SHORT_COMMONLY_USED, 714 /** 715 * Selector for long display name derived 716 * from the time zone's fallback name 717 * @stable ICU 4.4 718 */ 719 GENERIC_LOCATION 720 }; 721 722 /** 723 * Returns a name of this time zone suitable for presentation to the user 724 * in the default locale. 725 * This method returns the long name, not including daylight savings. 726 * If the display name is not available for the locale, 727 * then this method returns a string in the localized GMT offset format 728 * such as <code>GMT[+-]HH:mm</code>. 729 * @param result the human-readable name of this time zone in the default locale. 730 * @return A reference to 'result'. 731 * @stable ICU 2.0 732 */ 733 UnicodeString& getDisplayName(UnicodeString& result) const; 734 735 /** 736 * Returns a name of this time zone suitable for presentation to the user 737 * in the specified locale. 738 * This method returns the long name, not including daylight savings. 739 * If the display name is not available for the locale, 740 * then this method returns a string in the localized GMT offset format 741 * such as <code>GMT[+-]HH:mm</code>. 742 * @param locale the locale in which to supply the display name. 743 * @param result the human-readable name of this time zone in the given locale 744 * or in the default locale if the given locale is not recognized. 745 * @return A reference to 'result'. 746 * @stable ICU 2.0 747 */ 748 UnicodeString& getDisplayName(const Locale& locale, UnicodeString& result) const; 749 750 /** 751 * Returns a name of this time zone suitable for presentation to the user 752 * in the default locale. 753 * If the display name is not available for the locale, 754 * then this method returns a string in the localized GMT offset format 755 * such as <code>GMT[+-]HH:mm</code>. 756 * @param inDaylight if true, return the daylight savings name. 757 * @param style 758 * @param result the human-readable name of this time zone in the default locale. 759 * @return A reference to 'result'. 760 * @stable ICU 2.0 761 */ 762 UnicodeString& getDisplayName(UBool inDaylight, EDisplayType style, UnicodeString& result) const; 763 764 /** 765 * Returns a name of this time zone suitable for presentation to the user 766 * in the specified locale. 767 * If the display name is not available for the locale, 768 * then this method returns a string in the localized GMT offset format 769 * such as <code>GMT[+-]HH:mm</code>. 770 * @param inDaylight if true, return the daylight savings name. 771 * @param style 772 * @param locale the locale in which to supply the display name. 773 * @param result the human-readable name of this time zone in the given locale 774 * or in the default locale if the given locale is not recognized. 775 * @return A reference to 'result'. 776 * @stable ICU 2.0 777 */ 778 UnicodeString& getDisplayName(UBool inDaylight, EDisplayType style, const Locale& locale, UnicodeString& result) const; 779 780 /** 781 * Queries if this time zone uses daylight savings time. 782 * @return true if this time zone uses daylight savings time, 783 * false, otherwise. 784 * <p><strong>Note:</strong>The default implementation of 785 * ICU TimeZone uses the tz database, which supports historic 786 * rule changes, for system time zones. With the implementation, 787 * there are time zones that used daylight savings time in the 788 * past, but no longer used currently. For example, Asia/Tokyo has 789 * never used daylight savings time since 1951. Most clients would 790 * expect that this method to return <code>false</code> for such case. 791 * The default implementation of this method returns <code>true</code> 792 * when the time zone uses daylight savings time in the current 793 * (Gregorian) calendar year. 794 * <p>In Java 7, <code>observesDaylightTime()</code> was added in 795 * addition to <code>useDaylightTime()</code>. In Java, <code>useDaylightTime()</code> 796 * only checks if daylight saving time is observed by the last known 797 * rule. This specification might not be what most users would expect 798 * if daylight saving time is currently observed, but not scheduled 799 * in future. In this case, Java's <code>userDaylightTime()</code> returns 800 * <code>false</code>. To resolve the issue, Java 7 added <code>observesDaylightTime()</code>, 801 * which takes the current rule into account. The method <code>observesDaylightTime()</code> 802 * was added in ICU4J for supporting API signature compatibility with JDK. 803 * In general, ICU4C also provides JDK compatible methods, but the current 804 * implementation <code>userDaylightTime()</code> serves the purpose 805 * (takes the current rule into account), <code>observesDaylightTime()</code> 806 * is not added in ICU4C. In addition to <code>useDaylightTime()</code>, ICU4C 807 * <code>BasicTimeZone</code> class (Note that <code>TimeZone::createTimeZone(const UnicodeString &ID)</code> 808 * always returns a <code>BasicTimeZone</code>) provides a series of methods allowing 809 * historic and future time zone rule iteration, so you can check if daylight saving 810 * time is observed or not within a given period. 811 * 812 * @stable ICU 2.0 813 */ 814 virtual UBool useDaylightTime() const = 0; 815 816 #ifndef U_FORCE_HIDE_DEPRECATED_API 817 /** 818 * Queries if the given date is in daylight savings time in 819 * this time zone. 820 * This method is wasteful since it creates a new GregorianCalendar and 821 * deletes it each time it is called. This is a deprecated method 822 * and provided only for Java compatibility. 823 * 824 * @param date the given UDate. 825 * @param status Output param filled in with success/error code. 826 * @return true if the given date is in daylight savings time, 827 * false, otherwise. 828 * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead. 829 */ 830 virtual UBool inDaylightTime(UDate date, UErrorCode& status) const = 0; 831 #endif // U_FORCE_HIDE_DEPRECATED_API 832 833 /** 834 * Returns true if this zone has the same rule and offset as another zone. 835 * That is, if this zone differs only in ID, if at all. 836 * @param other the <code>TimeZone</code> object to be compared with 837 * @return true if the given zone is the same as this one, 838 * with the possible exception of the ID 839 * @stable ICU 2.0 840 */ 841 virtual UBool hasSameRules(const TimeZone& other) const; 842 843 /** 844 * Clones TimeZone objects polymorphically. Clients are responsible for deleting 845 * the TimeZone object cloned. 846 * 847 * @return A new copy of this TimeZone object. 848 * @stable ICU 2.0 849 */ 850 virtual TimeZone* clone() const = 0; 851 852 /** 853 * Return the class ID for this class. This is useful only for 854 * comparing to a return value from getDynamicClassID(). 855 * @return The class ID for all objects of this class. 856 * @stable ICU 2.0 857 */ 858 static UClassID U_EXPORT2 getStaticClassID(); 859 860 /** 861 * Returns a unique class ID POLYMORPHICALLY. This method is to 862 * implement a simple version of RTTI, since not all C++ compilers support genuine 863 * RTTI. Polymorphic operator==() and clone() methods call this method. 864 * <P> 865 * Concrete subclasses of TimeZone must use the UOBJECT_DEFINE_RTTI_IMPLEMENTATION 866 * macro from uobject.h in their implementation to provide correct RTTI information. 867 * @return The class ID for this object. All objects of a given class have the 868 * same class ID. Objects of other classes have different class IDs. 869 * @stable ICU 2.0 870 */ 871 virtual UClassID getDynamicClassID() const override = 0; 872 873 /** 874 * Returns the amount of time to be added to local standard time 875 * to get local wall clock time. 876 * <p> 877 * The default implementation always returns 3600000 milliseconds 878 * (i.e., one hour) if this time zone observes Daylight Saving 879 * Time. Otherwise, 0 (zero) is returned. 880 * <p> 881 * If an underlying TimeZone implementation subclass supports 882 * historical Daylight Saving Time changes, this method returns 883 * the known latest daylight saving value. 884 * 885 * @return the amount of saving time in milliseconds 886 * @stable ICU 3.6 887 */ 888 virtual int32_t getDSTSavings() const; 889 890 /** 891 * Gets the region code associated with the given 892 * system time zone ID. The region code is either ISO 3166 893 * 2-letter country code or UN M.49 3-digit area code. 894 * When the time zone is not associated with a specific location, 895 * for example - "Etc/UTC", "EST5EDT", then this method returns 896 * "001" (UN M.49 area code for World). 897 * 898 * @param id The system time zone ID. 899 * @param region Output buffer for receiving the region code. 900 * @param capacity The size of the output buffer. 901 * @param status Receives the status. When the given time zone ID 902 * is not a known system time zone ID, 903 * U_ILLEGAL_ARGUMENT_ERROR is set. 904 * @return The length of the output region code. 905 * @stable ICU 4.8 906 */ 907 static int32_t U_EXPORT2 getRegion(const UnicodeString& id, 908 char *region, int32_t capacity, UErrorCode& status); 909 910 protected: 911 912 /** 913 * Default constructor. ID is initialized to the empty string. 914 * @stable ICU 2.0 915 */ 916 TimeZone(); 917 918 /** 919 * Construct a TimeZone with a given ID. 920 * @param id a system time zone ID 921 * @stable ICU 2.0 922 */ 923 TimeZone(const UnicodeString &id); 924 925 /** 926 * Copy constructor. 927 * @param source the object to be copied. 928 * @stable ICU 2.0 929 */ 930 TimeZone(const TimeZone& source); 931 932 /** 933 * Default assignment operator. 934 * @param right the object to be copied. 935 * @stable ICU 2.0 936 */ 937 TimeZone& operator=(const TimeZone& right); 938 939 #ifndef U_HIDE_INTERNAL_API 940 /** 941 * Utility function. For internally loading rule data. 942 * @param top Top resource bundle for tz data 943 * @param ruleid ID of rule to load 944 * @param oldbundle Old bundle to reuse or nullptr 945 * @param status Status parameter 946 * @return either a new bundle or *oldbundle 947 * @internal 948 */ 949 static UResourceBundle* loadRule(const UResourceBundle* top, const UnicodeString& ruleid, UResourceBundle* oldbundle, UErrorCode&status); 950 #endif /* U_HIDE_INTERNAL_API */ 951 952 private: 953 friend class ZoneMeta; 954 955 956 static TimeZone* createCustomTimeZone(const UnicodeString&); // Creates a time zone based on the string. 957 958 /** 959 * Finds the given ID in the Olson tzdata. If the given ID is found in the tzdata, 960 * returns the pointer to the ID resource. This method is exposed through ZoneMeta class 961 * for ICU internal implementation and useful for building hashtable using a time zone 962 * ID as a key. 963 * @param id zone id string 964 * @return the pointer of the ID resource, or nullptr. 965 */ 966 static const char16_t* findID(const UnicodeString& id); 967 968 /** 969 * Resolve a link in Olson tzdata. When the given id is known and it's not a link, 970 * the id itself is returned. When the given id is known and it is a link, then 971 * dereferenced zone id is returned. When the given id is unknown, then it returns 972 * nullptr. 973 * @param id zone id string 974 * @return the dereferenced zone or nullptr 975 */ 976 static const char16_t* dereferOlsonLink(const UnicodeString& id); 977 978 /** 979 * Returns the region code associated with the given zone, 980 * or nullptr if the zone is not known. 981 * @param id zone id string 982 * @return the region associated with the given zone 983 */ 984 static const char16_t* getRegion(const UnicodeString& id); 985 986 public: 987 #ifndef U_HIDE_INTERNAL_API 988 /** 989 * Returns the region code associated with the given zone, 990 * or nullptr if the zone is not known. 991 * @param id zone id string 992 * @param status Status parameter 993 * @return the region associated with the given zone 994 * @internal 995 */ 996 static const char16_t* getRegion(const UnicodeString& id, UErrorCode& status); 997 #endif /* U_HIDE_INTERNAL_API */ 998 999 private: 1000 /** 1001 * Parses the given custom time zone identifier 1002 * @param id id A string of the form GMT[+-]hh:mm, GMT[+-]hhmm, or 1003 * GMT[+-]hh. 1004 * @param sign Receives parsed sign, 1 for positive, -1 for negative. 1005 * @param hour Receives parsed hour field 1006 * @param minute Receives parsed minute field 1007 * @param second Receives parsed second field 1008 * @return Returns true when the given custom id is valid. 1009 */ 1010 static UBool parseCustomID(const UnicodeString& id, int32_t& sign, int32_t& hour, 1011 int32_t& minute, int32_t& second); 1012 1013 /** 1014 * Parse a custom time zone identifier and return the normalized 1015 * custom time zone identifier for the given custom id string. 1016 * @param id a string of the form GMT[+-]hh:mm, GMT[+-]hhmm, or 1017 * GMT[+-]hh. 1018 * @param normalized Receives the normalized custom ID 1019 * @param status Receives the status. When the input ID string is invalid, 1020 * U_ILLEGAL_ARGUMENT_ERROR is set. 1021 * @return The normalized custom id string. 1022 */ 1023 static UnicodeString& getCustomID(const UnicodeString& id, UnicodeString& normalized, 1024 UErrorCode& status); 1025 1026 /** 1027 * Returns the normalized custom time zone ID for the given offset fields. 1028 * @param hour offset hours 1029 * @param min offset minutes 1030 * @param sec offset seconds 1031 * @param negative sign of the offset, true for negative offset. 1032 * @param id Receives the format result (normalized custom ID) 1033 * @return The reference to id 1034 */ 1035 static UnicodeString& formatCustomID(int32_t hour, int32_t min, int32_t sec, 1036 UBool negative, UnicodeString& id); 1037 1038 UnicodeString fID; // this time zone's ID 1039 1040 friend class TZEnumeration; 1041 }; 1042 1043 1044 // ------------------------------------- 1045 1046 inline UnicodeString& 1047 TimeZone::getID(UnicodeString& ID) const 1048 { 1049 ID = fID; 1050 return ID; 1051 } 1052 1053 // ------------------------------------- 1054 1055 inline void 1056 TimeZone::setID(const UnicodeString& ID) 1057 { 1058 fID = ID; 1059 } 1060 U_NAMESPACE_END 1061 1062 #endif /* #if !UCONFIG_NO_FORMATTING */ 1063 1064 #endif /* U_SHOW_CPLUSPLUS_API */ 1065 1066 #endif //_TIMEZONE 1067 //eof