intl/icu/source/i18n/unicode/tzfmt.h@6474c204b198
intl/icu/source/i18n/unicode/tzfmt.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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
10 /**
11 * \file
12 * \brief C++ API: TimeZoneFormat
13 */
15 #include "unicode/utypes.h"
17 #if !UCONFIG_NO_FORMATTING
19 #include "unicode/format.h"
20 #include "unicode/timezone.h"
21 #include "unicode/tznames.h"
23 U_CDECL_BEGIN
24 /**
25 * Constants for time zone display format style used by format/parse APIs
26 * in TimeZoneFormat.
27 * @stable ICU 50
28 */
29 typedef 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;
155 /**
156 * Constants for GMT offset pattern types.
157 * @stable ICU 50
158 */
159 typedef enum UTimeZoneFormatGMTOffsetPatternType {
160 /**
161 * Positive offset with hours and minutes fields
162 * @stable ICU 50
163 */
164 UTZFMT_PAT_POSITIVE_HM,
165 /**
166 * Positive offset with hours, minutes and seconds fields
167 * @stable ICU 50
168 */
169 UTZFMT_PAT_POSITIVE_HMS,
170 /**
171 * Negative offset with hours and minutes fields
172 * @stable ICU 50
173 */
174 UTZFMT_PAT_NEGATIVE_HM,
175 /**
176 * Negative offset with hours, minutes and seconds fields
177 * @stable ICU 50
178 */
179 UTZFMT_PAT_NEGATIVE_HMS,
180 #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 */
193 /**
194 * Number of UTimeZoneFormatGMTOffsetPatternType types.
195 * @internal
196 */
197 UTZFMT_PAT_COUNT = 6
198 } UTimeZoneFormatGMTOffsetPatternType;
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 */
205 typedef 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;
223 /**
224 * Constants for parse option flags, used for specifying optional parse behavior.
225 * @stable ICU 50
226 */
227 typedef 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;
242 U_CDECL_END
244 U_NAMESPACE_BEGIN
246 class TimeZoneGenericNames;
247 class UVector;
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 */
264 class U_I18N_API TimeZoneFormat : public Format {
265 public:
266 /**
267 * Copy constructor.
268 * @stable ICU 50
269 */
270 TimeZoneFormat(const TimeZoneFormat& other);
272 /**
273 * Destructor.
274 * @stable ICU 50
275 */
276 virtual ~TimeZoneFormat();
278 /**
279 * Assignment operator.
280 * @stable ICU 50
281 */
282 TimeZoneFormat& operator=(const TimeZoneFormat& other);
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;
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;
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);
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;
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);
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);
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;
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);
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;
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);
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;
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);
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;
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);
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;
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);
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;
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 */
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;
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 */
518 using Format::format;
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;
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;
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;
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 */
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;
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;
619 /* ----------------------------------------------
620 * Format APIs
621 * ---------------------------------------------- */
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;
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;
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);
657 /**
658 * ICU "poor man's RTTI", returns a UClassID for the actual class.
659 * @stable ICU 50
660 */
661 virtual UClassID getDynamicClassID() const;
663 protected:
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);
672 private:
673 /* Locale of this object */
674 Locale fLocale;
676 /* Stores the region (could be implicit default) */
677 char fTargetRegion[ULOC_COUNTRY_CAPACITY];
679 /* TimeZoneNames object used by this formatter */
680 TimeZoneNames* fTimeZoneNames;
682 /* TimeZoneGenericNames object used by this formatter - lazily instantiated */
683 TimeZoneGenericNames* fTimeZoneGenericNames;
685 /* Localized GMT format pattern - e.g. "GMT{0}" */
686 UnicodeString fGMTPattern;
688 /* Array of offset patterns used by Localized GMT format - e.g. "+HH:mm" */
689 UnicodeString fGMTOffsetPatterns[UTZFMT_PAT_COUNT];
691 /* Localized decimal digits used by Localized GMT format */
692 UChar32 fGMTOffsetDigits[10];
694 /* Localized GMT zero format - e.g. "GMT" */
695 UnicodeString fGMTZeroFormat;
697 /* Bit flags representing parse options */
698 uint32_t fDefParseOptionFlags;
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} */
704 /* Compiled offset patterns generated from fGMTOffsetPatterns[] */
705 UVector* fGMTOffsetPatternItems[UTZFMT_PAT_COUNT];
707 UBool fAbuttingOffsetHoursAndMinutes;
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;
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;
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;
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;
748 /**
749 * Private enum specifying a combination of offset fields
750 */
751 enum OffsetFields {
752 FIELDS_H,
753 FIELDS_HM,
754 FIELDS_HMS
755 };
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);
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);
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);
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);
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);
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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);
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);
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);
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);
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);
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();
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;
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);
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;
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;
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;
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 };
1082 U_NAMESPACE_END
1084 #endif /* !UCONFIG_NO_FORMATTING */
1085 #endif
