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