icuSources/i18n/unicode/tzfmt.h

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