Where Online Learning is simpler!
The C and C++ Include Header Files
/usr/include/unicode/tzfmt.h
$ cat -n /usr/include/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 bool operator==(const Format& other) const override; 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 override; 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 instance. 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 instance. 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 Receives 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 multiple 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 nullptr 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 = nullptr) 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 represented by bitwise flags of UTimeZoneFormatParseOption. 594 * @param timeType The output argument for receiving the time type (standard/daylight/unknown), 595 * or nullptr 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 = nullptr) 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 nullptr 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 = nullptr) 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 override; 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 nullptr 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 override; 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 override; 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 nullptr 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 = nullptr) 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 within 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
Contact us
|
About us
|
Term of use
|
Copyright © 2000-2025 MyWebUniversity.com ™
