Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/tzfmt.h @ 69:33d812a61356

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