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