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