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