Where Online Learning is simpler!
The C and C++ Include Header Files
/usr/include/unicode/timezone.h
$ cat -n /usr/include/unicode/timezone.h 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(void); 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 const 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(void); 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 #ifndef U_HIDE_DRAFT_API 449 /** 450 * Returns the preferred time zone ID in the IANA time zone database for the given time zone ID. 451 * There are two types of preferred IDs. The first type is the one defined in zone.tab file, 452 * such as "America/Los_Angeles". The second types is the one defined for zones not associated 453 * with a specific region, but not defined with "Link" syntax such as "Etc/GMT+10". 454 * 455 * <p>Note: For most of valid time zone IDs, this method returns an ID same as getCanonicalID(). 456 * getCanonicalID() is based on canonical time zone IDs defined in Unicode CLDR. 457 * These canonical time zone IDs in CLDR were based on very old version of the time zone database. 458 * In the IANA time zone database, some IDs were updated since then. This API returns a newer 459 * time zone ID. For example, CLDR defines "Asia/Calcutta" as the canonical time zone ID. This 460 * method returns "Asia/Kolkata" instead. 461 * <p> "Etc/Unknown" is a special time zone ID defined by CLDR. There are no corresponding zones 462 * in the IANA time zone database. Therefore, this API returns U_ILLEGAL_ARGUMENT_ERROR when the 463 * input ID is "Etc/Unknown". 464 * 465 * @param id The input time zone ID. 466 * @param ianaID Receives the preferred time zone ID in the IANA time zone database. When 467 * the given time zone ID is not a known time zone ID, this method sets an 468 * invalid (bogus) string. 469 * @param status Receives the status. When the given time zone ID is not a known time zone 470 * ID, U_ILLEGAL_ARGUMENT_ERROR is set. 471 * @return A reference to the result. 472 * @draft ICU 74 473 */ 474 static UnicodeString& U_EXPORT2 getIanaID(const UnicodeString&id, UnicodeString& ianaID, 475 UErrorCode& status); 476 #endif // U_HIDE_DRAFT_API 477 478 /** 479 * Converts a system time zone ID to an equivalent Windows time zone ID. For example, 480 * Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles". 481 * 482 * <p>There are system time zones that cannot be mapped to Windows zones. When the input 483 * system time zone ID is unknown or unmappable to a Windows time zone, then the result will be 484 * empty, but the operation itself remains successful (no error status set on return). 485 * 486 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html"> 487 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes, 488 * please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data"> 489 * Updating the Time Zone Data</a>. 490 * 491 * @param id A system time zone ID. 492 * @param winid Receives a Windows time zone ID. When the input system time zone ID is unknown 493 * or unmappable to a Windows time zone ID, then an empty string is set on return. 494 * @param status Receives the status. 495 * @return A reference to the result (<code>winid</code>). 496 * @see getIDForWindowsID 497 * 498 * @stable ICU 52 499 */ 500 static UnicodeString& U_EXPORT2 getWindowsID(const UnicodeString& id, 501 UnicodeString& winid, UErrorCode& status); 502 503 /** 504 * Converts a Windows time zone ID to an equivalent system time zone ID 505 * for a region. For example, system time zone ID "America/Los_Angeles" is returned 506 * for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>), 507 * "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and 508 * region "CA". 509 * 510 * <p>Not all Windows time zones can be mapped to system time zones. When the input 511 * Windows time zone ID is unknown or unmappable to a system time zone, then the result 512 * will be empty, but the operation itself remains successful (no error status set on return). 513 * 514 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html"> 515 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes, 516 * please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data"> 517 * Updating the Time Zone Data</a>. 518 * 519 * @param winid A Windows time zone ID. 520 * @param region A NUL-terminated region code, or <code>nullptr</code> if no regional preference. 521 * @param id Receives a system time zone ID. When the input Windows time zone ID is unknown 522 * or unmappable to a system time zone ID, then an empty string is set on return. 523 * @param status Receives the status. 524 * @return A reference to the result (<code>id</code>). 525 * @see getWindowsID 526 * 527 * @stable ICU 52 528 */ 529 static UnicodeString& U_EXPORT2 getIDForWindowsID(const UnicodeString& winid, const char* region, 530 UnicodeString& id, UErrorCode& status); 531 532 /** 533 * Returns true if the two TimeZones are equal. (The TimeZone version only compares 534 * IDs, but subclasses are expected to also compare the fields they add.) 535 * 536 * @param that The TimeZone object to be compared with. 537 * @return true if the given TimeZone is equal to this TimeZone; false 538 * otherwise. 539 * @stable ICU 2.0 540 */ 541 virtual bool operator==(const TimeZone& that) const; 542 543 /** 544 * Returns true if the two TimeZones are NOT equal; that is, if operator==() returns 545 * false. 546 * 547 * @param that The TimeZone object to be compared with. 548 * @return true if the given TimeZone is not equal to this TimeZone; false 549 * otherwise. 550 * @stable ICU 2.0 551 */ 552 bool operator!=(const TimeZone& that) const {return !operator==(that);} 553 554 /** 555 * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add 556 * to GMT to get local time in this time zone, taking daylight savings time into 557 * account) as of a particular reference date. The reference date is used to determine 558 * whether daylight savings time is in effect and needs to be figured into the offset 559 * that is returned (in other words, what is the adjusted GMT offset in this time zone 560 * at this particular date and time?). For the time zones produced by createTimeZone(), 561 * the reference data is specified according to the Gregorian calendar, and the date 562 * and time fields are local standard time. 563 * 564 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload, 565 * which returns both the raw and the DST offset for a given time. This method 566 * is retained only for backward compatibility. 567 * 568 * @param era The reference date's era 569 * @param year The reference date's year 570 * @param month The reference date's month (0-based; 0 is January) 571 * @param day The reference date's day-in-month (1-based) 572 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) 573 * @param millis The reference date's milliseconds in day, local standard time 574 * @param status Output param to filled in with a success or an error. 575 * @return The offset in milliseconds to add to GMT to get local time. 576 * @stable ICU 2.0 577 */ 578 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, 579 uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const = 0; 580 581 /** 582 * Gets the time zone offset, for current date, modified in case of 583 * daylight savings. This is the offset to add *to* UTC to get local time. 584 * 585 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload, 586 * which returns both the raw and the DST offset for a given time. This method 587 * is retained only for backward compatibility. 588 * 589 * @param era the era of the given date. 590 * @param year the year in the given date. 591 * @param month the month in the given date. 592 * Month is 0-based. e.g., 0 for January. 593 * @param day the day-in-month of the given date. 594 * @param dayOfWeek the day-of-week of the given date. 595 * @param milliseconds the millis in day in <em>standard</em> local time. 596 * @param monthLength the length of the given month in days. 597 * @param status Output param to filled in with a success or an error. 598 * @return the offset to add *to* GMT to get local time. 599 * @stable ICU 2.0 600 */ 601 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, 602 uint8_t dayOfWeek, int32_t milliseconds, 603 int32_t monthLength, UErrorCode& status) const = 0; 604 605 /** 606 * Returns the time zone raw and GMT offset for the given moment 607 * in time. Upon return, local-millis = GMT-millis + rawOffset + 608 * dstOffset. All computations are performed in the proleptic 609 * Gregorian calendar. The default implementation in the TimeZone 610 * class delegates to the 8-argument getOffset(). 611 * 612 * @param date moment in time for which to return offsets, in 613 * units of milliseconds from January 1, 1970 0:00 GMT, either GMT 614 * time or local wall time, depending on `local'. 615 * @param local if true, `date' is local wall time; otherwise it 616 * is in GMT time. 617 * @param rawOffset output parameter to receive the raw offset, that 618 * is, the offset not including DST adjustments 619 * @param dstOffset output parameter to receive the DST offset, 620 * that is, the offset to be added to `rawOffset' to obtain the 621 * total offset between local and GMT time. If DST is not in 622 * effect, this value is zero; otherwise it is a positive value, 623 * typically one hour. 624 * @param ec input-output error code 625 * 626 * @stable ICU 2.8 627 */ 628 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset, 629 int32_t& dstOffset, UErrorCode& ec) const; 630 631 /** 632 * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add 633 * to GMT to get local time, before taking daylight savings time into account). 634 * 635 * @param offsetMillis The new raw GMT offset for this time zone. 636 * @stable ICU 2.0 637 */ 638 virtual void setRawOffset(int32_t offsetMillis) = 0; 639 640 /** 641 * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add 642 * to GMT to get local time, before taking daylight savings time into account). 643 * 644 * @return The TimeZone's raw GMT offset. 645 * @stable ICU 2.0 646 */ 647 virtual int32_t getRawOffset(void) const = 0; 648 649 /** 650 * Fills in "ID" with the TimeZone's ID. 651 * 652 * @param ID Receives this TimeZone's ID. 653 * @return A reference to 'ID' 654 * @stable ICU 2.0 655 */ 656 UnicodeString& getID(UnicodeString& ID) const; 657 658 /** 659 * Sets the TimeZone's ID to the specified value. This doesn't affect any other 660 * fields (for example, if you say< 661 * blockquote><pre> 662 * . TimeZone* foo = TimeZone::createTimeZone("America/New_York"); 663 * . foo.setID("America/Los_Angeles"); 664 * </pre>\htmlonly</blockquote>\endhtmlonly 665 * the time zone's GMT offset and daylight-savings rules don't change to those for 666 * Los Angeles. They're still those for New York. Only the ID has changed.) 667 * 668 * @param ID The new time zone ID. 669 * @stable ICU 2.0 670 */ 671 void setID(const UnicodeString& ID); 672 673 /** 674 * Enum for use with getDisplayName 675 * @stable ICU 2.4 676 */ 677 enum EDisplayType { 678 /** 679 * Selector for short display name 680 * @stable ICU 2.4 681 */ 682 SHORT = 1, 683 /** 684 * Selector for long display name 685 * @stable ICU 2.4 686 */ 687 LONG, 688 /** 689 * Selector for short generic display name 690 * @stable ICU 4.4 691 */ 692 SHORT_GENERIC, 693 /** 694 * Selector for long generic display name 695 * @stable ICU 4.4 696 */ 697 LONG_GENERIC, 698 /** 699 * Selector for short display name derived 700 * from time zone offset 701 * @stable ICU 4.4 702 */ 703 SHORT_GMT, 704 /** 705 * Selector for long display name derived 706 * from time zone offset 707 * @stable ICU 4.4 708 */ 709 LONG_GMT, 710 /** 711 * Selector for short display name derived 712 * from the time zone's fallback name 713 * @stable ICU 4.4 714 */ 715 SHORT_COMMONLY_USED, 716 /** 717 * Selector for long display name derived 718 * from the time zone's fallback name 719 * @stable ICU 4.4 720 */ 721 GENERIC_LOCATION 722 }; 723 724 /** 725 * Returns a name of this time zone suitable for presentation to the user 726 * in the default locale. 727 * This method returns the long name, not including daylight savings. 728 * If the display name is not available for the locale, 729 * then this method returns a string in the localized GMT offset format 730 * such as <code>GMT[+-]HH:mm</code>. 731 * @param result the human-readable name of this time zone in the default locale. 732 * @return A reference to 'result'. 733 * @stable ICU 2.0 734 */ 735 UnicodeString& getDisplayName(UnicodeString& result) const; 736 737 /** 738 * Returns a name of this time zone suitable for presentation to the user 739 * in the specified locale. 740 * This method returns the long name, not including daylight savings. 741 * If the display name is not available for the locale, 742 * then this method returns a string in the localized GMT offset format 743 * such as <code>GMT[+-]HH:mm</code>. 744 * @param locale the locale in which to supply the display name. 745 * @param result the human-readable name of this time zone in the given locale 746 * or in the default locale if the given locale is not recognized. 747 * @return A reference to 'result'. 748 * @stable ICU 2.0 749 */ 750 UnicodeString& getDisplayName(const Locale& locale, UnicodeString& result) const; 751 752 /** 753 * Returns a name of this time zone suitable for presentation to the user 754 * in the default locale. 755 * If the display name is not available for the locale, 756 * then this method returns a string in the localized GMT offset format 757 * such as <code>GMT[+-]HH:mm</code>. 758 * @param inDaylight if true, return the daylight savings name. 759 * @param style 760 * @param result the human-readable name of this time zone in the default locale. 761 * @return A reference to 'result'. 762 * @stable ICU 2.0 763 */ 764 UnicodeString& getDisplayName(UBool inDaylight, EDisplayType style, UnicodeString& result) const; 765 766 /** 767 * Returns a name of this time zone suitable for presentation to the user 768 * in the specified locale. 769 * If the display name is not available for the locale, 770 * then this method returns a string in the localized GMT offset format 771 * such as <code>GMT[+-]HH:mm</code>. 772 * @param inDaylight if true, return the daylight savings name. 773 * @param style 774 * @param locale the locale in which to supply the display name. 775 * @param result the human-readable name of this time zone in the given locale 776 * or in the default locale if the given locale is not recognized. 777 * @return A reference to 'result'. 778 * @stable ICU 2.0 779 */ 780 UnicodeString& getDisplayName(UBool inDaylight, EDisplayType style, const Locale& locale, UnicodeString& result) const; 781 782 /** 783 * Queries if this time zone uses daylight savings time. 784 * @return true if this time zone uses daylight savings time, 785 * false, otherwise. 786 * <p><strong>Note:</strong>The default implementation of 787 * ICU TimeZone uses the tz database, which supports historic 788 * rule changes, for system time zones. With the implementation, 789 * there are time zones that used daylight savings time in the 790 * past, but no longer used currently. For example, Asia/Tokyo has 791 * never used daylight savings time since 1951. Most clients would 792 * expect that this method to return <code>false</code> for such case. 793 * The default implementation of this method returns <code>true</code> 794 * when the time zone uses daylight savings time in the current 795 * (Gregorian) calendar year. 796 * <p>In Java 7, <code>observesDaylightTime()</code> was added in 797 * addition to <code>useDaylightTime()</code>. In Java, <code>useDaylightTime()</code> 798 * only checks if daylight saving time is observed by the last known 799 * rule. This specification might not be what most users would expect 800 * if daylight saving time is currently observed, but not scheduled 801 * in future. In this case, Java's <code>userDaylightTime()</code> returns 802 * <code>false</code>. To resolve the issue, Java 7 added <code>observesDaylightTime()</code>, 803 * which takes the current rule into account. The method <code>observesDaylightTime()</code> 804 * was added in ICU4J for supporting API signature compatibility with JDK. 805 * In general, ICU4C also provides JDK compatible methods, but the current 806 * implementation <code>userDaylightTime()</code> serves the purpose 807 * (takes the current rule into account), <code>observesDaylightTime()</code> 808 * is not added in ICU4C. In addition to <code>useDaylightTime()</code>, ICU4C 809 * <code>BasicTimeZone</code> class (Note that <code>TimeZone::createTimeZone(const UnicodeString &ID)</code> 810 * always returns a <code>BasicTimeZone</code>) provides a series of methods allowing 811 * historic and future time zone rule iteration, so you can check if daylight saving 812 * time is observed or not within a given period. 813 * 814 * @stable ICU 2.0 815 */ 816 virtual UBool useDaylightTime(void) const = 0; 817 818 #ifndef U_FORCE_HIDE_DEPRECATED_API 819 /** 820 * Queries if the given date is in daylight savings time in 821 * this time zone. 822 * This method is wasteful since it creates a new GregorianCalendar and 823 * deletes it each time it is called. This is a deprecated method 824 * and provided only for Java compatibility. 825 * 826 * @param date the given UDate. 827 * @param status Output param filled in with success/error code. 828 * @return true if the given date is in daylight savings time, 829 * false, otherwise. 830 * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead. 831 */ 832 virtual UBool inDaylightTime(UDate date, UErrorCode& status) const = 0; 833 #endif // U_FORCE_HIDE_DEPRECATED_API 834 835 /** 836 * Returns true if this zone has the same rule and offset as another zone. 837 * That is, if this zone differs only in ID, if at all. 838 * @param other the <code>TimeZone</code> object to be compared with 839 * @return true if the given zone is the same as this one, 840 * with the possible exception of the ID 841 * @stable ICU 2.0 842 */ 843 virtual UBool hasSameRules(const TimeZone& other) const; 844 845 /** 846 * Clones TimeZone objects polymorphically. Clients are responsible for deleting 847 * the TimeZone object cloned. 848 * 849 * @return A new copy of this TimeZone object. 850 * @stable ICU 2.0 851 */ 852 virtual TimeZone* clone() const = 0; 853 854 /** 855 * Return the class ID for this class. This is useful only for 856 * comparing to a return value from getDynamicClassID(). 857 * @return The class ID for all objects of this class. 858 * @stable ICU 2.0 859 */ 860 static UClassID U_EXPORT2 getStaticClassID(void); 861 862 /** 863 * Returns a unique class ID POLYMORPHICALLY. This method is to 864 * implement a simple version of RTTI, since not all C++ compilers support genuine 865 * RTTI. Polymorphic operator==() and clone() methods call this method. 866 * <P> 867 * Concrete subclasses of TimeZone must use the UOBJECT_DEFINE_RTTI_IMPLEMENTATION 868 * macro from uobject.h in their implementation to provide correct RTTI information. 869 * @return The class ID for this object. All objects of a given class have the 870 * same class ID. Objects of other classes have different class IDs. 871 * @stable ICU 2.0 872 */ 873 virtual UClassID getDynamicClassID(void) const override = 0; 874 875 /** 876 * Returns the amount of time to be added to local standard time 877 * to get local wall clock time. 878 * <p> 879 * The default implementation always returns 3600000 milliseconds 880 * (i.e., one hour) if this time zone observes Daylight Saving 881 * Time. Otherwise, 0 (zero) is returned. 882 * <p> 883 * If an underlying TimeZone implementation subclass supports 884 * historical Daylight Saving Time changes, this method returns 885 * the known latest daylight saving value. 886 * 887 * @return the amount of saving time in milliseconds 888 * @stable ICU 3.6 889 */ 890 virtual int32_t getDSTSavings() const; 891 892 /** 893 * Gets the region code associated with the given 894 * system time zone ID. The region code is either ISO 3166 895 * 2-letter country code or UN M.49 3-digit area code. 896 * When the time zone is not associated with a specific location, 897 * for example - "Etc/UTC", "EST5EDT", then this method returns 898 * "001" (UN M.49 area code for World). 899 * 900 * @param id The system time zone ID. 901 * @param region Output buffer for receiving the region code. 902 * @param capacity The size of the output buffer. 903 * @param status Receives the status. When the given time zone ID 904 * is not a known system time zone ID, 905 * U_ILLEGAL_ARGUMENT_ERROR is set. 906 * @return The length of the output region code. 907 * @stable ICU 4.8 908 */ 909 static int32_t U_EXPORT2 getRegion(const UnicodeString& id, 910 char *region, int32_t capacity, UErrorCode& status); 911 912 protected: 913 914 /** 915 * Default constructor. ID is initialized to the empty string. 916 * @stable ICU 2.0 917 */ 918 TimeZone(); 919 920 /** 921 * Construct a TimeZone with a given ID. 922 * @param id a system time zone ID 923 * @stable ICU 2.0 924 */ 925 TimeZone(const UnicodeString &id); 926 927 /** 928 * Copy constructor. 929 * @param source the object to be copied. 930 * @stable ICU 2.0 931 */ 932 TimeZone(const TimeZone& source); 933 934 /** 935 * Default assignment operator. 936 * @param right the object to be copied. 937 * @stable ICU 2.0 938 */ 939 TimeZone& operator=(const TimeZone& right); 940 941 #ifndef U_HIDE_INTERNAL_API 942 /** 943 * Utility function. For internally loading rule data. 944 * @param top Top resource bundle for tz data 945 * @param ruleid ID of rule to load 946 * @param oldbundle Old bundle to reuse or nullptr 947 * @param status Status parameter 948 * @return either a new bundle or *oldbundle 949 * @internal 950 */ 951 static UResourceBundle* loadRule(const UResourceBundle* top, const UnicodeString& ruleid, UResourceBundle* oldbundle, UErrorCode&status); 952 #endif /* U_HIDE_INTERNAL_API */ 953 954 private: 955 friend class ZoneMeta; 956 957 958 static TimeZone* createCustomTimeZone(const UnicodeString&); // Creates a time zone based on the string. 959 960 /** 961 * Finds the given ID in the Olson tzdata. If the given ID is found in the tzdata, 962 * returns the pointer to the ID resource. This method is exposed through ZoneMeta class 963 * for ICU internal implementation and useful for building hashtable using a time zone 964 * ID as a key. 965 * @param id zone id string 966 * @return the pointer of the ID resource, or nullptr. 967 */ 968 static const char16_t* findID(const UnicodeString& id); 969 970 /** 971 * Resolve a link in Olson tzdata. When the given id is known and it's not a link, 972 * the id itself is returned. When the given id is known and it is a link, then 973 * dereferenced zone id is returned. When the given id is unknown, then it returns 974 * nullptr. 975 * @param id zone id string 976 * @return the dereferenced zone or nullptr 977 */ 978 static const char16_t* dereferOlsonLink(const UnicodeString& id); 979 980 /** 981 * Returns the region code associated with the given zone, 982 * or nullptr if the zone is not known. 983 * @param id zone id string 984 * @return the region associated with the given zone 985 */ 986 static const char16_t* getRegion(const UnicodeString& id); 987 988 public: 989 #ifndef U_HIDE_INTERNAL_API 990 /** 991 * Returns the region code associated with the given zone, 992 * or nullptr if the zone is not known. 993 * @param id zone id string 994 * @param status Status parameter 995 * @return the region associated with the given zone 996 * @internal 997 */ 998 static const char16_t* getRegion(const UnicodeString& id, UErrorCode& status); 999 #endif /* U_HIDE_INTERNAL_API */ 1000 1001 private: 1002 /** 1003 * Parses the given custom time zone identifier 1004 * @param id id A string of the form GMT[+-]hh:mm, GMT[+-]hhmm, or 1005 * GMT[+-]hh. 1006 * @param sign Receives parsed sign, 1 for positive, -1 for negative. 1007 * @param hour Receives parsed hour field 1008 * @param minute Receives parsed minute field 1009 * @param second Receives parsed second field 1010 * @return Returns true when the given custom id is valid. 1011 */ 1012 static UBool parseCustomID(const UnicodeString& id, int32_t& sign, int32_t& hour, 1013 int32_t& minute, int32_t& second); 1014 1015 /** 1016 * Parse a custom time zone identifier and return the normalized 1017 * custom time zone identifier for the given custom id string. 1018 * @param id a string of the form GMT[+-]hh:mm, GMT[+-]hhmm, or 1019 * GMT[+-]hh. 1020 * @param normalized Receives the normalized custom ID 1021 * @param status Receives the status. When the input ID string is invalid, 1022 * U_ILLEGAL_ARGUMENT_ERROR is set. 1023 * @return The normalized custom id string. 1024 */ 1025 static UnicodeString& getCustomID(const UnicodeString& id, UnicodeString& normalized, 1026 UErrorCode& status); 1027 1028 /** 1029 * Returns the normalized custom time zone ID for the given offset fields. 1030 * @param hour offset hours 1031 * @param min offset minutes 1032 * @param sec offset seconds 1033 * @param negative sign of the offset, true for negative offset. 1034 * @param id Receives the format result (normalized custom ID) 1035 * @return The reference to id 1036 */ 1037 static UnicodeString& formatCustomID(int32_t hour, int32_t min, int32_t sec, 1038 UBool negative, UnicodeString& id); 1039 1040 UnicodeString fID; // this time zone's ID 1041 1042 friend class TZEnumeration; 1043 }; 1044 1045 1046 // ------------------------------------- 1047 1048 inline UnicodeString& 1049 TimeZone::getID(UnicodeString& ID) const 1050 { 1051 ID = fID; 1052 return ID; 1053 } 1054 1055 // ------------------------------------- 1056 1057 inline void 1058 TimeZone::setID(const UnicodeString& ID) 1059 { 1060 fID = ID; 1061 } 1062 U_NAMESPACE_END 1063 1064 #endif /* #if !UCONFIG_NO_FORMATTING */ 1065 1066 #endif /* U_SHOW_CPLUSPLUS_API */ 1067 1068 #endif //_TIMEZONE 1069 //eof
Contact us
|
About us
|
Term of use
|
Copyright © 2000-2025 MyWebUniversity.com ™
