• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (C) 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 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}.
244       * @stable ICU 54
245       */
246     UTZFMT_PARSE_OPTION_TZ_DATABASE_ABBREVIATIONS = 0x02
247 } UTimeZoneFormatParseOption;
248 
249 U_CDECL_END
250 
251 U_NAMESPACE_BEGIN
252 
253 class TimeZoneGenericNames;
254 class TZDBTimeZoneNames;
255 class UVector;
256 
257 /**
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.
262  * <p>
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.
267  *
268  * @see SimpleDateFormat
269  * @see TimeZoneNames
270  * @stable ICU 50
271  */
272 class U_I18N_API TimeZoneFormat : public Format {
273 public:
274     /**
275      * Copy constructor.
276      * @stable ICU 50
277      */
278     TimeZoneFormat(const TimeZoneFormat& other);
279 
280     /**
281      * Destructor.
282      * @stable ICU 50
283      */
284     virtual ~TimeZoneFormat();
285 
286     /**
287      * Assignment operator.
288      * @stable ICU 50
289      */
290     TimeZoneFormat& operator=(const TimeZoneFormat& other);
291 
292     /**
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.
298      * @stable ICU 50
299      */
300     virtual UBool operator==(const Format& other) const;
301 
302     /**
303      * Clone this object polymorphically. The caller is responsible
304      * for deleting the result when done.
305      * @return A copy of the object
306      * @stable ICU 50
307      */
308     virtual Format* clone() const;
309 
310     /**
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.
316      * @stable ICU 50
317      */
318     static TimeZoneFormat* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
319 
320     /**
321      * Returns the time zone display name data used by this instance.
322      * @return The time zone display name data.
323      * @stable ICU 50
324      */
325     const TimeZoneNames* getTimeZoneNames() const;
326 
327     /**
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
330      * by this call.
331      * @param tznames TimeZoneNames object to be adopted.
332      * @stable ICU 50
333      */
334     void adoptTimeZoneNames(TimeZoneNames *tznames);
335 
336     /**
337      * Sets the time zone display name data to this format instnace.
338      * @param tznames TimeZoneNames object to be set.
339      * @stable ICU 50
340      */
341     void setTimeZoneNames(const TimeZoneNames &tznames);
342 
343     /**
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
348      * @stable ICU 50
349      */
350     UnicodeString& getGMTPattern(UnicodeString& pattern) const;
351 
352     /**
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
358      * @stable ICU 50
359      */
360     void setGMTPattern(const UnicodeString& pattern, UErrorCode& status);
361 
362     /**
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
368      * @stable ICU 50
369      */
370     UnicodeString& getGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, UnicodeString& pattern) const;
371 
372     /**
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
378      * @stable ICU 50
379      */
380     void setGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, const UnicodeString& pattern, UErrorCode& status);
381 
382     /**
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
386      * order.
387      * @param digits Receives the decimal digits used for localized GMT format.
388      * @see #setGMTOffsetDigits
389      * @stable ICU 50
390      */
391     UnicodeString& getGMTOffsetDigits(UnicodeString& digits) const;
392 
393     /**
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
403      * @stable ICU 50
404      */
405     void setGMTOffsetDigits(const UnicodeString& digits, UErrorCode& status);
406 
407     /**
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
412      * @stable ICU 50
413      */
414     UnicodeString& getGMTZeroFormat(UnicodeString& gmtZeroFormat) const;
415 
416     /**
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
421      * @stable ICU 50
422      */
423     void setGMTZeroFormat(const UnicodeString& gmtZeroFormat, UErrorCode& status);
424 
425     /**
426      * Returns the bitwise flags of UTimeZoneFormatParseOption representing the default parse
427      * options used by this object.
428      * @return the default parse options.
429      * @see ParseOption
430      * @stable ICU 50
431      */
432     uint32_t getDefaultParseOptions(void) const;
433 
434     /**
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
440      * @stable ICU 50
441      */
442     void setDefaultParseOptions(uint32_t flags);
443 
444     /**
445      * Returns the ISO 8601 basic time zone string for the given offset.
446      * For example, "-08", "-0830" and "Z"
447      *
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
457      * @stable ICU 51
458      */
459     UnicodeString& formatOffsetISO8601Basic(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds,
460         UnicodeString& result, UErrorCode& status) const;
461 
462     /**
463      * Returns the ISO 8601 extended time zone string for the given offset.
464      * For example, "-08:00", "-08:30" and "Z"
465      *
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
475      * @stable ICU 51
476      */
477     UnicodeString& formatOffsetISO8601Extended(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds,
478         UnicodeString& result, UErrorCode& status) const;
479 
480     /**
481      * Returns the localized GMT(UTC) offset format for the given offset.
482      * The localized GMT offset is defined by;
483      * <ul>
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})
488      * </ul>
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
497      * @stable ICU 50
498      */
499     UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const;
500 
501     /**
502      * Returns the short localized GMT(UTC) offset format for the given offset.
503      * The short localized GMT offset is defined by;
504      * <ul>
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})
509      * </ul>
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,
512      * GMT+5 and GMT+530.
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
518      * @stable ICU 51
519      */
520     UnicodeString& formatOffsetShortLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const;
521 
522     using Format::format;
523 
524     /**
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
535      * @stable ICU 50
536      */
537     virtual UnicodeString& format(UTimeZoneFormatStyle style, const TimeZone& tz, UDate date,
538         UnicodeString& name, UTimeZoneFormatTimeType* timeType = NULL) const;
539 
540     /**
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")
546      *              at the position.
547      * @param pos The ParsePosition object.
548      * @return The offset from GMT(UTC) in milliseconds for the given ISO 8601 style
549      *              time zone string.
550      * @see #formatOffsetISO8601Basic
551      * @see #formatOffsetISO8601Extended
552      * @stable ICU 50
553      */
554     int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos) const;
555 
556     /**
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>
560      * and returns 0.
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
566      * @stable ICU 50
567      */
568     int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const;
569 
570     /**
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>
574      * and returns 0.
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
580      * @stable ICU 51
581      */
582     int32_t parseOffsetShortLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const;
583 
584     /**
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.
587      *
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
598      * @stable ICU 50
599      */
600     virtual TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos,
601         int32_t parseOptions, UTimeZoneFormatTimeType* timeType = NULL) const;
602 
603     /**
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.
606      *
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
616      * @stable ICU 50
617      */
618     TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos,
619         UTimeZoneFormatTimeType* timeType = NULL) const;
620 
621     /* ----------------------------------------------
622      * Format APIs
623      * ---------------------------------------------- */
624 
625     /**
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.
634      * @stable ICU 50
635      */
636     virtual UnicodeString& format(const Formattable& obj, UnicodeString& appendTo,
637         FieldPosition& pos, UErrorCode& status) const;
638 
639     /**
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.
649      * @stable ICU 50
650      */
651     virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const;
652 
653     /**
654      * ICU "poor man's RTTI", returns a UClassID for this class.
655      * @stable ICU 50
656      */
657     static UClassID U_EXPORT2 getStaticClassID(void);
658 
659     /**
660      * ICU "poor man's RTTI", returns a UClassID for the actual class.
661      * @stable ICU 50
662      */
663     virtual UClassID getDynamicClassID() const;
664 
665 protected:
666     /**
667      * Constructs a TimeZoneFormat object for the specified locale.
668      * @param locale the locale
669      * @param status receives the status.
670      * @stable ICU 50
671      */
672     TimeZoneFormat(const Locale& locale, UErrorCode& status);
673 
674 private:
675     /* Locale of this object */
676     Locale fLocale;
677 
678     /* Stores the region (could be implicit default) */
679     char fTargetRegion[ULOC_COUNTRY_CAPACITY];
680 
681     /* TimeZoneNames object used by this formatter */
682     TimeZoneNames* fTimeZoneNames;
683 
684     /* TimeZoneGenericNames object used by this formatter - lazily instantiated */
685     TimeZoneGenericNames* fTimeZoneGenericNames;
686 
687     /* Localized GMT format pattern - e.g. "GMT{0}" */
688     UnicodeString fGMTPattern;
689 
690     /* Array of offset patterns used by Localized GMT format - e.g. "+HH:mm" */
691     UnicodeString fGMTOffsetPatterns[UTZFMT_PAT_COUNT];
692 
693     /* Localized decimal digits used by Localized GMT format */
694     UChar32 fGMTOffsetDigits[10];
695 
696     /* Localized GMT zero format - e.g. "GMT" */
697     UnicodeString fGMTZeroFormat;
698 
699     /* Bit flags representing parse options */
700     uint32_t fDefParseOptionFlags;
701 
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} */
705 
706     /* Compiled offset patterns generated from fGMTOffsetPatterns[] */
707     UVector* fGMTOffsetPatternItems[UTZFMT_PAT_COUNT];
708 
709     UBool fAbuttingOffsetHoursAndMinutes;
710 
711     /* TZDBTimeZoneNames object used for parsing */
712     TZDBTimeZoneNames* fTZDBTimeZoneNames;
713 
714     /**
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.
723      */
724     UnicodeString& formatSpecific(const TimeZone& tz, UTimeZoneNameType stdType, UTimeZoneNameType dstType,
725         UDate date, UnicodeString& name, UTimeZoneFormatTimeType *timeType) const;
726 
727     /**
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.
734      */
735     UnicodeString& formatGeneric(const TimeZone& tz, int32_t genType, UDate date, UnicodeString& name) const;
736 
737     /**
738      * Lazily create a TimeZoneGenericNames instance
739      * @param status receives the status
740      * @return the cached TimeZoneGenericNames.
741      */
742     const TimeZoneGenericNames* getTimeZoneGenericNames(UErrorCode& status) const;
743 
744     /**
745      * Lazily create a TZDBTimeZoneNames instance
746      * @param status receives the status
747      * @return the cached TZDBTimeZoneNames.
748      */
749     const TZDBTimeZoneNames* getTZDBTimeZoneNames(UErrorCode& status) const;
750 
751     /**
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.
757      */
758     UnicodeString& formatExemplarLocation(const TimeZone& tz, UnicodeString& name) const;
759 
760     /**
761      * Private enum specifying a combination of offset fields
762      */
763     enum OffsetFields {
764         FIELDS_H,
765         FIELDS_HM,
766         FIELDS_HMS
767     };
768 
769     /**
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}".
775      */
776     void initGMTPattern(const UnicodeString& gmtPattern, UErrorCode& status);
777 
778     /**
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.
785      */
786     static UVector* parseOffsetPattern(const UnicodeString& pattern, OffsetFields required, UErrorCode& status);
787 
788     /**
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
795      */
796     static UnicodeString& expandOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status);
797 
798     /**
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
805      */
806     static UnicodeString& truncateOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status);
807 
808     /**
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).
817      */
818     static UBool toCodePoints(const UnicodeString& str, UChar32* codeArray, int32_t capacity);
819 
820     /**
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.
829      */
830     UnicodeString& formatOffsetISO8601(int32_t offset, UBool isBasic, UBool useUtcIndicator,
831         UBool isShort, UBool ignoreSeconds, UnicodeString& result, UErrorCode& status) const;
832 
833     /**
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
839      */
840     UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UBool isShort, UnicodeString& result, UErrorCode& status) const;
841 
842     /**
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")
848      *      at the position.
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
854      *      time zone string.
855      */
856     int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos, UBool extendedOnly,
857         UBool* hasDigitOffset = NULL) const;
858 
859     /**
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
865      */
866     void appendOffsetDigits(UnicodeString& buf, int32_t n, uint8_t minDigits) const;
867 
868     /**
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>
872      * and returns 0.
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.
879      */
880     int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos,
881         UBool isShort, UBool* hasDigitOffset) const;
882 
883     /**
884      * Parse localized GMT format generated by the patter used by this formatter, except
885      * GMT Zero format.
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
891      */
892     int32_t parseOffsetLocalizedGMTPattern(const UnicodeString& text, int32_t start,
893         UBool isShort, int32_t& parsedLen) const;
894 
895     /**
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.
902      */
903     int32_t parseOffsetFields(const UnicodeString& text, int32_t start, UBool isShort, int32_t& parsedLen) const;
904 
905     /**
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
915      */
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;
918 
919     /**
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.
925      */
926     int32_t parseAbuttingOffsetFields(const UnicodeString& text, int32_t start, int32_t& parsedLen) const;
927 
928     /**
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.
934      */
935     int32_t parseOffsetDefaultLocalizedGMT(const UnicodeString& text, int start, int32_t& parsedLen) const;
936 
937     /**
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.
944      */
945     int32_t parseDefaultOffsetFields(const UnicodeString& text, int32_t start, UChar separator,
946         int32_t& parsedLen) const;
947 
948     /**
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>
952      *
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
961      */
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;
964 
965     /**
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.
973      */
974     int32_t parseSingleLocalizedDigit(const UnicodeString& text, int32_t start, int32_t& len) const;
975 
976     /**
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
984      */
985     static UnicodeString& formatOffsetWithAsciiDigits(int32_t offset, UChar sep,
986         OffsetFields minFields, OffsetFields maxFields, UnicodeString& result);
987 
988     /**
989      * Parses offset represented by contiguous ASCII digits.
990      * <p>
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.
999      */
1000     static int32_t parseAbuttingAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos,
1001         OffsetFields minFields, OffsetFields maxFields, UBool fixedHourWidth);
1002 
1003     /**
1004      * Parses offset represented by ASCII digits and separators.
1005      * <p>
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.
1014      */
1015     static int32_t parseAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, UChar sep,
1016         OffsetFields minFields, OffsetFields maxFields);
1017 
1018     /**
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.
1023      */
1024     static UnicodeString& unquote(const UnicodeString& pattern, UnicodeString& result);
1025 
1026     /**
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.
1030      */
1031     void initGMTOffsetPatterns(UErrorCode& status);
1032 
1033     /**
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.
1038      */
1039     void checkAbuttingHoursAndMinutes();
1040 
1041     /**
1042      * Creates an instance of TimeZone for the given offset
1043      * @param offset the offset
1044      * @return A TimeZone with the given offset
1045      */
1046     TimeZone* createTimeZoneForOffset(int32_t offset) const;
1047 
1048     /**
1049      * Returns the time type for the given name type
1050      * @param nameType the name type
1051      * @return the time type (unknown/standard/daylight)
1052      */
1053     static UTimeZoneFormatTimeType getTimeType(UTimeZoneNameType nameType);
1054 
1055     /**
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.
1062      */
1063     UnicodeString& getTimeZoneID(const TimeZoneNames::MatchInfoCollection* matches, int32_t idx, UnicodeString& tzID) const;
1064 
1065 
1066     /**
1067      * Parse a zone ID.
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
1072      */
1073     UnicodeString& parseZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1074 
1075     /**
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
1081      */
1082     UnicodeString& parseShortZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1083 
1084     /**
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
1090      */
1091     UnicodeString& parseExemplarLocation(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1092 };
1093 
1094 U_NAMESPACE_END
1095 
1096 #endif /* !UCONFIG_NO_FORMATTING */
1097 #endif
1098