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