icuSources/i18n/unicode/tzfmt.h

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