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