tzfmt.h (45831B)
1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ******************************************************************************* 5 * Copyright (C) 2011-2015, International Business Machines Corporation and 6 * others. All Rights Reserved. 7 ******************************************************************************* 8 */ 9 #ifndef __TZFMT_H 10 #define __TZFMT_H 11 12 /** 13 * \file 14 * \brief C++ API: TimeZoneFormat 15 */ 16 17 #include "unicode/utypes.h" 18 19 #if U_SHOW_CPLUSPLUS_API 20 21 #if !UCONFIG_NO_FORMATTING 22 23 #include "unicode/format.h" 24 #include "unicode/timezone.h" 25 #include "unicode/tznames.h" 26 27 U_CDECL_BEGIN 28 /** 29 * Constants for time zone display format style used by format/parse APIs 30 * in TimeZoneFormat. 31 * @stable ICU 50 32 */ 33 typedef enum UTimeZoneFormatStyle { 34 /** 35 * Generic location format, such as "United States Time (New York)", "Italy Time" 36 * @stable ICU 50 37 */ 38 UTZFMT_STYLE_GENERIC_LOCATION, 39 /** 40 * Generic long non-location format, such as "Eastern Time". 41 * @stable ICU 50 42 */ 43 UTZFMT_STYLE_GENERIC_LONG, 44 /** 45 * Generic short non-location format, such as "ET". 46 * @stable ICU 50 47 */ 48 UTZFMT_STYLE_GENERIC_SHORT, 49 /** 50 * Specific long format, such as "Eastern Standard Time". 51 * @stable ICU 50 52 */ 53 UTZFMT_STYLE_SPECIFIC_LONG, 54 /** 55 * Specific short format, such as "EST", "PDT". 56 * @stable ICU 50 57 */ 58 UTZFMT_STYLE_SPECIFIC_SHORT, 59 /** 60 * Localized GMT offset format, such as "GMT-05:00", "UTC+0100" 61 * @stable ICU 50 62 */ 63 UTZFMT_STYLE_LOCALIZED_GMT, 64 /** 65 * Short localized GMT offset format, such as "GMT-5", "UTC+1:30" 66 * This style is equivalent to the LDML date format pattern "O". 67 * @stable ICU 51 68 */ 69 UTZFMT_STYLE_LOCALIZED_GMT_SHORT, 70 /** 71 * Short ISO 8601 local time difference (basic format) or the UTC indicator. 72 * For example, "-05", "+0530", and "Z"(UTC). 73 * This style is equivalent to the LDML date format pattern "X". 74 * @stable ICU 51 75 */ 76 UTZFMT_STYLE_ISO_BASIC_SHORT, 77 /** 78 * Short ISO 8601 locale time difference (basic format). 79 * For example, "-05" and "+0530". 80 * This style is equivalent to the LDML date format pattern "x". 81 * @stable ICU 51 82 */ 83 UTZFMT_STYLE_ISO_BASIC_LOCAL_SHORT, 84 /** 85 * Fixed width ISO 8601 local time difference (basic format) or the UTC indicator. 86 * For example, "-0500", "+0530", and "Z"(UTC). 87 * This style is equivalent to the LDML date format pattern "XX". 88 * @stable ICU 51 89 */ 90 UTZFMT_STYLE_ISO_BASIC_FIXED, 91 /** 92 * Fixed width ISO 8601 local time difference (basic format). 93 * For example, "-0500" and "+0530". 94 * This style is equivalent to the LDML date format pattern "xx". 95 * @stable ICU 51 96 */ 97 UTZFMT_STYLE_ISO_BASIC_LOCAL_FIXED, 98 /** 99 * ISO 8601 local time difference (basic format) with optional seconds field, or the UTC indicator. 100 * For example, "-0500", "+052538", and "Z"(UTC). 101 * This style is equivalent to the LDML date format pattern "XXXX". 102 * @stable ICU 51 103 */ 104 UTZFMT_STYLE_ISO_BASIC_FULL, 105 /** 106 * ISO 8601 local time difference (basic format) with optional seconds field. 107 * For example, "-0500" and "+052538". 108 * This style is equivalent to the LDML date format pattern "xxxx". 109 * @stable ICU 51 110 */ 111 UTZFMT_STYLE_ISO_BASIC_LOCAL_FULL, 112 /** 113 * Fixed width ISO 8601 local time difference (extended format) or the UTC indicator. 114 * For example, "-05:00", "+05:30", and "Z"(UTC). 115 * This style is equivalent to the LDML date format pattern "XXX". 116 * @stable ICU 51 117 */ 118 UTZFMT_STYLE_ISO_EXTENDED_FIXED, 119 /** 120 * Fixed width ISO 8601 local time difference (extended format). 121 * For example, "-05:00" and "+05:30". 122 * This style is equivalent to the LDML date format pattern "xxx" and "ZZZZZ". 123 * @stable ICU 51 124 */ 125 UTZFMT_STYLE_ISO_EXTENDED_LOCAL_FIXED, 126 /** 127 * ISO 8601 local time difference (extended format) with optional seconds field, or the UTC indicator. 128 * For example, "-05:00", "+05:25:38", and "Z"(UTC). 129 * This style is equivalent to the LDML date format pattern "XXXXX". 130 * @stable ICU 51 131 */ 132 UTZFMT_STYLE_ISO_EXTENDED_FULL, 133 /** 134 * ISO 8601 local time difference (extended format) with optional seconds field. 135 * For example, "-05:00" and "+05:25:38". 136 * This style is equivalent to the LDML date format pattern "xxxxx". 137 * @stable ICU 51 138 */ 139 UTZFMT_STYLE_ISO_EXTENDED_LOCAL_FULL, 140 /** 141 * Time Zone ID, such as "America/Los_Angeles". 142 * @stable ICU 51 143 */ 144 UTZFMT_STYLE_ZONE_ID, 145 /** 146 * Short Time Zone ID (BCP 47 Unicode location extension, time zone type value), such as "uslax". 147 * @stable ICU 51 148 */ 149 UTZFMT_STYLE_ZONE_ID_SHORT, 150 /** 151 * Exemplar location, such as "Los Angeles" and "Paris". 152 * @stable ICU 51 153 */ 154 UTZFMT_STYLE_EXEMPLAR_LOCATION 155 } UTimeZoneFormatStyle; 156 157 /** 158 * Constants for GMT offset pattern types. 159 * @stable ICU 50 160 */ 161 typedef enum UTimeZoneFormatGMTOffsetPatternType { 162 /** 163 * Positive offset with hours and minutes fields 164 * @stable ICU 50 165 */ 166 UTZFMT_PAT_POSITIVE_HM, 167 /** 168 * Positive offset with hours, minutes and seconds fields 169 * @stable ICU 50 170 */ 171 UTZFMT_PAT_POSITIVE_HMS, 172 /** 173 * Negative offset with hours and minutes fields 174 * @stable ICU 50 175 */ 176 UTZFMT_PAT_NEGATIVE_HM, 177 /** 178 * Negative offset with hours, minutes and seconds fields 179 * @stable ICU 50 180 */ 181 UTZFMT_PAT_NEGATIVE_HMS, 182 /** 183 * Positive offset with hours field 184 * @stable ICU 51 185 */ 186 UTZFMT_PAT_POSITIVE_H, 187 /** 188 * Negative offset with hours field 189 * @stable ICU 51 190 */ 191 UTZFMT_PAT_NEGATIVE_H, 192 193 /* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed for other .h declarations */ 194 /** 195 * Number of UTimeZoneFormatGMTOffsetPatternType types. 196 * @internal 197 */ 198 UTZFMT_PAT_COUNT = 6 199 } UTimeZoneFormatGMTOffsetPatternType; 200 201 /** 202 * Constants for time types used by TimeZoneFormat APIs for 203 * receiving time type (standard time, daylight time or unknown). 204 * @stable ICU 50 205 */ 206 typedef enum UTimeZoneFormatTimeType { 207 /** 208 * Unknown 209 * @stable ICU 50 210 */ 211 UTZFMT_TIME_TYPE_UNKNOWN, 212 /** 213 * Standard time 214 * @stable ICU 50 215 */ 216 UTZFMT_TIME_TYPE_STANDARD, 217 /** 218 * Daylight saving time 219 * @stable ICU 50 220 */ 221 UTZFMT_TIME_TYPE_DAYLIGHT 222 } UTimeZoneFormatTimeType; 223 224 /** 225 * Constants for parse option flags, used for specifying optional parse behavior. 226 * @stable ICU 50 227 */ 228 typedef enum UTimeZoneFormatParseOption { 229 /** 230 * No option. 231 * @stable ICU 50 232 */ 233 UTZFMT_PARSE_OPTION_NONE = 0x00, 234 /** 235 * When a time zone display name is not found within a set of display names 236 * used for the specified style, look for the name from display names used 237 * by other styles. 238 * @stable ICU 50 239 */ 240 UTZFMT_PARSE_OPTION_ALL_STYLES = 0x01, 241 /** 242 * When parsing a time zone display name in \link UTZFMT_STYLE_SPECIFIC_SHORT \endlink, 243 * look for the IANA tz database compatible zone abbreviations in addition 244 * to the localized names coming from the icu::TimeZoneNames currently 245 * used by the icu::TimeZoneFormat. 246 * @stable ICU 54 247 */ 248 UTZFMT_PARSE_OPTION_TZ_DATABASE_ABBREVIATIONS = 0x02 249 } UTimeZoneFormatParseOption; 250 251 U_CDECL_END 252 253 U_NAMESPACE_BEGIN 254 255 class TimeZoneGenericNames; 256 class TZDBTimeZoneNames; 257 class UVector; 258 259 /** 260 * <code>TimeZoneFormat</code> supports time zone display name formatting and parsing. 261 * An instance of TimeZoneFormat works as a subformatter of {@link SimpleDateFormat}, 262 * but you can also directly get a new instance of <code>TimeZoneFormat</code> and 263 * formatting/parsing time zone display names. 264 * <p> 265 * ICU implements the time zone display names defined by <a href="http://www.unicode.org/reports/tr35/">UTS#35 266 * Unicode Locale Data Markup Language (LDML)</a>. {@link TimeZoneNames} represents the 267 * time zone display name data model and this class implements the algorithm for actual 268 * formatting and parsing. 269 * 270 * @see SimpleDateFormat 271 * @see TimeZoneNames 272 * @stable ICU 50 273 */ 274 class U_I18N_API_CLASS TimeZoneFormat : public Format { 275 public: 276 /** 277 * Copy constructor. 278 * @stable ICU 50 279 */ 280 U_I18N_API TimeZoneFormat(const TimeZoneFormat& other); 281 282 /** 283 * Destructor. 284 * @stable ICU 50 285 */ 286 U_I18N_API virtual ~TimeZoneFormat(); 287 288 /** 289 * Assignment operator. 290 * @stable ICU 50 291 */ 292 U_I18N_API TimeZoneFormat& operator=(const TimeZoneFormat& other); 293 294 /** 295 * Return true if the given Format objects are semantically equal. 296 * Objects of different subclasses are considered unequal. 297 * @param other The object to be compared with. 298 * @return Return true if the given Format objects are semantically equal. 299 * Objects of different subclasses are considered unequal. 300 * @stable ICU 50 301 */ 302 U_I18N_API virtual bool operator==(const Format& other) const override; 303 304 /** 305 * Clone this object polymorphically. The caller is responsible 306 * for deleting the result when done. 307 * @return A copy of the object 308 * @stable ICU 50 309 */ 310 U_I18N_API virtual TimeZoneFormat* clone() const override; 311 312 /** 313 * Creates an instance of <code>TimeZoneFormat</code> for the given locale. 314 * @param locale The locale. 315 * @param status Receives the status. 316 * @return An instance of <code>TimeZoneFormat</code> for the given locale, 317 * owned by the caller. 318 * @stable ICU 50 319 */ 320 U_I18N_API static TimeZoneFormat* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status); 321 322 /** 323 * Returns the time zone display name data used by this instance. 324 * @return The time zone display name data. 325 * @stable ICU 50 326 */ 327 U_I18N_API const TimeZoneNames* getTimeZoneNames() const; 328 329 /** 330 * Sets the time zone display name data to this format instance. 331 * The caller should not delete the TimeZoenNames object after it is adopted 332 * by this call. 333 * @param tznames TimeZoneNames object to be adopted. 334 * @stable ICU 50 335 */ 336 U_I18N_API void adoptTimeZoneNames(TimeZoneNames* tznames); 337 338 /** 339 * Sets the time zone display name data to this format instance. 340 * @param tznames TimeZoneNames object to be set. 341 * @stable ICU 50 342 */ 343 U_I18N_API void setTimeZoneNames(const TimeZoneNames& tznames); 344 345 /** 346 * Returns the localized GMT format pattern. 347 * @param pattern Receives the localized GMT format pattern. 348 * @return A reference to the result pattern. 349 * @see #setGMTPattern 350 * @stable ICU 50 351 */ 352 U_I18N_API UnicodeString& getGMTPattern(UnicodeString& pattern) const; 353 354 /** 355 * Sets the localized GMT format pattern. The pattern must contain 356 * a single argument {0}, for example "GMT {0}". 357 * @param pattern The localized GMT format pattern to be used by this object. 358 * @param status Receives the status. 359 * @see #getGMTPattern 360 * @stable ICU 50 361 */ 362 U_I18N_API void setGMTPattern(const UnicodeString& pattern, UErrorCode& status); 363 364 /** 365 * Returns the offset pattern used for localized GMT format. 366 * @param type The offset pattern type enum. 367 * @param pattern Receives the offset pattern. 368 * @return A reference to the result pattern. 369 * @see #setGMTOffsetPattern 370 * @stable ICU 50 371 */ 372 U_I18N_API UnicodeString& getGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, 373 UnicodeString& pattern) const; 374 375 /** 376 * Sets the offset pattern for the given offset type. 377 * @param type The offset pattern type enum. 378 * @param pattern The offset pattern used for localized GMT format for the type. 379 * @param status Receives the status. 380 * @see #getGMTOffsetPattern 381 * @stable ICU 50 382 */ 383 U_I18N_API void setGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, 384 const UnicodeString& pattern, UErrorCode& status); 385 386 /** 387 * Returns the decimal digit characters used for localized GMT format. 388 * The return string contains exactly 10 code points (may include Unicode 389 * supplementary character) representing digit 0 to digit 9 in the ascending 390 * order. 391 * @param digits Receives the decimal digits used for localized GMT format. 392 * @see #setGMTOffsetDigits 393 * @stable ICU 50 394 */ 395 U_I18N_API UnicodeString& getGMTOffsetDigits(UnicodeString& digits) const; 396 397 /** 398 * Sets the decimal digit characters used for localized GMT format. 399 * The input <code>digits</code> must contain exactly 10 code points 400 * (Unicode supplementary characters are also allowed) representing 401 * digit 0 to digit 9 in the ascending order. When the input <code>digits</code> 402 * does not satisfy the condition, <code>U_ILLEGAL_ARGUMENT_ERROR</code> 403 * will be set to the return status. 404 * @param digits The decimal digits used for localized GMT format. 405 * @param status Receives the status. 406 * @see #getGMTOffsetDigits 407 * @stable ICU 50 408 */ 409 U_I18N_API void setGMTOffsetDigits(const UnicodeString& digits, UErrorCode& status); 410 411 /** 412 * Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0). 413 * @param gmtZeroFormat Receives the localized GMT string string for GMT(UTC) itself. 414 * @return A reference to the result GMT string. 415 * @see #setGMTZeroFormat 416 * @stable ICU 50 417 */ 418 U_I18N_API UnicodeString& getGMTZeroFormat(UnicodeString& gmtZeroFormat) const; 419 420 /** 421 * Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0). 422 * @param gmtZeroFormat The localized GMT format string for GMT(UTC). 423 * @param status Receives the status. 424 * @see #getGMTZeroFormat 425 * @stable ICU 50 426 */ 427 U_I18N_API void setGMTZeroFormat(const UnicodeString& gmtZeroFormat, UErrorCode& status); 428 429 /** 430 * Returns the bitwise flags of UTimeZoneFormatParseOption representing the default parse 431 * options used by this object. 432 * @return the default parse options. 433 * @see ParseOption 434 * @stable ICU 50 435 */ 436 U_I18N_API uint32_t getDefaultParseOptions() const; 437 438 /** 439 * Sets the default parse options. 440 * <p><b>Note</b>: By default, an instance of <code>TimeZoneFormat</code> 441 * created by {@link #createInstance} has no parse options set (UTZFMT_PARSE_OPTION_NONE). 442 * To specify multiple options, use bitwise flags of UTimeZoneFormatParseOption. 443 * @see #UTimeZoneFormatParseOption 444 * @stable ICU 50 445 */ 446 U_I18N_API void setDefaultParseOptions(uint32_t flags); 447 448 /** 449 * Returns the ISO 8601 basic time zone string for the given offset. 450 * For example, "-08", "-0830" and "Z" 451 * 452 * @param offset the offset from GMT(UTC) in milliseconds. 453 * @param useUtcIndicator true if ISO 8601 UTC indicator "Z" is used when the offset is 0. 454 * @param isShort true if shortest form is used. 455 * @param ignoreSeconds true if non-zero offset seconds is appended. 456 * @param result Receives the ISO format string. 457 * @param status Receives the status 458 * @return the ISO 8601 basic format. 459 * @see #formatOffsetISO8601Extended 460 * @see #parseOffsetISO8601 461 * @stable ICU 51 462 */ 463 U_I18N_API UnicodeString& formatOffsetISO8601Basic(int32_t offset, 464 UBool useUtcIndicator, 465 UBool isShort, 466 UBool ignoreSeconds, 467 UnicodeString& result, 468 UErrorCode& status) const; 469 470 /** 471 * Returns the ISO 8601 extended time zone string for the given offset. 472 * For example, "-08:00", "-08:30" and "Z" 473 * 474 * @param offset the offset from GMT(UTC) in milliseconds. 475 * @param useUtcIndicator true if ISO 8601 UTC indicator "Z" is used when the offset is 0. 476 * @param isShort true if shortest form is used. 477 * @param ignoreSeconds true if non-zero offset seconds is appended. 478 * @param result Receives the ISO format string. 479 * @param status Receives the status 480 * @return the ISO 8601 basic format. 481 * @see #formatOffsetISO8601Extended 482 * @see #parseOffsetISO8601 483 * @stable ICU 51 484 */ 485 U_I18N_API UnicodeString& formatOffsetISO8601Extended(int32_t offset, 486 UBool useUtcIndicator, 487 UBool isShort, 488 UBool ignoreSeconds, 489 UnicodeString& result, 490 UErrorCode& status) const; 491 492 /** 493 * Returns the localized GMT(UTC) offset format for the given offset. 494 * The localized GMT offset is defined by; 495 * <ul> 496 * <li>GMT format pattern (e.g. "GMT {0}" - see {@link #getGMTPattern}) 497 * <li>Offset time pattern (e.g. "+HH:mm" - see {@link #getGMTOffsetPattern}) 498 * <li>Offset digits (e.g. "0123456789" - see {@link #getGMTOffsetDigits}) 499 * <li>GMT zero format (e.g. "GMT" - see {@link #getGMTZeroFormat}) 500 * </ul> 501 * This format always uses 2 digit hours and minutes. When the given offset has non-zero 502 * seconds, 2 digit seconds field will be appended. For example, 503 * GMT+05:00 and GMT+05:28:06. 504 * @param offset the offset from GMT(UTC) in milliseconds. 505 * @param status Receives the status 506 * @param result Receives the localized GMT format string. 507 * @return A reference to the result. 508 * @see #parseOffsetLocalizedGMT 509 * @stable ICU 50 510 */ 511 U_I18N_API UnicodeString& formatOffsetLocalizedGMT(int32_t offset, 512 UnicodeString& result, 513 UErrorCode& status) const; 514 515 /** 516 * Returns the short localized GMT(UTC) offset format for the given offset. 517 * The short localized GMT offset is defined by; 518 * <ul> 519 * <li>GMT format pattern (e.g. "GMT {0}" - see {@link #getGMTPattern}) 520 * <li>Offset time pattern (e.g. "+HH:mm" - see {@link #getGMTOffsetPattern}) 521 * <li>Offset digits (e.g. "0123456789" - see {@link #getGMTOffsetDigits}) 522 * <li>GMT zero format (e.g. "GMT" - see {@link #getGMTZeroFormat}) 523 * </ul> 524 * This format uses the shortest representation of offset. The hours field does not 525 * have leading zero and lower fields with zero will be truncated. For example, 526 * GMT+5 and GMT+530. 527 * @param offset the offset from GMT(UTC) in milliseconds. 528 * @param status Receives the status 529 * @param result Receives the short localized GMT format string. 530 * @return A reference to the result. 531 * @see #parseOffsetShortLocalizedGMT 532 * @stable ICU 51 533 */ 534 U_I18N_API UnicodeString& formatOffsetShortLocalizedGMT(int32_t offset, 535 UnicodeString& result, 536 UErrorCode& status) const; 537 538 using Format::format; 539 540 /** 541 * Returns the display name of the time zone at the given date for the style. 542 * @param style The style (e.g. <code>UTZFMT_STYLE_GENERIC_LONG</code>, <code>UTZFMT_STYLE_LOCALIZED_GMT</code>...) 543 * @param tz The time zone. 544 * @param date The date. 545 * @param name Receives the display name. 546 * @param timeType the output argument for receiving the time type (standard/daylight/unknown) 547 * used for the display name, or nullptr if the information is not necessary. 548 * @return A reference to the result 549 * @see #UTimeZoneFormatStyle 550 * @see #UTimeZoneFormatTimeType 551 * @stable ICU 50 552 */ 553 U_I18N_API virtual UnicodeString& format(UTimeZoneFormatStyle style, 554 const TimeZone& tz, 555 UDate date, 556 UnicodeString& name, 557 UTimeZoneFormatTimeType* timeType = nullptr) const; 558 559 /** 560 * Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 561 * style time zone string. When the given string is not an ISO 8601 time zone 562 * string, this method sets the current position as the error index 563 * to <code>ParsePosition pos</code> and returns 0. 564 * @param text The text contains ISO8601 style time zone string (e.g. "-08:00", "Z") 565 * at the position. 566 * @param pos The ParsePosition object. 567 * @return The offset from GMT(UTC) in milliseconds for the given ISO 8601 style 568 * time zone string. 569 * @see #formatOffsetISO8601Basic 570 * @see #formatOffsetISO8601Extended 571 * @stable ICU 50 572 */ 573 U_I18N_API int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos) const; 574 575 /** 576 * Returns offset from GMT(UTC) in milliseconds for the given localized GMT 577 * offset format string. When the given string cannot be parsed, this method 578 * sets the current position as the error index to <code>ParsePosition pos</code> 579 * and returns 0. 580 * @param text The text contains a localized GMT offset string at the position. 581 * @param pos The ParsePosition object. 582 * @return The offset from GMT(UTC) in milliseconds for the given localized GMT 583 * offset format string. 584 * @see #formatOffsetLocalizedGMT 585 * @stable ICU 50 586 */ 587 U_I18N_API int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const; 588 589 /** 590 * Returns offset from GMT(UTC) in milliseconds for the given short localized GMT 591 * offset format string. When the given string cannot be parsed, this method 592 * sets the current position as the error index to <code>ParsePosition pos</code> 593 * and returns 0. 594 * @param text The text contains a short localized GMT offset string at the position. 595 * @param pos The ParsePosition object. 596 * @return The offset from GMT(UTC) in milliseconds for the given short localized GMT 597 * offset format string. 598 * @see #formatOffsetShortLocalizedGMT 599 * @stable ICU 51 600 */ 601 U_I18N_API int32_t parseOffsetShortLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const; 602 603 /** 604 * Returns a <code>TimeZone</code> by parsing the time zone string according to 605 * the given parse position, the specified format style and parse options. 606 * 607 * @param text The text contains a time zone string at the position. 608 * @param style The format style 609 * @param pos The position. 610 * @param parseOptions The parse options represented by bitwise flags of UTimeZoneFormatParseOption. 611 * @param timeType The output argument for receiving the time type (standard/daylight/unknown), 612 * or nullptr if the information is not necessary. 613 * @return A <code>TimeZone</code>, or null if the input could not be parsed. 614 * @see UTimeZoneFormatStyle 615 * @see UTimeZoneFormatParseOption 616 * @see UTimeZoneFormatTimeType 617 * @stable ICU 50 618 */ 619 U_I18N_API virtual TimeZone* parse(UTimeZoneFormatStyle style, 620 const UnicodeString& text, 621 ParsePosition& pos, 622 int32_t parseOptions, 623 UTimeZoneFormatTimeType* timeType = nullptr) const; 624 625 /** 626 * Returns a <code>TimeZone</code> by parsing the time zone string according to 627 * the given parse position, the specified format style and the default parse options. 628 * 629 * @param text The text contains a time zone string at the position. 630 * @param style The format style 631 * @param pos The position. 632 * @param timeType The output argument for receiving the time type (standard/daylight/unknown), 633 * or nullptr if the information is not necessary. 634 * @return A <code>TimeZone</code>, or null if the input could not be parsed. 635 * @see UTimeZoneFormatStyle 636 * @see UTimeZoneFormatParseOption 637 * @see UTimeZoneFormatTimeType 638 * @stable ICU 50 639 */ 640 U_I18N_API TimeZone* parse(UTimeZoneFormatStyle style, 641 const UnicodeString& text, 642 ParsePosition& pos, 643 UTimeZoneFormatTimeType* timeType = nullptr) const; 644 645 /* ---------------------------------------------- 646 * Format APIs 647 * ---------------------------------------------- */ 648 649 /** 650 * Format an object to produce a time zone display string using localized GMT offset format. 651 * This method handles Formattable objects with a <code>TimeZone</code>. If a the Formattable 652 * object type is not a <code>TimeZone</code>, then it returns a failing UErrorCode. 653 * @param obj The object to format. Must be a <code>TimeZone</code>. 654 * @param appendTo Output parameter to receive result. Result is appended to existing contents. 655 * @param pos On input: an alignment field, if desired. On output: the offsets of the alignment field. 656 * @param status Output param filled with success/failure status. 657 * @return Reference to 'appendTo' parameter. 658 * @stable ICU 50 659 */ 660 U_I18N_API virtual UnicodeString& format(const Formattable& obj, 661 UnicodeString& appendTo, 662 FieldPosition& pos, 663 UErrorCode& status) const override; 664 665 /** 666 * Parse a string to produce an object. This methods handles parsing of 667 * time zone display strings into Formattable objects with <code>TimeZone</code>. 668 * @param source The string to be parsed into an object. 669 * @param result Formattable to be set to the parse result. If parse fails, return contents are undefined. 670 * @param parse_pos The position to start parsing at. Upon return this param is set to the position after the 671 * last character successfully parsed. If the source is not parsed successfully, this param 672 * will remain unchanged. 673 * @return A newly created Formattable* object, or nullptr on failure. The caller owns this and should 674 * delete it when done. 675 * @stable ICU 50 676 */ 677 U_I18N_API virtual void parseObject(const UnicodeString& source, 678 Formattable& result, 679 ParsePosition& parse_pos) const override; 680 681 /** 682 * ICU "poor man's RTTI", returns a UClassID for this class. 683 * @stable ICU 50 684 */ 685 U_I18N_API static UClassID getStaticClassID(); 686 687 /** 688 * ICU "poor man's RTTI", returns a UClassID for the actual class. 689 * @stable ICU 50 690 */ 691 U_I18N_API virtual UClassID getDynamicClassID() const override; 692 693 protected: 694 /** 695 * Constructs a TimeZoneFormat object for the specified locale. 696 * @param locale the locale 697 * @param status receives the status. 698 * @stable ICU 50 699 */ 700 U_I18N_API TimeZoneFormat(const Locale& locale, UErrorCode& status); 701 702 private: 703 /* Locale of this object */ 704 Locale fLocale; 705 706 /* Stores the region (could be implicit default) */ 707 char fTargetRegion[ULOC_COUNTRY_CAPACITY]; 708 709 /* TimeZoneNames object used by this formatter */ 710 TimeZoneNames* fTimeZoneNames; 711 712 /* TimeZoneGenericNames object used by this formatter - lazily instantiated */ 713 TimeZoneGenericNames* fTimeZoneGenericNames; 714 715 /* Localized GMT format pattern - e.g. "GMT{0}" */ 716 UnicodeString fGMTPattern; 717 718 /* Array of offset patterns used by Localized GMT format - e.g. "+HH:mm" */ 719 UnicodeString fGMTOffsetPatterns[UTZFMT_PAT_COUNT]; 720 721 /* Localized decimal digits used by Localized GMT format */ 722 UChar32 fGMTOffsetDigits[10]; 723 724 /* Localized GMT zero format - e.g. "GMT" */ 725 UnicodeString fGMTZeroFormat; 726 727 /* Bit flags representing parse options */ 728 uint32_t fDefParseOptionFlags; 729 730 /* Constant parts of GMT format pattern, populated from localized GMT format pattern*/ 731 UnicodeString fGMTPatternPrefix; /* Substring before {0} */ 732 UnicodeString fGMTPatternSuffix; /* Substring after {0} */ 733 734 /* Compiled offset patterns generated from fGMTOffsetPatterns[] */ 735 UVector* fGMTOffsetPatternItems[UTZFMT_PAT_COUNT]; 736 737 UBool fAbuttingOffsetHoursAndMinutes; 738 739 /* TZDBTimeZoneNames object used for parsing */ 740 TZDBTimeZoneNames* fTZDBTimeZoneNames; 741 742 /** 743 * Returns the time zone's specific format string. 744 * @param tz the time zone 745 * @param stdType the name type used for standard time 746 * @param dstType the name type used for daylight time 747 * @param date the date 748 * @param name receives the time zone's specific format name string 749 * @param timeType when null, actual time type is set 750 * @return a reference to name. 751 */ 752 UnicodeString& formatSpecific(const TimeZone& tz, UTimeZoneNameType stdType, UTimeZoneNameType dstType, 753 UDate date, UnicodeString& name, UTimeZoneFormatTimeType *timeType) const; 754 755 /** 756 * Returns the time zone's generic format string. 757 * @param tz the time zone 758 * @param genType the generic name type 759 * @param date the date 760 * @param name receives the time zone's generic format name string 761 * @return a reference to name. 762 */ 763 UnicodeString& formatGeneric(const TimeZone& tz, int32_t genType, UDate date, UnicodeString& name) const; 764 765 /** 766 * Lazily create a TimeZoneGenericNames instance 767 * @param status receives the status 768 * @return the cached TimeZoneGenericNames. 769 */ 770 const TimeZoneGenericNames* getTimeZoneGenericNames(UErrorCode& status) const; 771 772 /** 773 * Lazily create a TZDBTimeZoneNames instance 774 * @param status receives the status 775 * @return the cached TZDBTimeZoneNames. 776 */ 777 const TZDBTimeZoneNames* getTZDBTimeZoneNames(UErrorCode& status) const; 778 779 /** 780 * Private method returning the time zone's exemplar location string. 781 * This method will never return empty. 782 * @param tz the time zone 783 * @param name receives the time zone's exemplar location name 784 * @return a reference to name. 785 */ 786 UnicodeString& formatExemplarLocation(const TimeZone& tz, UnicodeString& name) const; 787 788 /** 789 * Private enum specifying a combination of offset fields 790 */ 791 enum OffsetFields { 792 FIELDS_H, 793 FIELDS_HM, 794 FIELDS_HMS 795 }; 796 797 /** 798 * Parses the localized GMT pattern string and initialize 799 * localized gmt pattern fields. 800 * @param gmtPattern the localized GMT pattern string such as "GMT {0}" 801 * @param status U_ILLEGAL_ARGUMENT_ERROR is set when the specified pattern does not 802 * contain an argument "{0}". 803 */ 804 void initGMTPattern(const UnicodeString& gmtPattern, UErrorCode& status); 805 806 /** 807 * Parse the GMT offset pattern into runtime optimized format. 808 * @param pattern the offset pattern string 809 * @param required the required set of fields, such as FIELDS_HM 810 * @param status U_ILLEGAL_ARGUMENT is set when the specified pattern does not contain 811 * pattern letters for the required fields. 812 * @return A list of GMTOffsetField objects, or nullptr on error. 813 */ 814 static UVector* parseOffsetPattern(const UnicodeString& pattern, OffsetFields required, UErrorCode& status); 815 816 /** 817 * Appends seconds field to the offset pattern with hour/minute 818 * Note: This code will be obsoleted once we add hour-minute-second pattern data in CLDR. 819 * @param offsetHM the offset pattern including hours and minutes fields 820 * @param result the output offset pattern including hour, minute and seconds fields 821 * @param status receives the status 822 * @return a reference to result 823 */ 824 static UnicodeString& expandOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status); 825 826 /** 827 * Truncates minutes field to the offset pattern with hour/minute 828 * Note: This code will be obsoleted once we add hour pattern data in CLDR. 829 * @param offsetHM the offset pattern including hours and minutes fields 830 * @param result the output offset pattern including only hours field 831 * @param status receives the status 832 * @return a reference to result 833 */ 834 static UnicodeString& truncateOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status); 835 836 /** 837 * Break input string into UChar32[]. Each array element represents 838 * a code point. This method is used for parsing localized digit 839 * characters and support characters in Unicode supplemental planes. 840 * @param str the string 841 * @param codeArray receives the result 842 * @param capacity the capacity of codeArray 843 * @return true when the specified code array is fully filled with code points 844 * (no under/overflow). 845 */ 846 static UBool toCodePoints(const UnicodeString& str, UChar32* codeArray, int32_t capacity); 847 848 /** 849 * Private method supprting all of ISO8601 formats 850 * @param offset the offset from GMT(UTC) in milliseconds. 851 * @param useUtcIndicator true if ISO 8601 UTC indicator "Z" is used when the offset is 0. 852 * @param isShort true if shortest form is used. 853 * @param ignoreSeconds true if non-zero offset seconds is appended. 854 * @param result Receives the result 855 * @param status Receives the status 856 * @return the ISO 8601 basic format. 857 */ 858 UnicodeString& formatOffsetISO8601(int32_t offset, UBool isBasic, UBool useUtcIndicator, 859 UBool isShort, UBool ignoreSeconds, UnicodeString& result, UErrorCode& status) const; 860 861 /** 862 * Private method used for localized GMT formatting. 863 * @param offset the zone's UTC offset 864 * @param isShort true if the short localized GMT format is desired. 865 * @param result receives the localized GMT format string 866 * @param status receives the status 867 */ 868 UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UBool isShort, UnicodeString& result, UErrorCode& status) const; 869 870 /** 871 * Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 style 872 * (extended format) time zone string. When the given string is not an ISO 8601 time 873 * zone string, this method sets the current position as the error index 874 * to <code>ParsePosition pos</code> and returns 0. 875 * @param text the text contains ISO 8601 style time zone string (e.g. "-08:00", "Z") 876 * at the position. 877 * @param pos the position, non-negative error index will be set on failure. 878 * @param extendedOnly true if parsing the text as ISO 8601 extended offset format (e.g. "-08:00"), 879 * or false to evaluate the text as basic format. 880 * @param hasDigitOffset receiving if the parsed zone string contains offset digits. 881 * @return the offset from GMT(UTC) in milliseconds for the given ISO 8601 style 882 * time zone string. 883 */ 884 int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos, UBool extendedOnly, 885 UBool* hasDigitOffset = nullptr) const; 886 887 /** 888 * Appends localized digits to the buffer. 889 * This code assumes that the input number is 0 - 59 890 * @param buf the target buffer 891 * @param n the integer number 892 * @param minDigits the minimum digits width 893 */ 894 void appendOffsetDigits(UnicodeString& buf, int32_t n, uint8_t minDigits) const; 895 896 /** 897 * Returns offset from GMT(UTC) in milliseconds for the given localized GMT 898 * offset format string. When the given string cannot be parsed, this method 899 * sets the current position as the error index to <code>ParsePosition pos</code> 900 * and returns 0. 901 * @param text the text contains a localized GMT offset string at the position. 902 * @param pos the position, non-negative error index will be set on failure. 903 * @param isShort true if this parser to try the short format first 904 * @param hasDigitOffset receiving if the parsed zone string contains offset digits. 905 * @return the offset from GMT(UTC) in milliseconds for the given localized GMT 906 * offset format string. 907 */ 908 int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos, 909 UBool isShort, UBool* hasDigitOffset) const; 910 911 /** 912 * Parse localized GMT format generated by the patter used by this formatter, except 913 * GMT Zero format. 914 * @param text the input text 915 * @param start the start index 916 * @param isShort true if the short localized format is parsed. 917 * @param parsedLen receives the parsed length 918 * @return the parsed offset in milliseconds 919 */ 920 int32_t parseOffsetLocalizedGMTPattern(const UnicodeString& text, int32_t start, 921 UBool isShort, int32_t& parsedLen) const; 922 923 /** 924 * Parses localized GMT offset fields into offset. 925 * @param text the input text 926 * @param start the start index 927 * @param isShort true if this is a short format - currently not used 928 * @param parsedLen the parsed length, or 0 on failure. 929 * @return the parsed offset in milliseconds. 930 */ 931 int32_t parseOffsetFields(const UnicodeString& text, int32_t start, UBool isShort, int32_t& parsedLen) const; 932 933 /** 934 * Parse localized GMT offset fields with the given pattern. 935 * @param text the input text 936 * @param start the start index 937 * @param pattenItems the pattern (already itemized) 938 * @param forceSingleHourDigit true if hours field is parsed as a single digit 939 * @param hour receives the hour offset field 940 * @param min receives the minute offset field 941 * @param sec receives the second offset field 942 * @return the parsed length 943 */ 944 int32_t parseOffsetFieldsWithPattern(const UnicodeString& text, int32_t start, 945 UVector* patternItems, UBool forceSingleHourDigit, int32_t& hour, int32_t& min, int32_t& sec) const; 946 947 /** 948 * Parses abutting localized GMT offset fields (such as 0800) into offset. 949 * @param text the input text 950 * @param start the start index 951 * @param parsedLen the parsed length, or 0 on failure 952 * @return the parsed offset in milliseconds. 953 */ 954 int32_t parseAbuttingOffsetFields(const UnicodeString& text, int32_t start, int32_t& parsedLen) const; 955 956 /** 957 * Parses the input text using the default format patterns (e.g. "UTC{0}"). 958 * @param text the input text 959 * @param start the start index 960 * @param parsedLen the parsed length, or 0 on failure 961 * @return the parsed offset in milliseconds. 962 */ 963 int32_t parseOffsetDefaultLocalizedGMT(const UnicodeString& text, int start, int32_t& parsedLen) const; 964 965 /** 966 * Parses the input GMT offset fields with the default offset pattern. 967 * @param text the input text 968 * @param start the start index 969 * @param separator the separator character, e.g. ':' 970 * @param parsedLen the parsed length, or 0 on failure. 971 * @return the parsed offset in milliseconds. 972 */ 973 int32_t parseDefaultOffsetFields(const UnicodeString& text, int32_t start, char16_t separator, 974 int32_t& parsedLen) const; 975 976 /** 977 * Reads an offset field value. This method will stop parsing when 978 * 1) number of digits reaches <code>maxDigits</code> 979 * 2) just before already parsed number exceeds <code>maxVal</code> 980 * 981 * @param text the text 982 * @param start the start offset 983 * @param minDigits the minimum number of required digits 984 * @param maxDigits the maximum number of digits 985 * @param minVal the minimum value 986 * @param maxVal the maximum value 987 * @param parsedLen the actual parsed length. 988 * @return the integer value parsed 989 */ 990 int32_t parseOffsetFieldWithLocalizedDigits(const UnicodeString& text, int32_t start, 991 uint8_t minDigits, uint8_t maxDigits, uint16_t minVal, uint16_t maxVal, int32_t& parsedLen) const; 992 993 /** 994 * Reads a single decimal digit, either localized digits used by this object 995 * or any Unicode numeric character. 996 * @param text the text 997 * @param start the start index 998 * @param len the actual length read from the text 999 * the start index is not a decimal number. 1000 * @return the integer value of the parsed digit, or -1 on failure. 1001 */ 1002 int32_t parseSingleLocalizedDigit(const UnicodeString& text, int32_t start, int32_t& len) const; 1003 1004 /** 1005 * Formats offset using ASCII digits. The input offset range must be 1006 * within +/-24 hours (exclusive). 1007 * @param offset The offset 1008 * @param sep The field separator character or 0 if not required 1009 * @param minFields The minimum fields 1010 * @param maxFields The maximum fields 1011 * @return The offset string 1012 */ 1013 static UnicodeString& formatOffsetWithAsciiDigits(int32_t offset, char16_t sep, 1014 OffsetFields minFields, OffsetFields maxFields, UnicodeString& result); 1015 1016 /** 1017 * Parses offset represented by contiguous ASCII digits. 1018 * <p> 1019 * Note: This method expects the input position is already at the start of 1020 * ASCII digits and does not parse sign (+/-). 1021 * @param text The text contains a sequence of ASCII digits 1022 * @param pos The parse position 1023 * @param minFields The minimum Fields to be parsed 1024 * @param maxFields The maximum Fields to be parsed 1025 * @param fixedHourWidth true if hours field must be width of 2 1026 * @return Parsed offset, 0 or positive number. 1027 */ 1028 static int32_t parseAbuttingAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, 1029 OffsetFields minFields, OffsetFields maxFields, UBool fixedHourWidth); 1030 1031 /** 1032 * Parses offset represented by ASCII digits and separators. 1033 * <p> 1034 * Note: This method expects the input position is already at the start of 1035 * ASCII digits and does not parse sign (+/-). 1036 * @param text The text 1037 * @param pos The parse position 1038 * @param sep The separator character 1039 * @param minFields The minimum Fields to be parsed 1040 * @param maxFields The maximum Fields to be parsed 1041 * @return Parsed offset, 0 or positive number. 1042 */ 1043 static int32_t parseAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, char16_t sep, 1044 OffsetFields minFields, OffsetFields maxFields); 1045 1046 /** 1047 * Unquotes the message format style pattern. 1048 * @param pattern the pattern 1049 * @param result receive the unquoted pattern. 1050 * @return A reference to result. 1051 */ 1052 static UnicodeString& unquote(const UnicodeString& pattern, UnicodeString& result); 1053 1054 /** 1055 * Initialize localized GMT format offset hour/min/sec patterns. 1056 * This method parses patterns into optimized run-time format. 1057 * @param status receives the status. 1058 */ 1059 void initGMTOffsetPatterns(UErrorCode& status); 1060 1061 /** 1062 * Check if there are any GMT format offset patterns without 1063 * any separators between hours field and minutes field and update 1064 * fAbuttingOffsetHoursAndMinutes field. This method must be called 1065 * after all patterns are parsed into pattern items. 1066 */ 1067 void checkAbuttingHoursAndMinutes(); 1068 1069 /** 1070 * Creates an instance of TimeZone for the given offset 1071 * @param offset the offset 1072 * @return A TimeZone with the given offset 1073 */ 1074 TimeZone* createTimeZoneForOffset(int32_t offset) const; 1075 1076 /** 1077 * Returns the time type for the given name type 1078 * @param nameType the name type 1079 * @return the time type (unknown/standard/daylight) 1080 */ 1081 static UTimeZoneFormatTimeType getTimeType(UTimeZoneNameType nameType); 1082 1083 /** 1084 * Returns the time zone ID of a match at the specified index within 1085 * the MatchInfoCollection. 1086 * @param matches the collection of matches 1087 * @param idx the index within matches 1088 * @param tzID receives the resolved time zone ID 1089 * @return a reference to tzID. 1090 */ 1091 UnicodeString& getTimeZoneID(const TimeZoneNames::MatchInfoCollection* matches, int32_t idx, UnicodeString& tzID) const; 1092 1093 1094 /** 1095 * Parse a zone ID. 1096 * @param text the text contains a time zone ID string at the position. 1097 * @param pos the position 1098 * @param tzID receives the zone ID 1099 * @return a reference to tzID 1100 */ 1101 UnicodeString& parseZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const; 1102 1103 /** 1104 * Parse a short zone ID. 1105 * @param text the text contains a short time zone ID string at the position. 1106 * @param pos the position 1107 * @param tzID receives the short zone ID 1108 * @return a reference to tzID 1109 */ 1110 UnicodeString& parseShortZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const; 1111 1112 /** 1113 * Parse an exemplar location string. 1114 * @param text the text contains an exemplar location string at the position. 1115 * @param pos the position. 1116 * @param tzID receives the time zone ID 1117 * @return a reference to tzID 1118 */ 1119 UnicodeString& parseExemplarLocation(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const; 1120 }; 1121 1122 U_NAMESPACE_END 1123 1124 #endif /* !UCONFIG_NO_FORMATTING */ 1125 1126 #endif /* U_SHOW_CPLUSPLUS_API */ 1127 1128 #endif