icuSources/i18n/unicode/tzfmt.h

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