1 /* 2 ******************************************************************************* 3 * Copyright (C) 2011-2012, 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 #ifndef U_HIDE_INTERNAL_API 19 20 #include "unicode/format.h" 21 #include "unicode/timezone.h" 22 #include "unicode/tznames.h" 23 24 U_CDECL_BEGIN 25 /** 26 * Constants for time zone display format style used by format/parse APIs 27 * in TimeZoneFormat. 28 * @draft ICU 50 29 */ 30 typedef enum UTimeZoneFormatStyle { 31 /** 32 * Generic location format, such as "United States Time (New York)", "Italy Time" 33 * @draft ICU 50 34 */ 35 UTZFMT_STYLE_GENERIC_LOCATION, 36 /** 37 * Generic long non-location format, such as "Eastern Time". 38 * @draft ICU 50 39 */ 40 UTZFMT_STYLE_GENERIC_LONG, 41 /** 42 * Generic short non-location format, such as "ET". 43 * @draft ICU 50 44 */ 45 UTZFMT_STYLE_GENERIC_SHORT, 46 /** 47 * Specific long format, such as "Eastern Standard Time". 48 * @draft ICU 50 49 */ 50 UTZFMT_STYLE_SPECIFIC_LONG, 51 /** 52 * Specific short format, such as "EST", "PDT". 53 * @draft ICU 50 54 */ 55 UTZFMT_STYLE_SPECIFIC_SHORT, 56 /** 57 * RFC822 format, such as "-0500" 58 * @draft ICU 50 59 */ 60 UTZFMT_STYLE_RFC822, 61 /** 62 * Localized GMT offset format, such as "GMT-05:00", "UTC+0100" 63 * @draft ICU 50 64 */ 65 UTZFMT_STYLE_LOCALIZED_GMT, 66 /** 67 * ISO 8601 format (extended), such as "-05:00", "Z"(UTC) 68 * @draft ICU 50 69 */ 70 UTZFMT_STYLE_ISO8601 71 } UTimeZoneFormatStyle; 72 73 /** 74 * Constants for GMT offset pattern types. 75 * @draft ICU 50 76 */ 77 typedef enum UTimeZoneFormatGMTOffsetPatternType { 78 /** 79 * Positive offset with hour and minute fields 80 * @draft ICU 50 81 */ 82 UTZFMT_PAT_POSITIVE_HM, 83 /** 84 * Positive offset with hour, minute and second fields 85 * @draft ICU 50 86 */ 87 UTZFMT_PAT_POSITIVE_HMS, 88 /** 89 * Negative offset with hour and minute fields 90 * @draft ICU 50 91 */ 92 UTZFMT_PAT_NEGATIVE_HM, 93 /** 94 * Negative offset with hour, minute and second fields 95 * @draft ICU 50 96 */ 97 UTZFMT_PAT_NEGATIVE_HMS 98 } UTimeZoneFormatGMTOffsetPatternType; 99 100 /** 101 * Constants for time types used by TimeZoneFormat APIs for 102 * receiving time type (standard time, daylight time or unknown). 103 * @draft ICU 50 104 */ 105 typedef enum UTimeZoneFormatTimeType { 106 /** 107 * Unknown 108 * @draft ICU 50 109 */ 110 UTZFMT_TIME_TYPE_UNKNOWN, 111 /** 112 * Standard time 113 * @draft ICU 50 114 */ 115 UTZFMT_TIME_TYPE_STANDARD, 116 /** 117 * Daylight saving time 118 * @draft ICU 50 119 */ 120 UTZFMT_TIME_TYPE_DAYLIGHT 121 } UTimeZoneFormatTimeType; 122 123 /** 124 * Constants for parse option flags, used for specifying optional parse behavior. 125 * @draft ICU 50 126 */ 127 typedef enum UTimeZoneFormatParseOption { 128 /** 129 * No option. 130 * @draft ICU 50 131 */ 132 UTZFMT_PARSE_OPTION_NONE = 0x00, 133 /** 134 * When a time zone display name is not found within a set of display names 135 * used for the specified style, look for the name from display names used 136 * by other styles. 137 * @draft ICU 50 138 */ 139 UTZFMT_PARSE_OPTION_ALL_STYLES = 0x01 140 } UTimeZoneFormatParseOption; 141 142 U_CDECL_END 143 144 U_NAMESPACE_BEGIN 145 146 class TimeZoneGenericNames; 147 class UVector; 148 149 /** 150 * <code>TimeZoneFormat</code> supports time zone display name formatting and parsing. 151 * An instance of TimeZoneFormat works as a subformatter of {@link SimpleDateFormat}, 152 * but you can also directly get a new instance of <code>TimeZoneFormat</code> and 153 * formatting/parsing time zone display names. 154 * <p> 155 * ICU implements the time zone display names defined by <a href="http://www.unicode.org/reports/tr35/">UTS#35 156 * Unicode Locale Data Markup Language (LDML)</a>. {@link TimeZoneNames} represents the 157 * time zone display name data model and this class implements the algorithm for actual 158 * formatting and parsing. 159 * 160 * @see SimpleDateFormat 161 * @see TimeZoneNames 162 * @draft ICU 50 163 */ 164 class U_I18N_API TimeZoneFormat : public Format { 165 public: 166 /** 167 * Copy constructor. 168 * @draft ICU 50 169 */ 170 TimeZoneFormat(const TimeZoneFormat& other); 171 172 /** 173 * Destructor. 174 * @draft ICU 50 175 */ 176 virtual ~TimeZoneFormat(); 177 178 /** 179 * Assignment operator. 180 * @draft ICU 50 181 */ 182 TimeZoneFormat& operator=(const TimeZoneFormat& other); 183 184 /** 185 * Return true if the given Format objects are semantically equal. 186 * Objects of different subclasses are considered unequal. 187 * @param other The object to be compared with. 188 * @return Return TRUE if the given Format objects are semantically equal. 189 * Objects of different subclasses are considered unequal. 190 * @draft ICU 50 191 */ 192 virtual UBool operator==(const Format& other) const; 193 194 /** 195 * Clone this object polymorphically. The caller is responsible 196 * for deleting the result when done. 197 * @return A copy of the object 198 * @draft ICU 50 199 */ 200 virtual Format* clone() const; 201 202 /** 203 * Creates an instance of <code>TimeZoneFormat</code> for the given locale. 204 * @param locale The locale. 205 * @param status Recevies the status. 206 * @return An instance of <code>TimeZoneFormat</code> for the given locale, 207 * owned by the caller. 208 * @draft ICU 50 209 */ 210 static TimeZoneFormat* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status); 211 212 /** 213 * Returns the time zone display name data used by this instance. 214 * @return The time zone display name data. 215 * @draft ICU 50 216 */ 217 const TimeZoneNames* getTimeZoneNames() const; 218 219 /** 220 * Sets the time zone display name data to this format instnace. 221 * The caller should not delete the TimeZoenNames object after it is adopted 222 * by this call. 223 * @param tznames TimeZoneNames object to be adopted. 224 * @draft ICU 50 225 */ 226 void adoptTimeZoneNames(TimeZoneNames *tznames); 227 228 /** 229 * Sets the time zone display name data to this format instnace. 230 * @param tznames TimeZoneNames object to be set. 231 * @draft ICU 50 232 */ 233 void setTimeZoneNames(const TimeZoneNames &tznames); 234 235 /** 236 * Returns the localized GMT format pattern. 237 * @param pattern Receives the localized GMT format pattern. 238 * @return A reference to the result pattern. 239 * @see #setGMTPattern 240 * @draft ICU 50 241 */ 242 UnicodeString& getGMTPattern(UnicodeString& pattern) const; 243 244 /** 245 * Sets the localized GMT format pattern. The pattern must contain 246 * a single argument {0}, for example "GMT {0}". 247 * @param pattern The localized GMT format pattern to be used by this object. 248 * @param status Recieves the status. 249 * @see #getGMTPattern 250 * @draft ICU 50 251 */ 252 void setGMTPattern(const UnicodeString& pattern, UErrorCode& status); 253 254 /** 255 * Returns the offset pattern used for localized GMT format. 256 * @param type The offset pattern type enum. 257 * @param pattern Receives the offset pattern. 258 * @return A reference to the result pattern. 259 * @see #setGMTOffsetPattern 260 * @draft ICU 50 261 */ 262 UnicodeString& getGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, UnicodeString& pattern) const; 263 264 /** 265 * Sets the offset pattern for the given offset type. 266 * @param type The offset pattern type enum. 267 * @param pattern The offset pattern used for localized GMT format for the type. 268 * @param status Receives the status. 269 * @see #getGMTOffsetPattern 270 * @draft ICU 50 271 */ 272 void setGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, const UnicodeString& pattern, UErrorCode& status); 273 274 /** 275 * Returns the decimal digit characters used for localized GMT format. 276 * The return string contains exactly 10 code points (may include Unicode 277 * supplementary character) representing digit 0 to digit 9 in the ascending 278 * order. 279 * @param digits Receives the decimal digits used for localized GMT format. 280 * @see #setGMTOffsetDigits 281 * @draft ICU 50 282 */ 283 UnicodeString& getGMTOffsetDigits(UnicodeString& digits) const; 284 285 /** 286 * Sets the decimal digit characters used for localized GMT format. 287 * The input <code>digits</code> must contain exactly 10 code points 288 * (Unicode supplementary characters are also allowed) representing 289 * digit 0 to digit 9 in the ascending order. When the input <code>digits</code> 290 * does not satisfy the condition, <code>U_ILLEGAL_ARGUMENT_ERROR</code> 291 * will be set to the return status. 292 * @param digits The decimal digits used for localized GMT format. 293 * @param status Receives the status. 294 * @see #getGMTOffsetDigits 295 * @draft ICU 50 296 */ 297 void setGMTOffsetDigits(const UnicodeString& digits, UErrorCode& status); 298 299 /** 300 * Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0). 301 * @param gmtZeroFormat Receives the localized GMT string string for GMT(UTC) itself. 302 * @return A reference to the result GMT string. 303 * @see #setGMTZeroFormat 304 * @draft ICU 50 305 */ 306 UnicodeString& getGMTZeroFormat(UnicodeString& gmtZeroFormat) const; 307 308 /** 309 * Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0). 310 * @param gmtZeroFormat The localized GMT format string for GMT(UTC). 311 * @param status Receives the status. 312 * @see #getGMTZeroFormat 313 * @draft ICU 50 314 */ 315 void setGMTZeroFormat(const UnicodeString& gmtZeroFormat, UErrorCode& status); 316 317 /** 318 * Returns the bitwise flags of UTimeZoneFormatParseOption representing the default parse 319 * options used by this object. 320 * @return the default parse options. 321 * @see ParseOption 322 * @draft ICU 50 323 */ 324 uint32_t getDefaultParseOptions(void) const; 325 326 /** 327 * Sets the default parse options. 328 * <p><b>Note</b>: By default, an instance of <code>TimeZoneFormat</code> 329 * created by {@link #createInstance} has no parse options set (UTZFMT_PARSE_OPTION_NONE). 330 * To specify multipe options, use bitwise flags of UTimeZoneFormatParseOption. 331 * @see #UTimeZoneFormatParseOption 332 * @draft ICU 50 333 */ 334 void setDefaultParseOptions(uint32_t flags); 335 336 /** 337 * Returns the RFC822 style time zone string for the given offset. 338 * For example, "-0800". 339 * @param offset The offset from GMT(UTC) in milliseconds. 340 * @param result Recevies the RFC822 style GMT(UTC) offset format. 341 * @return A reference to the result. 342 * @param status Receives the status 343 * @see #parseOffsetRFC822 344 * @draft ICU 50 345 */ 346 UnicodeString& formatOffsetRFC822(int32_t offset, UnicodeString& result, UErrorCode& status) const; 347 348 /** 349 * Returns the ISO 8601 style time zone string for the given offset. 350 * For example, "-08:00" and "Z". 351 * @param offset The offset from GMT(UTC) in milliseconds. 352 * @param result Receives the ISO 8601 style GMT(UTC) offset format. 353 * @param status Receives the status 354 * @return A reference to the result. 355 * @see #parseOffsetISO8601 356 * @draft ICU 50 357 */ 358 UnicodeString& formatOffsetISO8601(int32_t offset, UnicodeString& result, UErrorCode& status) const; 359 360 /** 361 * Returns the localized GMT(UTC) offset format for the given offset. 362 * The localized GMT offset is defined by; 363 * <ul> 364 * <li>GMT format pattern (e.g. "GMT {0}" - see {@link #getGMTPattern}) 365 * <li>Offset time pattern (e.g. "+HH:mm" - see {@link #getGMTOffsetPattern}) 366 * <li>Offset digits (e.g. "0123456789" - see {@link #getGMTOffsetDigits}) 367 * <li>GMT zero format (e.g. "GMT" - see {@link #getGMTZeroFormat}) 368 * </ul> 369 * @param offset the offset from GMT(UTC) in milliseconds. 370 * @param status Receives the status 371 * @param result Receives the localized GMT format string. 372 * @return A reference to the result. 373 * @see #parseOffsetLocalizedGMT 374 * @draft ICU 50 375 */ 376 UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const; 377 378 using Format::format; 379 380 /** 381 * Returns the display name of the time zone at the given date for the style. 382 * @param style The style (e.g. <code>UTZFMT_STYLE_GENERIC_LONG</code>, <code>UTZFMT_STYLE_LOCALIZED_GMT</code>...) 383 * @param tz The time zone. 384 * @param date The date. 385 * @param name Receives the display name. 386 * @param timeType the output argument for receiving the time type (standard/daylight/unknown) 387 * used for the display name, or NULL if the information is not necessary. 388 * @return A reference to the result 389 * @see #UTimeZoneFormatStyle 390 * @see #UTimeZoneFormatTimeType 391 * @draft ICU 50 392 */ 393 virtual UnicodeString& format(UTimeZoneFormatStyle style, const TimeZone& tz, UDate date, 394 UnicodeString& name, UTimeZoneFormatTimeType* timeType = NULL) const; 395 396 /** 397 * Returns offset from GMT(UTC) in milliseconds for the given RFC822 398 * style time zone string. When the given string is not an RFC822 time zone 399 * string, this method sets the current position as the error index 400 * to <code>ParsePosition pos</code> and returns 0. 401 * @param text The text contains RFC822 style time zone string (e.g. "-0800") 402 * at the position. 403 * @param pos The ParsePosition object. 404 * @return The offset from GMT(UTC) in milliseconds for the given RFC822 style 405 * time zone string. 406 * @see #formatOffsetRFC822 407 * @draft ICU 50 408 */ 409 int32_t parseOffsetRFC822(const UnicodeString& text, ParsePosition& pos) const; 410 411 /** 412 * Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 413 * style time zone string. When the given string is not an ISO 8601 time zone 414 * string, this method sets the current position as the error index 415 * to <code>ParsePosition pos</code> and returns 0. 416 * @param text The text contains ISO8601 style time zone string (e.g. "-08:00", "Z") 417 * at the position. 418 * @param pos The ParsePosition object. 419 * @return The offset from GMT(UTC) in milliseconds for the given ISO 8601 style 420 * time zone string. 421 * @see #formatOffsetISO8601 422 * @draft ICU 50 423 */ 424 int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos) const; 425 426 /** 427 * Returns offset from GMT(UTC) in milliseconds for the given localized GMT 428 * offset format string. When the given string cannot be parsed, this method 429 * sets the current position as the error index to <code>ParsePosition pos</code> 430 * and returns 0. 431 * @param text The text contains a localized GMT offset string at the position. 432 * @param pos The ParsePosition object. 433 * @return The offset from GMT(UTC) in milliseconds for the given localized GMT 434 * offset format string. 435 * @see #formatOffsetLocalizedGMT 436 * @draft ICU 50 437 */ 438 int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const; 439 440 /** 441 * Returns a <code>TimeZone</code> by parsing the time zone string according to 442 * the given parse position, the specified format style and parse options. 443 * 444 * @param text The text contains a time zone string at the position. 445 * @param style The format style 446 * @param pos The position. 447 * @param parseOptions The parse options repesented by bitwise flags of UTimeZoneFormatParseOption. 448 * @param timeType The output argument for receiving the time type (standard/daylight/unknown), 449 * or NULL if the information is not necessary. 450 * @return A <code>TimeZone</code>, or null if the input could not be parsed. 451 * @see UTimeZoneFormatStyle 452 * @see UTimeZoneFormatParseOption 453 * @see UTimeZoneFormatTimeType 454 * @draft ICU 50 455 */ 456 virtual TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos, 457 int32_t parseOptions, UTimeZoneFormatTimeType* timeType = NULL) const; 458 459 /** 460 * Returns a <code>TimeZone</code> by parsing the time zone string according to 461 * the given parse position, the specified format style and the default parse options. 462 * 463 * @param text The text contains a time zone string at the position. 464 * @param style The format style 465 * @param pos The position. 466 * @param timeType The output argument for receiving the time type (standard/daylight/unknown), 467 * or NULL if the information is not necessary. 468 * @return A <code>TimeZone</code>, or null if the input could not be parsed. 469 * @see UTimeZoneFormatStyle 470 * @see UTimeZoneFormatParseOption 471 * @see UTimeZoneFormatTimeType 472 * @draft ICU 50 473 */ 474 TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos, 475 UTimeZoneFormatTimeType* timeType = NULL) const; 476 477 /* ---------------------------------------------- 478 * Format APIs 479 * ---------------------------------------------- */ 480 481 /** 482 * Format an object to produce a time zone display string using localized GMT offset format. 483 * This method handles Formattable objects with a <code>TimeZone</code>. If a the Formattable 484 * object type is not a <code>TimeZone</code>, then it returns a failing UErrorCode. 485 * @param obj The object to format. Must be a <code>TimeZone</code>. 486 * @param appendTo Output parameter to receive result. Result is appended to existing contents. 487 * @param pos On input: an alignment field, if desired. On output: the offsets of the alignment field. 488 * @param status Output param filled with success/failure status. 489 * @return Reference to 'appendTo' parameter. 490 * @draft ICU 50 491 */ 492 virtual UnicodeString& format(const Formattable& obj, UnicodeString& appendTo, 493 FieldPosition& pos, UErrorCode& status) const; 494 495 /** 496 * Parse a string to produce an object. This methods handles parsing of 497 * time zone display strings into Formattable objects with <code>TimeZone</code>. 498 * @param source The string to be parsed into an object. 499 * @param result Formattable to be set to the parse result. If parse fails, return contents are undefined. 500 * @param parse_pos The position to start parsing at. Upon return this param is set to the position after the 501 * last character successfully parsed. If the source is not parsed successfully, this param 502 * will remain unchanged. 503 * @return A newly created Formattable* object, or NULL on failure. The caller owns this and should 504 * delete it when done. 505 * @draft ICU 50 506 */ 507 virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const; 508 509 /** 510 * ICU "poor man's RTTI", returns a UClassID for this class. 511 * @draft ICU 50 512 */ 513 static UClassID U_EXPORT2 getStaticClassID(void); 514 515 /** 516 * ICU "poor man's RTTI", returns a UClassID for the actual class. 517 * @draft ICU 50 518 */ 519 virtual UClassID getDynamicClassID() const; 520 521 protected: 522 /** 523 * Constructs a TimeZoneFormat object for the specified locale. 524 * @param locale the locale 525 * @param status receives the status. 526 * @draft ICU 50 527 */ 528 TimeZoneFormat(const Locale& locale, UErrorCode& status); 529 530 private: 531 /* Locale of this object */ 532 Locale fLocale; 533 534 /* Stores the region (could be implicit default) */ 535 char fTargetRegion[ULOC_COUNTRY_CAPACITY]; 536 537 /* TimeZoneNames object used by this formatter */ 538 TimeZoneNames* fTimeZoneNames; 539 540 /* TimeZoneGenericNames object used by this formatter - lazily instantiated */ 541 TimeZoneGenericNames* fTimeZoneGenericNames; 542 543 /* Localized GMT format pattern - e.g. "GMT{0}" */ 544 UnicodeString fGMTPattern; 545 546 /* Array of offset patterns used by Localized GMT format - e.g. "+HH:mm" */ 547 UnicodeString fGMTOffsetPatterns[UTZFMT_PAT_NEGATIVE_HMS + 1]; 548 549 /* Localized decimal digits used by Localized GMT format */ 550 UChar32 fGMTOffsetDigits[10]; 551 552 /* Localized GMT zero format - e.g. "GMT" */ 553 UnicodeString fGMTZeroFormat; 554 555 /* Bit flags representing parse options */ 556 uint32_t fDefParseOptionFlags; 557 558 /* Constant parts of GMT format pattern, populated from localized GMT format pattern*/ 559 UnicodeString fGMTPatternPrefix; /* Substring before {0} */ 560 UnicodeString fGMTPatternSuffix; /* Substring after {0} */ 561 562 /* Compiled offset patterns generated from fGMTOffsetPatterns[] */ 563 UVector* fGMTOffsetPatternItems[UTZFMT_PAT_NEGATIVE_HMS + 1]; 564 565 /** 566 * Returns the time zone's specific format string. 567 * @param tz the time zone 568 * @param stdType the name type used for standard time 569 * @param dstType the name type used for daylight time 570 * @param date the date 571 * @param name receives the time zone's specific format name string 572 * @param timeType when null, actual time type is set 573 * @return a reference to name. 574 */ 575 UnicodeString& formatSpecific(const TimeZone& tz, UTimeZoneNameType stdType, UTimeZoneNameType dstType, 576 UDate date, UnicodeString& name, UTimeZoneFormatTimeType *timeType) const; 577 578 /** 579 * Returns the time zone's generic format string. 580 * @param tz the time zone 581 * @param genType the generic name type 582 * @param date the date 583 * @param name receives the time zone's generic format name string 584 * @return a reference to name. 585 */ 586 UnicodeString& formatGeneric(const TimeZone& tz, int32_t genType, UDate date, UnicodeString& name) const; 587 588 /** 589 * Lazily create a TimeZoneGenericNames instance 590 * @param status receives the status 591 * @return the cached TimeZoneGenericNames. 592 */ 593 const TimeZoneGenericNames* getTimeZoneGenericNames(UErrorCode& status) const; 594 595 /** 596 * Private enum specifying a combination of offset fields 597 */ 598 enum OffsetFields { 599 FIELDS_H, 600 FIELDS_HM, 601 FIELDS_HMS 602 }; 603 604 /** 605 * Parses the localized GMT pattern string and initialize 606 * localized gmt pattern fields. 607 * @param gmtPattern the localized GMT pattern string such as "GMT {0}" 608 * @param status U_ILLEGAL_ARGUMENT_ERROR is set when the specified pattern does not 609 * contain an argument "{0}". 610 */ 611 void initGMTPattern(const UnicodeString& gmtPattern, UErrorCode& status); 612 613 /** 614 * Parse the GMT offset pattern into runtime optimized format. 615 * @param pattern the offset pattern string 616 * @param required the required set of fields, such as FIELDS_HM 617 * @param status U_ILLEGAL_ARGUMENT is set when the specified pattern does not contain 618 * pattern letters for the required fields. 619 * @return A list of GMTOffsetField objects, or NULL on error. 620 */ 621 static UVector* parseOffsetPattern(const UnicodeString& pattern, OffsetFields required, UErrorCode& status); 622 623 /** 624 * Appends second field to the offset pattern with hour/minute 625 * Note: This code will be obsoleted once we add hour-minute-second pattern data in CLDR. 626 * @param offsetHM the offset pattern including hour and minute fields 627 * @param result the output offset pattern including hour, minute and second fields 628 * @return a reference to result 629 */ 630 static UnicodeString& expandOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result); 631 632 /** 633 * Break input string into UChar32[]. Each array element represents 634 * a code point. This method is used for parsing localized digit 635 * characters and support characters in Unicode supplemental planes. 636 * @param str the string 637 * @param codeArray receives the result 638 * @param capacity the capacity of codeArray 639 * @return TRUE when the specified code array is fully filled with code points 640 * (no under/overflow). 641 */ 642 static UBool toCodePoints(const UnicodeString& str, UChar32* codeArray, int32_t capacity); 643 644 /** 645 * Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 style 646 * (extended format) time zone string. When the given string is not an ISO 8601 time 647 * zone string, this method sets the current position as the error index 648 * to <code>ParsePosition pos</code> and returns 0. 649 * @param text the text contains ISO 8601 style time zone string (e.g. "-08:00", "Z") 650 * at the position. 651 * @param pos the position, non-negative error index will be set on failure. 652 * @param extendedOnly TRUE if parsing the text as ISO 8601 extended offset format (e.g. "-08:00"), 653 * or FALSE to evaluate the text as basic format. 654 * @param hasDigitOffset receiving if the parsed zone string contains offset digits. 655 * @return the offset from GMT(UTC) in milliseconds for the given ISO 8601 style 656 * time zone string. 657 */ 658 int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos, UBool extendedOnly, 659 UBool* hasDigitOffset = NULL) const; 660 661 /** 662 * Appends localized digits to the buffer. 663 * This code assumes that the input number is 0 - 59 664 * @param buf the target buffer 665 * @param n the integer number 666 * @param minDigits the minimum digits width 667 */ 668 void appendOffsetDigits(UnicodeString& buf, int32_t n, uint8_t minDigits) const; 669 670 /** 671 * Returns offset from GMT(UTC) in milliseconds for the given localized GMT 672 * offset format string. When the given string cannot be parsed, this method 673 * sets the current position as the error index to <code>ParsePosition pos</code> 674 * and returns 0. 675 * @param text the text contains a localized GMT offset string at the position. 676 * @param pos the position, non-negative error index will be set on failure. 677 * @param hasDigitOffset receiving if the parsed zone string contains offset digits. 678 * @return the offset from GMT(UTC) in milliseconds for the given localized GMT 679 * offset format string. 680 */ 681 int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos, 682 UBool* hasDigitOffset) const; 683 684 /** 685 * Parses localized GMT offset fields into offset. 686 * @param text the input text 687 * @param start the start index 688 * @param minimumHourWidth true if the parser allows hour field width to be 1 689 * @param parsedLen the parsed length, or 0 on failure. 690 * @return the parsed offset in milliseconds. 691 */ 692 int32_t parseOffsetFields(const UnicodeString& text, int32_t start, UBool minimumHourWidth, 693 int32_t& parsedLen) const; 694 695 /** 696 * Parses abutting localized GMT offset fields (such as 0800) into offset. 697 * @param text the input text 698 * @param start the start index 699 * @param parsedLen the parsed length, or 0 on failure 700 * @return the parsed offset in milliseconds. 701 */ 702 int32_t parseAbuttingOffsetFields(const UnicodeString& text, int32_t start, int32_t& parsedLen) const; 703 704 /** 705 * Parses the input text using the default format patterns (e.g. "UTC{0}"). 706 * @param text the input text 707 * @param start the start index 708 * @param parsedLen the parsed length, or 0 on failure 709 * @return the parsed offset in milliseconds. 710 */ 711 int32_t parseOffsetDefaultLocalizedGMT(const UnicodeString& text, int start, int32_t& parsedLen) const; 712 713 /** 714 * Parses the input GMT offset fields with the default offset pattern. 715 * @param text the input text 716 * @param start the start index 717 * @param separator the separator character, e.g. ':' 718 * @param parsedLen the parsed length, or 0 on failure. 719 * @return the parsed offset in milliseconds. 720 */ 721 int32_t parseDefaultOffsetFields(const UnicodeString& text, int32_t start, UChar separator, 722 int32_t& parsedLen) const; 723 724 /** 725 * Reads an offset field value. This method will stop parsing when 726 * 1) number of digits reaches <code>maxDigits</code> 727 * 2) just before already parsed number exceeds <code>maxVal</code> 728 * 729 * @param text the text 730 * @param start the start offset 731 * @param minDigits the minimum number of required digits 732 * @param maxDigits the maximum number of digits 733 * @param minVal the minimum value 734 * @param maxVal the maximum value 735 * @param parsedLen the actual parsed length. 736 * @return the integer value parsed 737 */ 738 int32_t parseOffsetFieldWithLocalizedDigits(const UnicodeString& text, int32_t start, 739 uint8_t minDigits, uint8_t maxDigits, uint16_t minVal, uint16_t maxVal, int32_t& parsedLen) const; 740 741 /** 742 * Reads a single decimal digit, either localized digits used by this object 743 * or any Unicode numeric character. 744 * @param text the text 745 * @param start the start index 746 * @param len the actual length read from the text 747 * the start index is not a decimal number. 748 * @return the integer value of the parsed digit, or -1 on failure. 749 */ 750 int32_t parseSingleLocalizedDigit(const UnicodeString& text, int32_t start, int32_t& len) const; 751 752 /** 753 * Formats offset using ASCII digits. The input offset range must be 754 * within +/-24 hours (exclusive). 755 * @param offset The offset 756 * @param sep The field separator character or 0 if not required 757 * @param minFields The minimum fields 758 * @param maxFields The maximum fields 759 * @return The offset string 760 */ 761 static UnicodeString& formatOffsetWithAsciiDigits(int32_t offset, UChar sep, 762 OffsetFields minFields, OffsetFields maxFields, UnicodeString& result); 763 764 /** 765 * Parses offset represented by contiguous ASCII digits. 766 * <p> 767 * Note: This method expects the input position is already at the start of 768 * ASCII digits and does not parse sign (+/-). 769 * @param text The text contains a sequence of ASCII digits 770 * @param pos The parse position 771 * @param minFields The minimum Fields to be parsed 772 * @param maxFields The maximum Fields to be parsed 773 * @param fixedHourWidth true if hour field must be width of 2 774 * @return Parsed offset, 0 or positive number. 775 */ 776 static int32_t parseAbuttingAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, 777 OffsetFields minFields, OffsetFields maxFields, UBool fixedHourWidth); 778 779 /** 780 * Parses offset represented by ASCII digits and separators. 781 * <p> 782 * Note: This method expects the input position is already at the start of 783 * ASCII digits and does not parse sign (+/-). 784 * @param text The text 785 * @param pos The parse position 786 * @param sep The separator character 787 * @param minFields The minimum Fields to be parsed 788 * @param maxFields The maximum Fields to be parsed 789 * @param fixedHourWidth true if hour field must be width of 2 790 * @return Parsed offset, 0 or positive number. 791 */ 792 static int32_t parseAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, UChar sep, 793 OffsetFields minFields, OffsetFields maxFields, UBool fixedHourWidth); 794 795 /** 796 * Unquotes the message format style pattern. 797 * @param pattern the pattern 798 * @param result receive the unquoted pattern. 799 * @return A reference to result. 800 */ 801 static UnicodeString& unquote(const UnicodeString& pattern, UnicodeString& result); 802 803 /** 804 * Initialize localized GMT format offset hour/min/sec patterns. 805 * This method parses patterns into optimized run-time format. 806 * @param status receives the status. 807 */ 808 void initGMTOffsetPatterns(UErrorCode& status); 809 810 /** 811 * Creates an instance of TimeZone for the given offset 812 * @param offset the offset 813 * @return A TimeZone with the given offset 814 */ 815 TimeZone* createTimeZoneForOffset(int32_t offset) const; 816 817 /** 818 * Returns the time type for the given name type 819 * @param nameType the name type 820 * @return the time type (unknown/standard/daylight) 821 */ 822 static UTimeZoneFormatTimeType getTimeType(UTimeZoneNameType nameType); 823 824 /* 825 * Returns the time zone ID of a match at the specified index within 826 * the MatchInfoCollection. 827 * @param matches the collection of matches 828 * @param idx the index withing matches 829 * @param tzID receives the resolved time zone ID 830 * @return a reference to tzID. 831 */ 832 UnicodeString& getTimeZoneID(const TimeZoneNames::MatchInfoCollection* matches, int32_t idx, UnicodeString& tzID) const; 833 }; 834 835 U_NAMESPACE_END 836 837 #endif /* U_HIDE_INTERNAL_API */ 838 #endif 839 #endif 840 841
