1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 *******************************************************************************
5 * Copyright (C) 2011-2015, International Business Machines Corporation and
6 * others. All Rights Reserved.
7 *******************************************************************************
14 * \brief C++ API: TimeZoneFormat
17 #include "unicode/utypes.h"
19 #if !UCONFIG_NO_FORMATTING
21 #include "unicode/format.h"
22 #include "unicode/timezone.h"
23 #include "unicode/tznames.h"
27 * Constants for time zone display format style used by format/parse APIs
31 typedef enum UTimeZoneFormatStyle {
33 * Generic location format, such as "United States Time (New York)", "Italy Time"
36 UTZFMT_STYLE_GENERIC_LOCATION,
38 * Generic long non-location format, such as "Eastern Time".
41 UTZFMT_STYLE_GENERIC_LONG,
43 * Generic short non-location format, such as "ET".
46 UTZFMT_STYLE_GENERIC_SHORT,
48 * Specific long format, such as "Eastern Standard Time".
51 UTZFMT_STYLE_SPECIFIC_LONG,
53 * Specific short format, such as "EST", "PDT".
56 UTZFMT_STYLE_SPECIFIC_SHORT,
58 * Localized GMT offset format, such as "GMT-05:00", "UTC+0100"
61 UTZFMT_STYLE_LOCALIZED_GMT,
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".
67 UTZFMT_STYLE_LOCALIZED_GMT_SHORT,
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".
74 UTZFMT_STYLE_ISO_BASIC_SHORT,
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".
81 UTZFMT_STYLE_ISO_BASIC_LOCAL_SHORT,
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".
88 UTZFMT_STYLE_ISO_BASIC_FIXED,
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".
95 UTZFMT_STYLE_ISO_BASIC_LOCAL_FIXED,
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".
102 UTZFMT_STYLE_ISO_BASIC_FULL,
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".
109 UTZFMT_STYLE_ISO_BASIC_LOCAL_FULL,
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".
116 UTZFMT_STYLE_ISO_EXTENDED_FIXED,
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".
123 UTZFMT_STYLE_ISO_EXTENDED_LOCAL_FIXED,
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".
130 UTZFMT_STYLE_ISO_EXTENDED_FULL,
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".
137 UTZFMT_STYLE_ISO_EXTENDED_LOCAL_FULL,
139 * Time Zone ID, such as "America/Los_Angeles".
142 UTZFMT_STYLE_ZONE_ID,
144 * Short Time Zone ID (BCP 47 Unicode location extension, time zone type value), such as "uslax".
147 UTZFMT_STYLE_ZONE_ID_SHORT,
149 * Exemplar location, such as "Los Angeles" and "Paris".
152 UTZFMT_STYLE_EXEMPLAR_LOCATION
153 } UTimeZoneFormatStyle;
156 * Constants for GMT offset pattern types.
159 typedef enum UTimeZoneFormatGMTOffsetPatternType {
161 * Positive offset with hours and minutes fields
164 UTZFMT_PAT_POSITIVE_HM,
166 * Positive offset with hours, minutes and seconds fields
169 UTZFMT_PAT_POSITIVE_HMS,
171 * Negative offset with hours and minutes fields
174 UTZFMT_PAT_NEGATIVE_HM,
176 * Negative offset with hours, minutes and seconds fields
179 UTZFMT_PAT_NEGATIVE_HMS,
181 * Positive offset with hours field
184 UTZFMT_PAT_POSITIVE_H,
186 * Negative offset with hours field
189 UTZFMT_PAT_NEGATIVE_H,
191 /* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed for other .h declarations */
193 * Number of UTimeZoneFormatGMTOffsetPatternType types.
197 } UTimeZoneFormatGMTOffsetPatternType;
200 * Constants for time types used by TimeZoneFormat APIs for
201 * receiving time type (standard time, daylight time or unknown).
204 typedef enum UTimeZoneFormatTimeType {
209 UTZFMT_TIME_TYPE_UNKNOWN,
214 UTZFMT_TIME_TYPE_STANDARD,
216 * Daylight saving time
219 UTZFMT_TIME_TYPE_DAYLIGHT
220 } UTimeZoneFormatTimeType;
223 * Constants for parse option flags, used for specifying optional parse behavior.
226 typedef enum UTimeZoneFormatParseOption {
231 UTZFMT_PARSE_OPTION_NONE = 0x00,
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
238 UTZFMT_PARSE_OPTION_ALL_STYLES = 0x01,
240 * When parsing a time zone display name in UTZFMT_STYLE_SPECIFIC_SHORT,
241 * look for the IANA tz database compatible zone abbreviations in addition
242 * to the localized names coming from the {@link TimeZoneNames} currently
243 * used by the {@link TimeZoneFormat}.
246 UTZFMT_PARSE_OPTION_TZ_DATABASE_ABBREVIATIONS = 0x02
247 } UTimeZoneFormatParseOption;
253 class TimeZoneGenericNames;
254 class TZDBTimeZoneNames;
258 * <code>TimeZoneFormat</code> supports time zone display name formatting and parsing.
259 * An instance of TimeZoneFormat works as a subformatter of {@link SimpleDateFormat},
260 * but you can also directly get a new instance of <code>TimeZoneFormat</code> and
261 * formatting/parsing time zone display names.
263 * ICU implements the time zone display names defined by <a href="http://www.unicode.org/reports/tr35/">UTS#35
264 * Unicode Locale Data Markup Language (LDML)</a>. {@link TimeZoneNames} represents the
265 * time zone display name data model and this class implements the algorithm for actual
266 * formatting and parsing.
268 * @see SimpleDateFormat
272 class U_I18N_API TimeZoneFormat : public Format {
278 TimeZoneFormat(const TimeZoneFormat& other);
284 virtual ~TimeZoneFormat();
287 * Assignment operator.
290 TimeZoneFormat& operator=(const TimeZoneFormat& other);
293 * Return true if the given Format objects are semantically equal.
294 * Objects of different subclasses are considered unequal.
295 * @param other The object to be compared with.
296 * @return Return TRUE if the given Format objects are semantically equal.
297 * Objects of different subclasses are considered unequal.
300 virtual UBool operator==(const Format& other) const;
303 * Clone this object polymorphically. The caller is responsible
304 * for deleting the result when done.
305 * @return A copy of the object
308 virtual Format* clone() const;
311 * Creates an instance of <code>TimeZoneFormat</code> for the given locale.
312 * @param locale The locale.
313 * @param status Receives the status.
314 * @return An instance of <code>TimeZoneFormat</code> for the given locale,
315 * owned by the caller.
318 static TimeZoneFormat* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
321 * Returns the time zone display name data used by this instance.
322 * @return The time zone display name data.
325 const TimeZoneNames* getTimeZoneNames() const;
328 * Sets the time zone display name data to this format instnace.
329 * The caller should not delete the TimeZoenNames object after it is adopted
331 * @param tznames TimeZoneNames object to be adopted.
334 void adoptTimeZoneNames(TimeZoneNames *tznames);
337 * Sets the time zone display name data to this format instnace.
338 * @param tznames TimeZoneNames object to be set.
341 void setTimeZoneNames(const TimeZoneNames &tznames);
344 * Returns the localized GMT format pattern.
345 * @param pattern Receives the localized GMT format pattern.
346 * @return A reference to the result pattern.
347 * @see #setGMTPattern
350 UnicodeString& getGMTPattern(UnicodeString& pattern) const;
353 * Sets the localized GMT format pattern. The pattern must contain
354 * a single argument {0}, for example "GMT {0}".
355 * @param pattern The localized GMT format pattern to be used by this object.
356 * @param status Recieves the status.
357 * @see #getGMTPattern
360 void setGMTPattern(const UnicodeString& pattern, UErrorCode& status);
363 * Returns the offset pattern used for localized GMT format.
364 * @param type The offset pattern type enum.
365 * @param pattern Receives the offset pattern.
366 * @return A reference to the result pattern.
367 * @see #setGMTOffsetPattern
370 UnicodeString& getGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, UnicodeString& pattern) const;
373 * Sets the offset pattern for the given offset type.
374 * @param type The offset pattern type enum.
375 * @param pattern The offset pattern used for localized GMT format for the type.
376 * @param status Receives the status.
377 * @see #getGMTOffsetPattern
380 void setGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, const UnicodeString& pattern, UErrorCode& status);
383 * Returns the decimal digit characters used for localized GMT format.
384 * The return string contains exactly 10 code points (may include Unicode
385 * supplementary character) representing digit 0 to digit 9 in the ascending
387 * @param digits Receives the decimal digits used for localized GMT format.
388 * @see #setGMTOffsetDigits
391 UnicodeString& getGMTOffsetDigits(UnicodeString& digits) const;
394 * Sets the decimal digit characters used for localized GMT format.
395 * The input <code>digits</code> must contain exactly 10 code points
396 * (Unicode supplementary characters are also allowed) representing
397 * digit 0 to digit 9 in the ascending order. When the input <code>digits</code>
398 * does not satisfy the condition, <code>U_ILLEGAL_ARGUMENT_ERROR</code>
399 * will be set to the return status.
400 * @param digits The decimal digits used for localized GMT format.
401 * @param status Receives the status.
402 * @see #getGMTOffsetDigits
405 void setGMTOffsetDigits(const UnicodeString& digits, UErrorCode& status);
408 * Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0).
409 * @param gmtZeroFormat Receives the localized GMT string string for GMT(UTC) itself.
410 * @return A reference to the result GMT string.
411 * @see #setGMTZeroFormat
414 UnicodeString& getGMTZeroFormat(UnicodeString& gmtZeroFormat) const;
417 * Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0).
418 * @param gmtZeroFormat The localized GMT format string for GMT(UTC).
419 * @param status Receives the status.
420 * @see #getGMTZeroFormat
423 void setGMTZeroFormat(const UnicodeString& gmtZeroFormat, UErrorCode& status);
426 * Returns the bitwise flags of UTimeZoneFormatParseOption representing the default parse
427 * options used by this object.
428 * @return the default parse options.
432 uint32_t getDefaultParseOptions(void) const;
435 * Sets the default parse options.
436 * <p><b>Note</b>: By default, an instance of <code>TimeZoneFormat</code>
437 * created by {@link #createInstance} has no parse options set (UTZFMT_PARSE_OPTION_NONE).
438 * To specify multipe options, use bitwise flags of UTimeZoneFormatParseOption.
439 * @see #UTimeZoneFormatParseOption
442 void setDefaultParseOptions(uint32_t flags);
445 * Returns the ISO 8601 basic time zone string for the given offset.
446 * For example, "-08", "-0830" and "Z"
448 * @param offset the offset from GMT(UTC) in milliseconds.
449 * @param useUtcIndicator true if ISO 8601 UTC indicator "Z" is used when the offset is 0.
450 * @param isShort true if shortest form is used.
451 * @param ignoreSeconds true if non-zero offset seconds is appended.
452 * @param result Receives the ISO format string.
453 * @param status Receives the status
454 * @return the ISO 8601 basic format.
455 * @see #formatOffsetISO8601Extended
456 * @see #parseOffsetISO8601
459 UnicodeString& formatOffsetISO8601Basic(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds,
460 UnicodeString& result, UErrorCode& status) const;
463 * Returns the ISO 8601 extended time zone string for the given offset.
464 * For example, "-08:00", "-08:30" and "Z"
466 * @param offset the offset from GMT(UTC) in milliseconds.
467 * @param useUtcIndicator true if ISO 8601 UTC indicator "Z" is used when the offset is 0.
468 * @param isShort true if shortest form is used.
469 * @param ignoreSeconds true if non-zero offset seconds is appended.
470 * @param result Receives the ISO format string.
471 * @param status Receives the status
472 * @return the ISO 8601 basic format.
473 * @see #formatOffsetISO8601Extended
474 * @see #parseOffsetISO8601
477 UnicodeString& formatOffsetISO8601Extended(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds,
478 UnicodeString& result, UErrorCode& status) const;
481 * Returns the localized GMT(UTC) offset format for the given offset.
482 * The localized GMT offset is defined by;
484 * <li>GMT format pattern (e.g. "GMT {0}" - see {@link #getGMTPattern})
485 * <li>Offset time pattern (e.g. "+HH:mm" - see {@link #getGMTOffsetPattern})
486 * <li>Offset digits (e.g. "0123456789" - see {@link #getGMTOffsetDigits})
487 * <li>GMT zero format (e.g. "GMT" - see {@link #getGMTZeroFormat})
489 * This format always uses 2 digit hours and minutes. When the given offset has non-zero
490 * seconds, 2 digit seconds field will be appended. For example,
491 * GMT+05:00 and GMT+05:28:06.
492 * @param offset the offset from GMT(UTC) in milliseconds.
493 * @param status Receives the status
494 * @param result Receives the localized GMT format string.
495 * @return A reference to the result.
496 * @see #parseOffsetLocalizedGMT
499 UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const;
502 * Returns the short localized GMT(UTC) offset format for the given offset.
503 * The short localized GMT offset is defined by;
505 * <li>GMT format pattern (e.g. "GMT {0}" - see {@link #getGMTPattern})
506 * <li>Offset time pattern (e.g. "+HH:mm" - see {@link #getGMTOffsetPattern})
507 * <li>Offset digits (e.g. "0123456789" - see {@link #getGMTOffsetDigits})
508 * <li>GMT zero format (e.g. "GMT" - see {@link #getGMTZeroFormat})
510 * This format uses the shortest representation of offset. The hours field does not
511 * have leading zero and lower fields with zero will be truncated. For example,
513 * @param offset the offset from GMT(UTC) in milliseconds.
514 * @param status Receives the status
515 * @param result Receives the short localized GMT format string.
516 * @return A reference to the result.
517 * @see #parseOffsetShortLocalizedGMT
520 UnicodeString& formatOffsetShortLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const;
522 using Format::format;
525 * Returns the display name of the time zone at the given date for the style.
526 * @param style The style (e.g. <code>UTZFMT_STYLE_GENERIC_LONG</code>, <code>UTZFMT_STYLE_LOCALIZED_GMT</code>...)
527 * @param tz The time zone.
528 * @param date The date.
529 * @param name Receives the display name.
530 * @param timeType the output argument for receiving the time type (standard/daylight/unknown)
531 * used for the display name, or NULL if the information is not necessary.
532 * @return A reference to the result
533 * @see #UTimeZoneFormatStyle
534 * @see #UTimeZoneFormatTimeType
537 virtual UnicodeString& format(UTimeZoneFormatStyle style, const TimeZone& tz, UDate date,
538 UnicodeString& name, UTimeZoneFormatTimeType* timeType = NULL) const;
541 * Returns offset from GMT(UTC) in milliseconds for the given ISO 8601
542 * style time zone string. When the given string is not an ISO 8601 time zone
543 * string, this method sets the current position as the error index
544 * to <code>ParsePosition pos</code> and returns 0.
545 * @param text The text contains ISO8601 style time zone string (e.g. "-08:00", "Z")
547 * @param pos The ParsePosition object.
548 * @return The offset from GMT(UTC) in milliseconds for the given ISO 8601 style
550 * @see #formatOffsetISO8601Basic
551 * @see #formatOffsetISO8601Extended
554 int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos) const;
557 * Returns offset from GMT(UTC) in milliseconds for the given localized GMT
558 * offset format string. When the given string cannot be parsed, this method
559 * sets the current position as the error index to <code>ParsePosition pos</code>
561 * @param text The text contains a localized GMT offset string at the position.
562 * @param pos The ParsePosition object.
563 * @return The offset from GMT(UTC) in milliseconds for the given localized GMT
564 * offset format string.
565 * @see #formatOffsetLocalizedGMT
568 int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const;
571 * Returns offset from GMT(UTC) in milliseconds for the given short localized GMT
572 * offset format string. When the given string cannot be parsed, this method
573 * sets the current position as the error index to <code>ParsePosition pos</code>
575 * @param text The text contains a short localized GMT offset string at the position.
576 * @param pos The ParsePosition object.
577 * @return The offset from GMT(UTC) in milliseconds for the given short localized GMT
578 * offset format string.
579 * @see #formatOffsetShortLocalizedGMT
582 int32_t parseOffsetShortLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const;
585 * Returns a <code>TimeZone</code> by parsing the time zone string according to
586 * the given parse position, the specified format style and parse options.
588 * @param text The text contains a time zone string at the position.
589 * @param style The format style
590 * @param pos The position.
591 * @param parseOptions The parse options repesented by bitwise flags of UTimeZoneFormatParseOption.
592 * @param timeType The output argument for receiving the time type (standard/daylight/unknown),
593 * or NULL if the information is not necessary.
594 * @return A <code>TimeZone</code>, or null if the input could not be parsed.
595 * @see UTimeZoneFormatStyle
596 * @see UTimeZoneFormatParseOption
597 * @see UTimeZoneFormatTimeType
600 virtual TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos,
601 int32_t parseOptions, UTimeZoneFormatTimeType* timeType = NULL) const;
604 * Returns a <code>TimeZone</code> by parsing the time zone string according to
605 * the given parse position, the specified format style and the default parse options.
607 * @param text The text contains a time zone string at the position.
608 * @param style The format style
609 * @param pos The position.
610 * @param timeType The output argument for receiving the time type (standard/daylight/unknown),
611 * or NULL if the information is not necessary.
612 * @return A <code>TimeZone</code>, or null if the input could not be parsed.
613 * @see UTimeZoneFormatStyle
614 * @see UTimeZoneFormatParseOption
615 * @see UTimeZoneFormatTimeType
618 TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos,
619 UTimeZoneFormatTimeType* timeType = NULL) const;
621 /* ----------------------------------------------
623 * ---------------------------------------------- */
626 * Format an object to produce a time zone display string using localized GMT offset format.
627 * This method handles Formattable objects with a <code>TimeZone</code>. If a the Formattable
628 * object type is not a <code>TimeZone</code>, then it returns a failing UErrorCode.
629 * @param obj The object to format. Must be a <code>TimeZone</code>.
630 * @param appendTo Output parameter to receive result. Result is appended to existing contents.
631 * @param pos On input: an alignment field, if desired. On output: the offsets of the alignment field.
632 * @param status Output param filled with success/failure status.
633 * @return Reference to 'appendTo' parameter.
636 virtual UnicodeString& format(const Formattable& obj, UnicodeString& appendTo,
637 FieldPosition& pos, UErrorCode& status) const;
640 * Parse a string to produce an object. This methods handles parsing of
641 * time zone display strings into Formattable objects with <code>TimeZone</code>.
642 * @param source The string to be parsed into an object.
643 * @param result Formattable to be set to the parse result. If parse fails, return contents are undefined.
644 * @param parse_pos The position to start parsing at. Upon return this param is set to the position after the
645 * last character successfully parsed. If the source is not parsed successfully, this param
646 * will remain unchanged.
647 * @return A newly created Formattable* object, or NULL on failure. The caller owns this and should
648 * delete it when done.
651 virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const;
654 * ICU "poor man's RTTI", returns a UClassID for this class.
657 static UClassID U_EXPORT2 getStaticClassID(void);
660 * ICU "poor man's RTTI", returns a UClassID for the actual class.
663 virtual UClassID getDynamicClassID() const;
667 * Constructs a TimeZoneFormat object for the specified locale.
668 * @param locale the locale
669 * @param status receives the status.
672 TimeZoneFormat(const Locale& locale, UErrorCode& status);
675 /* Locale of this object */
678 /* Stores the region (could be implicit default) */
679 char fTargetRegion[ULOC_COUNTRY_CAPACITY];
681 /* TimeZoneNames object used by this formatter */
682 TimeZoneNames* fTimeZoneNames;
684 /* TimeZoneGenericNames object used by this formatter - lazily instantiated */
685 TimeZoneGenericNames* fTimeZoneGenericNames;
687 /* Localized GMT format pattern - e.g. "GMT{0}" */
688 UnicodeString fGMTPattern;
690 /* Array of offset patterns used by Localized GMT format - e.g. "+HH:mm" */
691 UnicodeString fGMTOffsetPatterns[UTZFMT_PAT_COUNT];
693 /* Localized decimal digits used by Localized GMT format */
694 UChar32 fGMTOffsetDigits[10];
696 /* Localized GMT zero format - e.g. "GMT" */
697 UnicodeString fGMTZeroFormat;
699 /* Bit flags representing parse options */
700 uint32_t fDefParseOptionFlags;
702 /* Constant parts of GMT format pattern, populated from localized GMT format pattern*/
703 UnicodeString fGMTPatternPrefix; /* Substring before {0} */
704 UnicodeString fGMTPatternSuffix; /* Substring after {0} */
706 /* Compiled offset patterns generated from fGMTOffsetPatterns[] */
707 UVector* fGMTOffsetPatternItems[UTZFMT_PAT_COUNT];
709 UBool fAbuttingOffsetHoursAndMinutes;
711 /* TZDBTimeZoneNames object used for parsing */
712 TZDBTimeZoneNames* fTZDBTimeZoneNames;
715 * Returns the time zone's specific format string.
716 * @param tz the time zone
717 * @param stdType the name type used for standard time
718 * @param dstType the name type used for daylight time
719 * @param date the date
720 * @param name receives the time zone's specific format name string
721 * @param timeType when null, actual time type is set
722 * @return a reference to name.
724 UnicodeString& formatSpecific(const TimeZone& tz, UTimeZoneNameType stdType, UTimeZoneNameType dstType,
725 UDate date, UnicodeString& name, UTimeZoneFormatTimeType *timeType) const;
728 * Returns the time zone's generic format string.
729 * @param tz the time zone
730 * @param genType the generic name type
731 * @param date the date
732 * @param name receives the time zone's generic format name string
733 * @return a reference to name.
735 UnicodeString& formatGeneric(const TimeZone& tz, int32_t genType, UDate date, UnicodeString& name) const;
738 * Lazily create a TimeZoneGenericNames instance
739 * @param status receives the status
740 * @return the cached TimeZoneGenericNames.
742 const TimeZoneGenericNames* getTimeZoneGenericNames(UErrorCode& status) const;
745 * Lazily create a TZDBTimeZoneNames instance
746 * @param status receives the status
747 * @return the cached TZDBTimeZoneNames.
749 const TZDBTimeZoneNames* getTZDBTimeZoneNames(UErrorCode& status) const;
752 * Private method returning the time zone's exemplar location string.
753 * This method will never return empty.
754 * @param tz the time zone
755 * @param name receives the time zone's exemplar location name
756 * @return a reference to name.
758 UnicodeString& formatExemplarLocation(const TimeZone& tz, UnicodeString& name) const;
761 * Private enum specifying a combination of offset fields
770 * Parses the localized GMT pattern string and initialize
771 * localized gmt pattern fields.
772 * @param gmtPattern the localized GMT pattern string such as "GMT {0}"
773 * @param status U_ILLEGAL_ARGUMENT_ERROR is set when the specified pattern does not
774 * contain an argument "{0}".
776 void initGMTPattern(const UnicodeString& gmtPattern, UErrorCode& status);
779 * Parse the GMT offset pattern into runtime optimized format.
780 * @param pattern the offset pattern string
781 * @param required the required set of fields, such as FIELDS_HM
782 * @param status U_ILLEGAL_ARGUMENT is set when the specified pattern does not contain
783 * pattern letters for the required fields.
784 * @return A list of GMTOffsetField objects, or NULL on error.
786 static UVector* parseOffsetPattern(const UnicodeString& pattern, OffsetFields required, UErrorCode& status);
789 * Appends seconds field to the offset pattern with hour/minute
790 * Note: This code will be obsoleted once we add hour-minute-second pattern data in CLDR.
791 * @param offsetHM the offset pattern including hours and minutes fields
792 * @param result the output offset pattern including hour, minute and seconds fields
793 * @param status receives the status
794 * @return a reference to result
796 static UnicodeString& expandOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status);
799 * Truncates minutes field to the offset pattern with hour/minute
800 * Note: This code will be obsoleted once we add hour pattern data in CLDR.
801 * @param offsetHM the offset pattern including hours and minutes fields
802 * @param result the output offset pattern including only hours field
803 * @param status receives the status
804 * @return a reference to result
806 static UnicodeString& truncateOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status);
809 * Break input string into UChar32[]. Each array element represents
810 * a code point. This method is used for parsing localized digit
811 * characters and support characters in Unicode supplemental planes.
812 * @param str the string
813 * @param codeArray receives the result
814 * @param capacity the capacity of codeArray
815 * @return TRUE when the specified code array is fully filled with code points
816 * (no under/overflow).
818 static UBool toCodePoints(const UnicodeString& str, UChar32* codeArray, int32_t capacity);
821 * Private method supprting all of ISO8601 formats
822 * @param offset the offset from GMT(UTC) in milliseconds.
823 * @param useUtcIndicator true if ISO 8601 UTC indicator "Z" is used when the offset is 0.
824 * @param isShort true if shortest form is used.
825 * @param ignoreSeconds true if non-zero offset seconds is appended.
826 * @param result Receives the result
827 * @param status Receives the status
828 * @return the ISO 8601 basic format.
830 UnicodeString& formatOffsetISO8601(int32_t offset, UBool isBasic, UBool useUtcIndicator,
831 UBool isShort, UBool ignoreSeconds, UnicodeString& result, UErrorCode& status) const;
834 * Private method used for localized GMT formatting.
835 * @param offset the zone's UTC offset
836 * @param isShort true if the short localized GMT format is desired.
837 * @param result receives the localized GMT format string
838 * @param status receives the status
840 UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UBool isShort, UnicodeString& result, UErrorCode& status) const;
843 * Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 style
844 * (extended format) time zone string. When the given string is not an ISO 8601 time
845 * zone string, this method sets the current position as the error index
846 * to <code>ParsePosition pos</code> and returns 0.
847 * @param text the text contains ISO 8601 style time zone string (e.g. "-08:00", "Z")
849 * @param pos the position, non-negative error index will be set on failure.
850 * @param extendedOnly TRUE if parsing the text as ISO 8601 extended offset format (e.g. "-08:00"),
851 * or FALSE to evaluate the text as basic format.
852 * @param hasDigitOffset receiving if the parsed zone string contains offset digits.
853 * @return the offset from GMT(UTC) in milliseconds for the given ISO 8601 style
856 int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos, UBool extendedOnly,
857 UBool* hasDigitOffset = NULL) const;
860 * Appends localized digits to the buffer.
861 * This code assumes that the input number is 0 - 59
862 * @param buf the target buffer
863 * @param n the integer number
864 * @param minDigits the minimum digits width
866 void appendOffsetDigits(UnicodeString& buf, int32_t n, uint8_t minDigits) const;
869 * Returns offset from GMT(UTC) in milliseconds for the given localized GMT
870 * offset format string. When the given string cannot be parsed, this method
871 * sets the current position as the error index to <code>ParsePosition pos</code>
873 * @param text the text contains a localized GMT offset string at the position.
874 * @param pos the position, non-negative error index will be set on failure.
875 * @param isShort true if this parser to try the short format first
876 * @param hasDigitOffset receiving if the parsed zone string contains offset digits.
877 * @return the offset from GMT(UTC) in milliseconds for the given localized GMT
878 * offset format string.
880 int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos,
881 UBool isShort, UBool* hasDigitOffset) const;
884 * Parse localized GMT format generated by the patter used by this formatter, except
886 * @param text the input text
887 * @param start the start index
888 * @param isShort true if the short localized format is parsed.
889 * @param parsedLen receives the parsed length
890 * @return the parsed offset in milliseconds
892 int32_t parseOffsetLocalizedGMTPattern(const UnicodeString& text, int32_t start,
893 UBool isShort, int32_t& parsedLen) const;
896 * Parses localized GMT offset fields into offset.
897 * @param text the input text
898 * @param start the start index
899 * @param isShort true if this is a short format - currently not used
900 * @param parsedLen the parsed length, or 0 on failure.
901 * @return the parsed offset in milliseconds.
903 int32_t parseOffsetFields(const UnicodeString& text, int32_t start, UBool isShort, int32_t& parsedLen) const;
906 * Parse localized GMT offset fields with the given pattern.
907 * @param text the input text
908 * @param start the start index
909 * @param pattenItems the pattern (already itemized)
910 * @param forceSingleHourDigit true if hours field is parsed as a single digit
911 * @param hour receives the hour offset field
912 * @param min receives the minute offset field
913 * @param sec receives the second offset field
914 * @return the parsed length
916 int32_t parseOffsetFieldsWithPattern(const UnicodeString& text, int32_t start,
917 UVector* patternItems, UBool forceSingleHourDigit, int32_t& hour, int32_t& min, int32_t& sec) const;
920 * Parses abutting localized GMT offset fields (such as 0800) into offset.
921 * @param text the input text
922 * @param start the start index
923 * @param parsedLen the parsed length, or 0 on failure
924 * @return the parsed offset in milliseconds.
926 int32_t parseAbuttingOffsetFields(const UnicodeString& text, int32_t start, int32_t& parsedLen) const;
929 * Parses the input text using the default format patterns (e.g. "UTC{0}").
930 * @param text the input text
931 * @param start the start index
932 * @param parsedLen the parsed length, or 0 on failure
933 * @return the parsed offset in milliseconds.
935 int32_t parseOffsetDefaultLocalizedGMT(const UnicodeString& text, int start, int32_t& parsedLen) const;
938 * Parses the input GMT offset fields with the default offset pattern.
939 * @param text the input text
940 * @param start the start index
941 * @param separator the separator character, e.g. ':'
942 * @param parsedLen the parsed length, or 0 on failure.
943 * @return the parsed offset in milliseconds.
945 int32_t parseDefaultOffsetFields(const UnicodeString& text, int32_t start, UChar separator,
946 int32_t& parsedLen) const;
949 * Reads an offset field value. This method will stop parsing when
950 * 1) number of digits reaches <code>maxDigits</code>
951 * 2) just before already parsed number exceeds <code>maxVal</code>
953 * @param text the text
954 * @param start the start offset
955 * @param minDigits the minimum number of required digits
956 * @param maxDigits the maximum number of digits
957 * @param minVal the minimum value
958 * @param maxVal the maximum value
959 * @param parsedLen the actual parsed length.
960 * @return the integer value parsed
962 int32_t parseOffsetFieldWithLocalizedDigits(const UnicodeString& text, int32_t start,
963 uint8_t minDigits, uint8_t maxDigits, uint16_t minVal, uint16_t maxVal, int32_t& parsedLen) const;
966 * Reads a single decimal digit, either localized digits used by this object
967 * or any Unicode numeric character.
968 * @param text the text
969 * @param start the start index
970 * @param len the actual length read from the text
971 * the start index is not a decimal number.
972 * @return the integer value of the parsed digit, or -1 on failure.
974 int32_t parseSingleLocalizedDigit(const UnicodeString& text, int32_t start, int32_t& len) const;
977 * Formats offset using ASCII digits. The input offset range must be
978 * within +/-24 hours (exclusive).
979 * @param offset The offset
980 * @param sep The field separator character or 0 if not required
981 * @param minFields The minimum fields
982 * @param maxFields The maximum fields
983 * @return The offset string
985 static UnicodeString& formatOffsetWithAsciiDigits(int32_t offset, UChar sep,
986 OffsetFields minFields, OffsetFields maxFields, UnicodeString& result);
989 * Parses offset represented by contiguous ASCII digits.
991 * Note: This method expects the input position is already at the start of
992 * ASCII digits and does not parse sign (+/-).
993 * @param text The text contains a sequence of ASCII digits
994 * @param pos The parse position
995 * @param minFields The minimum Fields to be parsed
996 * @param maxFields The maximum Fields to be parsed
997 * @param fixedHourWidth true if hours field must be width of 2
998 * @return Parsed offset, 0 or positive number.
1000 static int32_t parseAbuttingAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos,
1001 OffsetFields minFields, OffsetFields maxFields, UBool fixedHourWidth);
1004 * Parses offset represented by ASCII digits and separators.
1006 * Note: This method expects the input position is already at the start of
1007 * ASCII digits and does not parse sign (+/-).
1008 * @param text The text
1009 * @param pos The parse position
1010 * @param sep The separator character
1011 * @param minFields The minimum Fields to be parsed
1012 * @param maxFields The maximum Fields to be parsed
1013 * @return Parsed offset, 0 or positive number.
1015 static int32_t parseAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, UChar sep,
1016 OffsetFields minFields, OffsetFields maxFields);
1019 * Unquotes the message format style pattern.
1020 * @param pattern the pattern
1021 * @param result receive the unquoted pattern.
1022 * @return A reference to result.
1024 static UnicodeString& unquote(const UnicodeString& pattern, UnicodeString& result);
1027 * Initialize localized GMT format offset hour/min/sec patterns.
1028 * This method parses patterns into optimized run-time format.
1029 * @param status receives the status.
1031 void initGMTOffsetPatterns(UErrorCode& status);
1034 * Check if there are any GMT format offset patterns without
1035 * any separators between hours field and minutes field and update
1036 * fAbuttingOffsetHoursAndMinutes field. This method must be called
1037 * after all patterns are parsed into pattern items.
1039 void checkAbuttingHoursAndMinutes();
1042 * Creates an instance of TimeZone for the given offset
1043 * @param offset the offset
1044 * @return A TimeZone with the given offset
1046 TimeZone* createTimeZoneForOffset(int32_t offset) const;
1049 * Returns the time type for the given name type
1050 * @param nameType the name type
1051 * @return the time type (unknown/standard/daylight)
1053 static UTimeZoneFormatTimeType getTimeType(UTimeZoneNameType nameType);
1056 * Returns the time zone ID of a match at the specified index within
1057 * the MatchInfoCollection.
1058 * @param matches the collection of matches
1059 * @param idx the index withing matches
1060 * @param tzID receives the resolved time zone ID
1061 * @return a reference to tzID.
1063 UnicodeString& getTimeZoneID(const TimeZoneNames::MatchInfoCollection* matches, int32_t idx, UnicodeString& tzID) const;
1068 * @param text the text contains a time zone ID string at the position.
1069 * @param pos the position
1070 * @param tzID receives the zone ID
1071 * @return a reference to tzID
1073 UnicodeString& parseZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1076 * Parse a short zone ID.
1077 * @param text the text contains a short time zone ID string at the position.
1078 * @param pos the position
1079 * @param tzID receives the short zone ID
1080 * @return a reference to tzID
1082 UnicodeString& parseShortZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1085 * Parse an exemplar location string.
1086 * @param text the text contains an exemplar location string at the position.
1087 * @param pos the position.
1088 * @param tzID receives the time zone ID
1089 * @return a reference to tzID
1091 UnicodeString& parseExemplarLocation(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1096 #endif /* !UCONFIG_NO_FORMATTING */