michael@0: /* michael@0: ******************************************************************************* michael@0: * Copyright (C) 2011-2013, International Business Machines Corporation and * michael@0: * others. All Rights Reserved. * michael@0: ******************************************************************************* michael@0: */ michael@0: #ifndef __TZFMT_H michael@0: #define __TZFMT_H michael@0: michael@0: /** michael@0: * \file michael@0: * \brief C++ API: TimeZoneFormat michael@0: */ michael@0: michael@0: #include "unicode/utypes.h" michael@0: michael@0: #if !UCONFIG_NO_FORMATTING michael@0: michael@0: #include "unicode/format.h" michael@0: #include "unicode/timezone.h" michael@0: #include "unicode/tznames.h" michael@0: michael@0: U_CDECL_BEGIN michael@0: /** michael@0: * Constants for time zone display format style used by format/parse APIs michael@0: * in TimeZoneFormat. michael@0: * @stable ICU 50 michael@0: */ michael@0: typedef enum UTimeZoneFormatStyle { michael@0: /** michael@0: * Generic location format, such as "United States Time (New York)", "Italy Time" michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_STYLE_GENERIC_LOCATION, michael@0: /** michael@0: * Generic long non-location format, such as "Eastern Time". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_STYLE_GENERIC_LONG, michael@0: /** michael@0: * Generic short non-location format, such as "ET". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_STYLE_GENERIC_SHORT, michael@0: /** michael@0: * Specific long format, such as "Eastern Standard Time". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_STYLE_SPECIFIC_LONG, michael@0: /** michael@0: * Specific short format, such as "EST", "PDT". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_STYLE_SPECIFIC_SHORT, michael@0: /** michael@0: * Localized GMT offset format, such as "GMT-05:00", "UTC+0100" michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_STYLE_LOCALIZED_GMT, michael@0: #ifndef U_HIDE_DRAFT_API michael@0: /** michael@0: * Short localized GMT offset format, such as "GMT-5", "UTC+1:30" michael@0: * This style is equivalent to the LDML date format pattern "O". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_LOCALIZED_GMT_SHORT, michael@0: /** michael@0: * Short ISO 8601 local time difference (basic format) or the UTC indicator. michael@0: * For example, "-05", "+0530", and "Z"(UTC). michael@0: * This style is equivalent to the LDML date format pattern "X". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_BASIC_SHORT, michael@0: /** michael@0: * Short ISO 8601 locale time difference (basic format). michael@0: * For example, "-05" and "+0530". michael@0: * This style is equivalent to the LDML date format pattern "x". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_BASIC_LOCAL_SHORT, michael@0: /** michael@0: * Fixed width ISO 8601 local time difference (basic format) or the UTC indicator. michael@0: * For example, "-0500", "+0530", and "Z"(UTC). michael@0: * This style is equivalent to the LDML date format pattern "XX". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_BASIC_FIXED, michael@0: /** michael@0: * Fixed width ISO 8601 local time difference (basic format). michael@0: * For example, "-0500" and "+0530". michael@0: * This style is equivalent to the LDML date format pattern "xx". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_BASIC_LOCAL_FIXED, michael@0: /** michael@0: * ISO 8601 local time difference (basic format) with optional seconds field, or the UTC indicator. michael@0: * For example, "-0500", "+052538", and "Z"(UTC). michael@0: * This style is equivalent to the LDML date format pattern "XXXX". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_BASIC_FULL, michael@0: /** michael@0: * ISO 8601 local time difference (basic format) with optional seconds field. michael@0: * For example, "-0500" and "+052538". michael@0: * This style is equivalent to the LDML date format pattern "xxxx". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_BASIC_LOCAL_FULL, michael@0: /** michael@0: * Fixed width ISO 8601 local time difference (extended format) or the UTC indicator. michael@0: * For example, "-05:00", "+05:30", and "Z"(UTC). michael@0: * This style is equivalent to the LDML date format pattern "XXX". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_EXTENDED_FIXED, michael@0: /** michael@0: * Fixed width ISO 8601 local time difference (extended format). michael@0: * For example, "-05:00" and "+05:30". michael@0: * This style is equivalent to the LDML date format pattern "xxx" and "ZZZZZ". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_EXTENDED_LOCAL_FIXED, michael@0: /** michael@0: * ISO 8601 local time difference (extended format) with optional seconds field, or the UTC indicator. michael@0: * For example, "-05:00", "+05:25:38", and "Z"(UTC). michael@0: * This style is equivalent to the LDML date format pattern "XXXXX". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_EXTENDED_FULL, michael@0: /** michael@0: * ISO 8601 local time difference (extended format) with optional seconds field. michael@0: * For example, "-05:00" and "+05:25:38". michael@0: * This style is equivalent to the LDML date format pattern "xxxxx". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ISO_EXTENDED_LOCAL_FULL, michael@0: /** michael@0: * Time Zone ID, such as "America/Los_Angeles". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ZONE_ID, michael@0: /** michael@0: * Short Time Zone ID (BCP 47 Unicode location extension, time zone type value), such as "uslax". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_ZONE_ID_SHORT, michael@0: /** michael@0: * Exemplar location, such as "Los Angeles" and "Paris". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_STYLE_EXEMPLAR_LOCATION michael@0: #endif /* U_HIDE_DRAFT_API */ michael@0: } UTimeZoneFormatStyle; michael@0: michael@0: /** michael@0: * Constants for GMT offset pattern types. michael@0: * @stable ICU 50 michael@0: */ michael@0: typedef enum UTimeZoneFormatGMTOffsetPatternType { michael@0: /** michael@0: * Positive offset with hours and minutes fields michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_PAT_POSITIVE_HM, michael@0: /** michael@0: * Positive offset with hours, minutes and seconds fields michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_PAT_POSITIVE_HMS, michael@0: /** michael@0: * Negative offset with hours and minutes fields michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_PAT_NEGATIVE_HM, michael@0: /** michael@0: * Negative offset with hours, minutes and seconds fields michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_PAT_NEGATIVE_HMS, michael@0: #ifndef U_HIDE_DRAFT_API michael@0: /** michael@0: * Positive offset with hours field michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_PAT_POSITIVE_H, michael@0: /** michael@0: * Negative offset with hours field michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZFMT_PAT_NEGATIVE_H, michael@0: #endif /* U_HIDE_DRAFT_API */ michael@0: michael@0: /** michael@0: * Number of UTimeZoneFormatGMTOffsetPatternType types. michael@0: * @internal michael@0: */ michael@0: UTZFMT_PAT_COUNT = 6 michael@0: } UTimeZoneFormatGMTOffsetPatternType; michael@0: michael@0: /** michael@0: * Constants for time types used by TimeZoneFormat APIs for michael@0: * receiving time type (standard time, daylight time or unknown). michael@0: * @stable ICU 50 michael@0: */ michael@0: typedef enum UTimeZoneFormatTimeType { michael@0: /** michael@0: * Unknown michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_TIME_TYPE_UNKNOWN, michael@0: /** michael@0: * Standard time michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_TIME_TYPE_STANDARD, michael@0: /** michael@0: * Daylight saving time michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_TIME_TYPE_DAYLIGHT michael@0: } UTimeZoneFormatTimeType; michael@0: michael@0: /** michael@0: * Constants for parse option flags, used for specifying optional parse behavior. michael@0: * @stable ICU 50 michael@0: */ michael@0: typedef enum UTimeZoneFormatParseOption { michael@0: /** michael@0: * No option. michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_PARSE_OPTION_NONE = 0x00, michael@0: /** michael@0: * When a time zone display name is not found within a set of display names michael@0: * used for the specified style, look for the name from display names used michael@0: * by other styles. michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZFMT_PARSE_OPTION_ALL_STYLES = 0x01 michael@0: } UTimeZoneFormatParseOption; michael@0: michael@0: U_CDECL_END michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: class TimeZoneGenericNames; michael@0: class UVector; michael@0: michael@0: /** michael@0: * TimeZoneFormat supports time zone display name formatting and parsing. michael@0: * An instance of TimeZoneFormat works as a subformatter of {@link SimpleDateFormat}, michael@0: * but you can also directly get a new instance of TimeZoneFormat and michael@0: * formatting/parsing time zone display names. michael@0: *

michael@0: * ICU implements the time zone display names defined by UTS#35 michael@0: * Unicode Locale Data Markup Language (LDML). {@link TimeZoneNames} represents the michael@0: * time zone display name data model and this class implements the algorithm for actual michael@0: * formatting and parsing. michael@0: * michael@0: * @see SimpleDateFormat michael@0: * @see TimeZoneNames michael@0: * @stable ICU 50 michael@0: */ michael@0: class U_I18N_API TimeZoneFormat : public Format { michael@0: public: michael@0: /** michael@0: * Copy constructor. michael@0: * @stable ICU 50 michael@0: */ michael@0: TimeZoneFormat(const TimeZoneFormat& other); michael@0: michael@0: /** michael@0: * Destructor. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual ~TimeZoneFormat(); michael@0: michael@0: /** michael@0: * Assignment operator. michael@0: * @stable ICU 50 michael@0: */ michael@0: TimeZoneFormat& operator=(const TimeZoneFormat& other); michael@0: michael@0: /** michael@0: * Return true if the given Format objects are semantically equal. michael@0: * Objects of different subclasses are considered unequal. michael@0: * @param other The object to be compared with. michael@0: * @return Return TRUE if the given Format objects are semantically equal. michael@0: * Objects of different subclasses are considered unequal. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UBool operator==(const Format& other) const; michael@0: michael@0: /** michael@0: * Clone this object polymorphically. The caller is responsible michael@0: * for deleting the result when done. michael@0: * @return A copy of the object michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual Format* clone() const; michael@0: michael@0: /** michael@0: * Creates an instance of TimeZoneFormat for the given locale. michael@0: * @param locale The locale. michael@0: * @param status Recevies the status. michael@0: * @return An instance of TimeZoneFormat for the given locale, michael@0: * owned by the caller. michael@0: * @stable ICU 50 michael@0: */ michael@0: static TimeZoneFormat* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status); michael@0: michael@0: /** michael@0: * Returns the time zone display name data used by this instance. michael@0: * @return The time zone display name data. michael@0: * @stable ICU 50 michael@0: */ michael@0: const TimeZoneNames* getTimeZoneNames() const; michael@0: michael@0: /** michael@0: * Sets the time zone display name data to this format instnace. michael@0: * The caller should not delete the TimeZoenNames object after it is adopted michael@0: * by this call. michael@0: * @param tznames TimeZoneNames object to be adopted. michael@0: * @stable ICU 50 michael@0: */ michael@0: void adoptTimeZoneNames(TimeZoneNames *tznames); michael@0: michael@0: /** michael@0: * Sets the time zone display name data to this format instnace. michael@0: * @param tznames TimeZoneNames object to be set. michael@0: * @stable ICU 50 michael@0: */ michael@0: void setTimeZoneNames(const TimeZoneNames &tznames); michael@0: michael@0: /** michael@0: * Returns the localized GMT format pattern. michael@0: * @param pattern Receives the localized GMT format pattern. michael@0: * @return A reference to the result pattern. michael@0: * @see #setGMTPattern michael@0: * @stable ICU 50 michael@0: */ michael@0: UnicodeString& getGMTPattern(UnicodeString& pattern) const; michael@0: michael@0: /** michael@0: * Sets the localized GMT format pattern. The pattern must contain michael@0: * a single argument {0}, for example "GMT {0}". michael@0: * @param pattern The localized GMT format pattern to be used by this object. michael@0: * @param status Recieves the status. michael@0: * @see #getGMTPattern michael@0: * @stable ICU 50 michael@0: */ michael@0: void setGMTPattern(const UnicodeString& pattern, UErrorCode& status); michael@0: michael@0: /** michael@0: * Returns the offset pattern used for localized GMT format. michael@0: * @param type The offset pattern type enum. michael@0: * @param pattern Receives the offset pattern. michael@0: * @return A reference to the result pattern. michael@0: * @see #setGMTOffsetPattern michael@0: * @stable ICU 50 michael@0: */ michael@0: UnicodeString& getGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, UnicodeString& pattern) const; michael@0: michael@0: /** michael@0: * Sets the offset pattern for the given offset type. michael@0: * @param type The offset pattern type enum. michael@0: * @param pattern The offset pattern used for localized GMT format for the type. michael@0: * @param status Receives the status. michael@0: * @see #getGMTOffsetPattern michael@0: * @stable ICU 50 michael@0: */ michael@0: void setGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, const UnicodeString& pattern, UErrorCode& status); michael@0: michael@0: /** michael@0: * Returns the decimal digit characters used for localized GMT format. michael@0: * The return string contains exactly 10 code points (may include Unicode michael@0: * supplementary character) representing digit 0 to digit 9 in the ascending michael@0: * order. michael@0: * @param digits Receives the decimal digits used for localized GMT format. michael@0: * @see #setGMTOffsetDigits michael@0: * @stable ICU 50 michael@0: */ michael@0: UnicodeString& getGMTOffsetDigits(UnicodeString& digits) const; michael@0: michael@0: /** michael@0: * Sets the decimal digit characters used for localized GMT format. michael@0: * The input digits must contain exactly 10 code points michael@0: * (Unicode supplementary characters are also allowed) representing michael@0: * digit 0 to digit 9 in the ascending order. When the input digits michael@0: * does not satisfy the condition, U_ILLEGAL_ARGUMENT_ERROR michael@0: * will be set to the return status. michael@0: * @param digits The decimal digits used for localized GMT format. michael@0: * @param status Receives the status. michael@0: * @see #getGMTOffsetDigits michael@0: * @stable ICU 50 michael@0: */ michael@0: void setGMTOffsetDigits(const UnicodeString& digits, UErrorCode& status); michael@0: michael@0: /** michael@0: * Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0). michael@0: * @param gmtZeroFormat Receives the localized GMT string string for GMT(UTC) itself. michael@0: * @return A reference to the result GMT string. michael@0: * @see #setGMTZeroFormat michael@0: * @stable ICU 50 michael@0: */ michael@0: UnicodeString& getGMTZeroFormat(UnicodeString& gmtZeroFormat) const; michael@0: michael@0: /** michael@0: * Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0). michael@0: * @param gmtZeroFormat The localized GMT format string for GMT(UTC). michael@0: * @param status Receives the status. michael@0: * @see #getGMTZeroFormat michael@0: * @stable ICU 50 michael@0: */ michael@0: void setGMTZeroFormat(const UnicodeString& gmtZeroFormat, UErrorCode& status); michael@0: michael@0: /** michael@0: * Returns the bitwise flags of UTimeZoneFormatParseOption representing the default parse michael@0: * options used by this object. michael@0: * @return the default parse options. michael@0: * @see ParseOption michael@0: * @stable ICU 50 michael@0: */ michael@0: uint32_t getDefaultParseOptions(void) const; michael@0: michael@0: /** michael@0: * Sets the default parse options. michael@0: *

Note: By default, an instance of TimeZoneFormat michael@0: * created by {@link #createInstance} has no parse options set (UTZFMT_PARSE_OPTION_NONE). michael@0: * To specify multipe options, use bitwise flags of UTimeZoneFormatParseOption. michael@0: * @see #UTimeZoneFormatParseOption michael@0: * @stable ICU 50 michael@0: */ michael@0: void setDefaultParseOptions(uint32_t flags); michael@0: michael@0: #ifndef U_HIDE_DRAFT_API michael@0: /** michael@0: * Returns the ISO 8601 basic time zone string for the given offset. michael@0: * For example, "-08", "-0830" and "Z" michael@0: * michael@0: * @param offset the offset from GMT(UTC) in milliseconds. michael@0: * @param useUtcIndicator true if ISO 8601 UTC indicator "Z" is used when the offset is 0. michael@0: * @param isShort true if shortest form is used. michael@0: * @param ignoreSeconds true if non-zero offset seconds is appended. michael@0: * @param result Receives the ISO format string. michael@0: * @param status Receives the status michael@0: * @return the ISO 8601 basic format. michael@0: * @see #formatOffsetISO8601Extended michael@0: * @see #parseOffsetISO8601 michael@0: * @draft ICU 51 michael@0: */ michael@0: UnicodeString& formatOffsetISO8601Basic(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds, michael@0: UnicodeString& result, UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Returns the ISO 8601 extended time zone string for the given offset. michael@0: * For example, "-08:00", "-08:30" and "Z" michael@0: * michael@0: * @param offset the offset from GMT(UTC) in milliseconds. michael@0: * @param useUtcIndicator true if ISO 8601 UTC indicator "Z" is used when the offset is 0. michael@0: * @param isShort true if shortest form is used. michael@0: * @param ignoreSeconds true if non-zero offset seconds is appended. michael@0: * @param result Receives the ISO format string. michael@0: * @param status Receives the status michael@0: * @return the ISO 8601 basic format. michael@0: * @see #formatOffsetISO8601Extended michael@0: * @see #parseOffsetISO8601 michael@0: * @draft ICU 51 michael@0: */ michael@0: UnicodeString& formatOffsetISO8601Extended(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds, michael@0: UnicodeString& result, UErrorCode& status) const; michael@0: #endif /* U_HIDE_DRAFT_API */ michael@0: michael@0: /** michael@0: * Returns the localized GMT(UTC) offset format for the given offset. michael@0: * The localized GMT offset is defined by; michael@0: *

michael@0: * This format always uses 2 digit hours and minutes. When the given offset has non-zero michael@0: * seconds, 2 digit seconds field will be appended. For example, michael@0: * GMT+05:00 and GMT+05:28:06. michael@0: * @param offset the offset from GMT(UTC) in milliseconds. michael@0: * @param status Receives the status michael@0: * @param result Receives the localized GMT format string. michael@0: * @return A reference to the result. michael@0: * @see #parseOffsetLocalizedGMT michael@0: * @stable ICU 50 michael@0: */ michael@0: UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const; michael@0: michael@0: #ifndef U_HIDE_DRAFT_API michael@0: /** michael@0: * Returns the short localized GMT(UTC) offset format for the given offset. michael@0: * The short localized GMT offset is defined by; michael@0: * michael@0: * This format uses the shortest representation of offset. The hours field does not michael@0: * have leading zero and lower fields with zero will be truncated. For example, michael@0: * GMT+5 and GMT+530. michael@0: * @param offset the offset from GMT(UTC) in milliseconds. michael@0: * @param status Receives the status michael@0: * @param result Receives the short localized GMT format string. michael@0: * @return A reference to the result. michael@0: * @see #parseOffsetShortLocalizedGMT michael@0: * @draft ICU 51 michael@0: */ michael@0: UnicodeString& formatOffsetShortLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const; michael@0: #endif /* U_HIDE_DRAFT_API */ michael@0: michael@0: using Format::format; michael@0: michael@0: /** michael@0: * Returns the display name of the time zone at the given date for the style. michael@0: * @param style The style (e.g. UTZFMT_STYLE_GENERIC_LONG, UTZFMT_STYLE_LOCALIZED_GMT...) michael@0: * @param tz The time zone. michael@0: * @param date The date. michael@0: * @param name Receives the display name. michael@0: * @param timeType the output argument for receiving the time type (standard/daylight/unknown) michael@0: * used for the display name, or NULL if the information is not necessary. michael@0: * @return A reference to the result michael@0: * @see #UTimeZoneFormatStyle michael@0: * @see #UTimeZoneFormatTimeType michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UnicodeString& format(UTimeZoneFormatStyle style, const TimeZone& tz, UDate date, michael@0: UnicodeString& name, UTimeZoneFormatTimeType* timeType = NULL) const; michael@0: michael@0: /** michael@0: * Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 michael@0: * style time zone string. When the given string is not an ISO 8601 time zone michael@0: * string, this method sets the current position as the error index michael@0: * to ParsePosition pos and returns 0. michael@0: * @param text The text contains ISO8601 style time zone string (e.g. "-08:00", "Z") michael@0: * at the position. michael@0: * @param pos The ParsePosition object. michael@0: * @return The offset from GMT(UTC) in milliseconds for the given ISO 8601 style michael@0: * time zone string. michael@0: * @see #formatOffsetISO8601Basic michael@0: * @see #formatOffsetISO8601Extended michael@0: * @stable ICU 50 michael@0: */ michael@0: int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos) const; michael@0: michael@0: /** michael@0: * Returns offset from GMT(UTC) in milliseconds for the given localized GMT michael@0: * offset format string. When the given string cannot be parsed, this method michael@0: * sets the current position as the error index to ParsePosition pos michael@0: * and returns 0. michael@0: * @param text The text contains a localized GMT offset string at the position. michael@0: * @param pos The ParsePosition object. michael@0: * @return The offset from GMT(UTC) in milliseconds for the given localized GMT michael@0: * offset format string. michael@0: * @see #formatOffsetLocalizedGMT michael@0: * @stable ICU 50 michael@0: */ michael@0: int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const; michael@0: michael@0: #ifndef U_HIDE_DRAFT_API michael@0: /** michael@0: * Returns offset from GMT(UTC) in milliseconds for the given short localized GMT michael@0: * offset format string. When the given string cannot be parsed, this method michael@0: * sets the current position as the error index to ParsePosition pos michael@0: * and returns 0. michael@0: * @param text The text contains a short localized GMT offset string at the position. michael@0: * @param pos The ParsePosition object. michael@0: * @return The offset from GMT(UTC) in milliseconds for the given short localized GMT michael@0: * offset format string. michael@0: * @see #formatOffsetShortLocalizedGMT michael@0: * @draft ICU 51 michael@0: */ michael@0: int32_t parseOffsetShortLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const; michael@0: #endif /* U_HIDE_DRAFT_API */ michael@0: michael@0: /** michael@0: * Returns a TimeZone by parsing the time zone string according to michael@0: * the given parse position, the specified format style and parse options. michael@0: * michael@0: * @param text The text contains a time zone string at the position. michael@0: * @param style The format style michael@0: * @param pos The position. michael@0: * @param parseOptions The parse options repesented by bitwise flags of UTimeZoneFormatParseOption. michael@0: * @param timeType The output argument for receiving the time type (standard/daylight/unknown), michael@0: * or NULL if the information is not necessary. michael@0: * @return A TimeZone, or null if the input could not be parsed. michael@0: * @see UTimeZoneFormatStyle michael@0: * @see UTimeZoneFormatParseOption michael@0: * @see UTimeZoneFormatTimeType michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos, michael@0: int32_t parseOptions, UTimeZoneFormatTimeType* timeType = NULL) const; michael@0: michael@0: /** michael@0: * Returns a TimeZone by parsing the time zone string according to michael@0: * the given parse position, the specified format style and the default parse options. michael@0: * michael@0: * @param text The text contains a time zone string at the position. michael@0: * @param style The format style michael@0: * @param pos The position. michael@0: * @param timeType The output argument for receiving the time type (standard/daylight/unknown), michael@0: * or NULL if the information is not necessary. michael@0: * @return A TimeZone, or null if the input could not be parsed. michael@0: * @see UTimeZoneFormatStyle michael@0: * @see UTimeZoneFormatParseOption michael@0: * @see UTimeZoneFormatTimeType michael@0: * @stable ICU 50 michael@0: */ michael@0: TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos, michael@0: UTimeZoneFormatTimeType* timeType = NULL) const; michael@0: michael@0: /* ---------------------------------------------- michael@0: * Format APIs michael@0: * ---------------------------------------------- */ michael@0: michael@0: /** michael@0: * Format an object to produce a time zone display string using localized GMT offset format. michael@0: * This method handles Formattable objects with a TimeZone. If a the Formattable michael@0: * object type is not a TimeZone, then it returns a failing UErrorCode. michael@0: * @param obj The object to format. Must be a TimeZone. michael@0: * @param appendTo Output parameter to receive result. Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. On output: the offsets of the alignment field. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UnicodeString& format(const Formattable& obj, UnicodeString& appendTo, michael@0: FieldPosition& pos, UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Parse a string to produce an object. This methods handles parsing of michael@0: * time zone display strings into Formattable objects with TimeZone. michael@0: * @param source The string to be parsed into an object. michael@0: * @param result Formattable to be set to the parse result. If parse fails, return contents are undefined. michael@0: * @param parse_pos The position to start parsing at. Upon return this param is set to the position after the michael@0: * last character successfully parsed. If the source is not parsed successfully, this param michael@0: * will remain unchanged. michael@0: * @return A newly created Formattable* object, or NULL on failure. The caller owns this and should michael@0: * delete it when done. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const; michael@0: michael@0: /** michael@0: * ICU "poor man's RTTI", returns a UClassID for this class. michael@0: * @stable ICU 50 michael@0: */ michael@0: static UClassID U_EXPORT2 getStaticClassID(void); michael@0: michael@0: /** michael@0: * ICU "poor man's RTTI", returns a UClassID for the actual class. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UClassID getDynamicClassID() const; michael@0: michael@0: protected: michael@0: /** michael@0: * Constructs a TimeZoneFormat object for the specified locale. michael@0: * @param locale the locale michael@0: * @param status receives the status. michael@0: * @stable ICU 50 michael@0: */ michael@0: TimeZoneFormat(const Locale& locale, UErrorCode& status); michael@0: michael@0: private: michael@0: /* Locale of this object */ michael@0: Locale fLocale; michael@0: michael@0: /* Stores the region (could be implicit default) */ michael@0: char fTargetRegion[ULOC_COUNTRY_CAPACITY]; michael@0: michael@0: /* TimeZoneNames object used by this formatter */ michael@0: TimeZoneNames* fTimeZoneNames; michael@0: michael@0: /* TimeZoneGenericNames object used by this formatter - lazily instantiated */ michael@0: TimeZoneGenericNames* fTimeZoneGenericNames; michael@0: michael@0: /* Localized GMT format pattern - e.g. "GMT{0}" */ michael@0: UnicodeString fGMTPattern; michael@0: michael@0: /* Array of offset patterns used by Localized GMT format - e.g. "+HH:mm" */ michael@0: UnicodeString fGMTOffsetPatterns[UTZFMT_PAT_COUNT]; michael@0: michael@0: /* Localized decimal digits used by Localized GMT format */ michael@0: UChar32 fGMTOffsetDigits[10]; michael@0: michael@0: /* Localized GMT zero format - e.g. "GMT" */ michael@0: UnicodeString fGMTZeroFormat; michael@0: michael@0: /* Bit flags representing parse options */ michael@0: uint32_t fDefParseOptionFlags; michael@0: michael@0: /* Constant parts of GMT format pattern, populated from localized GMT format pattern*/ michael@0: UnicodeString fGMTPatternPrefix; /* Substring before {0} */ michael@0: UnicodeString fGMTPatternSuffix; /* Substring after {0} */ michael@0: michael@0: /* Compiled offset patterns generated from fGMTOffsetPatterns[] */ michael@0: UVector* fGMTOffsetPatternItems[UTZFMT_PAT_COUNT]; michael@0: michael@0: UBool fAbuttingOffsetHoursAndMinutes; michael@0: michael@0: /** michael@0: * Returns the time zone's specific format string. michael@0: * @param tz the time zone michael@0: * @param stdType the name type used for standard time michael@0: * @param dstType the name type used for daylight time michael@0: * @param date the date michael@0: * @param name receives the time zone's specific format name string michael@0: * @param timeType when null, actual time type is set michael@0: * @return a reference to name. michael@0: */ michael@0: UnicodeString& formatSpecific(const TimeZone& tz, UTimeZoneNameType stdType, UTimeZoneNameType dstType, michael@0: UDate date, UnicodeString& name, UTimeZoneFormatTimeType *timeType) const; michael@0: michael@0: /** michael@0: * Returns the time zone's generic format string. michael@0: * @param tz the time zone michael@0: * @param genType the generic name type michael@0: * @param date the date michael@0: * @param name receives the time zone's generic format name string michael@0: * @return a reference to name. michael@0: */ michael@0: UnicodeString& formatGeneric(const TimeZone& tz, int32_t genType, UDate date, UnicodeString& name) const; michael@0: michael@0: /** michael@0: * Lazily create a TimeZoneGenericNames instance michael@0: * @param status receives the status michael@0: * @return the cached TimeZoneGenericNames. michael@0: */ michael@0: const TimeZoneGenericNames* getTimeZoneGenericNames(UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Private method returning the time zone's exemplar location string. michael@0: * This method will never return empty. michael@0: * @param tz the time zone michael@0: * @param name receives the time zone's exemplar location name michael@0: * @return a reference to name. michael@0: */ michael@0: UnicodeString& formatExemplarLocation(const TimeZone& tz, UnicodeString& name) const; michael@0: michael@0: /** michael@0: * Private enum specifying a combination of offset fields michael@0: */ michael@0: enum OffsetFields { michael@0: FIELDS_H, michael@0: FIELDS_HM, michael@0: FIELDS_HMS michael@0: }; michael@0: michael@0: /** michael@0: * Parses the localized GMT pattern string and initialize michael@0: * localized gmt pattern fields. michael@0: * @param gmtPattern the localized GMT pattern string such as "GMT {0}" michael@0: * @param status U_ILLEGAL_ARGUMENT_ERROR is set when the specified pattern does not michael@0: * contain an argument "{0}". michael@0: */ michael@0: void initGMTPattern(const UnicodeString& gmtPattern, UErrorCode& status); michael@0: michael@0: /** michael@0: * Parse the GMT offset pattern into runtime optimized format. michael@0: * @param pattern the offset pattern string michael@0: * @param required the required set of fields, such as FIELDS_HM michael@0: * @param status U_ILLEGAL_ARGUMENT is set when the specified pattern does not contain michael@0: * pattern letters for the required fields. michael@0: * @return A list of GMTOffsetField objects, or NULL on error. michael@0: */ michael@0: static UVector* parseOffsetPattern(const UnicodeString& pattern, OffsetFields required, UErrorCode& status); michael@0: michael@0: /** michael@0: * Appends seconds field to the offset pattern with hour/minute michael@0: * Note: This code will be obsoleted once we add hour-minute-second pattern data in CLDR. michael@0: * @param offsetHM the offset pattern including hours and minutes fields michael@0: * @param result the output offset pattern including hour, minute and seconds fields michael@0: * @param status receives the status michael@0: * @return a reference to result michael@0: */ michael@0: static UnicodeString& expandOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status); michael@0: michael@0: /** michael@0: * Truncates minutes field to the offset pattern with hour/minute michael@0: * Note: This code will be obsoleted once we add hour pattern data in CLDR. michael@0: * @param offsetHM the offset pattern including hours and minutes fields michael@0: * @param result the output offset pattern including only hours field michael@0: * @param status receives the status michael@0: * @return a reference to result michael@0: */ michael@0: static UnicodeString& truncateOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status); michael@0: michael@0: /** michael@0: * Break input string into UChar32[]. Each array element represents michael@0: * a code point. This method is used for parsing localized digit michael@0: * characters and support characters in Unicode supplemental planes. michael@0: * @param str the string michael@0: * @param codeArray receives the result michael@0: * @param capacity the capacity of codeArray michael@0: * @return TRUE when the specified code array is fully filled with code points michael@0: * (no under/overflow). michael@0: */ michael@0: static UBool toCodePoints(const UnicodeString& str, UChar32* codeArray, int32_t capacity); michael@0: michael@0: /** michael@0: * Private method supprting all of ISO8601 formats michael@0: * @param offset the offset from GMT(UTC) in milliseconds. michael@0: * @param useUtcIndicator true if ISO 8601 UTC indicator "Z" is used when the offset is 0. michael@0: * @param isShort true if shortest form is used. michael@0: * @param ignoreSeconds true if non-zero offset seconds is appended. michael@0: * @param result Receives the result michael@0: * @param status Receives the status michael@0: * @return the ISO 8601 basic format. michael@0: */ michael@0: UnicodeString& formatOffsetISO8601(int32_t offset, UBool isBasic, UBool useUtcIndicator, michael@0: UBool isShort, UBool ignoreSeconds, UnicodeString& result, UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Private method used for localized GMT formatting. michael@0: * @param offset the zone's UTC offset michael@0: * @param isShort true if the short localized GMT format is desired. michael@0: * @param result receives the localized GMT format string michael@0: * @param status receives the status michael@0: */ michael@0: UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UBool isShort, UnicodeString& result, UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 style michael@0: * (extended format) time zone string. When the given string is not an ISO 8601 time michael@0: * zone string, this method sets the current position as the error index michael@0: * to ParsePosition pos and returns 0. michael@0: * @param text the text contains ISO 8601 style time zone string (e.g. "-08:00", "Z") michael@0: * at the position. michael@0: * @param pos the position, non-negative error index will be set on failure. michael@0: * @param extendedOnly TRUE if parsing the text as ISO 8601 extended offset format (e.g. "-08:00"), michael@0: * or FALSE to evaluate the text as basic format. michael@0: * @param hasDigitOffset receiving if the parsed zone string contains offset digits. michael@0: * @return the offset from GMT(UTC) in milliseconds for the given ISO 8601 style michael@0: * time zone string. michael@0: */ michael@0: int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos, UBool extendedOnly, michael@0: UBool* hasDigitOffset = NULL) const; michael@0: michael@0: /** michael@0: * Appends localized digits to the buffer. michael@0: * This code assumes that the input number is 0 - 59 michael@0: * @param buf the target buffer michael@0: * @param n the integer number michael@0: * @param minDigits the minimum digits width michael@0: */ michael@0: void appendOffsetDigits(UnicodeString& buf, int32_t n, uint8_t minDigits) const; michael@0: michael@0: /** michael@0: * Returns offset from GMT(UTC) in milliseconds for the given localized GMT michael@0: * offset format string. When the given string cannot be parsed, this method michael@0: * sets the current position as the error index to ParsePosition pos michael@0: * and returns 0. michael@0: * @param text the text contains a localized GMT offset string at the position. michael@0: * @param pos the position, non-negative error index will be set on failure. michael@0: * @param isShort true if this parser to try the short format first michael@0: * @param hasDigitOffset receiving if the parsed zone string contains offset digits. michael@0: * @return the offset from GMT(UTC) in milliseconds for the given localized GMT michael@0: * offset format string. michael@0: */ michael@0: int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos, michael@0: UBool isShort, UBool* hasDigitOffset) const; michael@0: michael@0: /** michael@0: * Parse localized GMT format generated by the patter used by this formatter, except michael@0: * GMT Zero format. michael@0: * @param text the input text michael@0: * @param start the start index michael@0: * @param isShort true if the short localized format is parsed. michael@0: * @param parsedLen receives the parsed length michael@0: * @return the parsed offset in milliseconds michael@0: */ michael@0: int32_t parseOffsetLocalizedGMTPattern(const UnicodeString& text, int32_t start, michael@0: UBool isShort, int32_t& parsedLen) const; michael@0: michael@0: /** michael@0: * Parses localized GMT offset fields into offset. michael@0: * @param text the input text michael@0: * @param start the start index michael@0: * @param isShort true if this is a short format - currently not used michael@0: * @param parsedLen the parsed length, or 0 on failure. michael@0: * @return the parsed offset in milliseconds. michael@0: */ michael@0: int32_t parseOffsetFields(const UnicodeString& text, int32_t start, UBool isShort, int32_t& parsedLen) const; michael@0: michael@0: /** michael@0: * Parse localized GMT offset fields with the given pattern. michael@0: * @param text the input text michael@0: * @param start the start index michael@0: * @param pattenItems the pattern (already itemized) michael@0: * @param forceSingleHourDigit true if hours field is parsed as a single digit michael@0: * @param hour receives the hour offset field michael@0: * @param min receives the minute offset field michael@0: * @param sec receives the second offset field michael@0: * @return the parsed length michael@0: */ michael@0: int32_t parseOffsetFieldsWithPattern(const UnicodeString& text, int32_t start, michael@0: UVector* patternItems, UBool forceSingleHourDigit, int32_t& hour, int32_t& min, int32_t& sec) const; michael@0: michael@0: /** michael@0: * Parses abutting localized GMT offset fields (such as 0800) into offset. michael@0: * @param text the input text michael@0: * @param start the start index michael@0: * @param parsedLen the parsed length, or 0 on failure michael@0: * @return the parsed offset in milliseconds. michael@0: */ michael@0: int32_t parseAbuttingOffsetFields(const UnicodeString& text, int32_t start, int32_t& parsedLen) const; michael@0: michael@0: /** michael@0: * Parses the input text using the default format patterns (e.g. "UTC{0}"). michael@0: * @param text the input text michael@0: * @param start the start index michael@0: * @param parsedLen the parsed length, or 0 on failure michael@0: * @return the parsed offset in milliseconds. michael@0: */ michael@0: int32_t parseOffsetDefaultLocalizedGMT(const UnicodeString& text, int start, int32_t& parsedLen) const; michael@0: michael@0: /** michael@0: * Parses the input GMT offset fields with the default offset pattern. michael@0: * @param text the input text michael@0: * @param start the start index michael@0: * @param separator the separator character, e.g. ':' michael@0: * @param parsedLen the parsed length, or 0 on failure. michael@0: * @return the parsed offset in milliseconds. michael@0: */ michael@0: int32_t parseDefaultOffsetFields(const UnicodeString& text, int32_t start, UChar separator, michael@0: int32_t& parsedLen) const; michael@0: michael@0: /** michael@0: * Reads an offset field value. This method will stop parsing when michael@0: * 1) number of digits reaches maxDigits michael@0: * 2) just before already parsed number exceeds maxVal michael@0: * michael@0: * @param text the text michael@0: * @param start the start offset michael@0: * @param minDigits the minimum number of required digits michael@0: * @param maxDigits the maximum number of digits michael@0: * @param minVal the minimum value michael@0: * @param maxVal the maximum value michael@0: * @param parsedLen the actual parsed length. michael@0: * @return the integer value parsed michael@0: */ michael@0: int32_t parseOffsetFieldWithLocalizedDigits(const UnicodeString& text, int32_t start, michael@0: uint8_t minDigits, uint8_t maxDigits, uint16_t minVal, uint16_t maxVal, int32_t& parsedLen) const; michael@0: michael@0: /** michael@0: * Reads a single decimal digit, either localized digits used by this object michael@0: * or any Unicode numeric character. michael@0: * @param text the text michael@0: * @param start the start index michael@0: * @param len the actual length read from the text michael@0: * the start index is not a decimal number. michael@0: * @return the integer value of the parsed digit, or -1 on failure. michael@0: */ michael@0: int32_t parseSingleLocalizedDigit(const UnicodeString& text, int32_t start, int32_t& len) const; michael@0: michael@0: /** michael@0: * Formats offset using ASCII digits. The input offset range must be michael@0: * within +/-24 hours (exclusive). michael@0: * @param offset The offset michael@0: * @param sep The field separator character or 0 if not required michael@0: * @param minFields The minimum fields michael@0: * @param maxFields The maximum fields michael@0: * @return The offset string michael@0: */ michael@0: static UnicodeString& formatOffsetWithAsciiDigits(int32_t offset, UChar sep, michael@0: OffsetFields minFields, OffsetFields maxFields, UnicodeString& result); michael@0: michael@0: /** michael@0: * Parses offset represented by contiguous ASCII digits. michael@0: *

michael@0: * Note: This method expects the input position is already at the start of michael@0: * ASCII digits and does not parse sign (+/-). michael@0: * @param text The text contains a sequence of ASCII digits michael@0: * @param pos The parse position michael@0: * @param minFields The minimum Fields to be parsed michael@0: * @param maxFields The maximum Fields to be parsed michael@0: * @param fixedHourWidth true if hours field must be width of 2 michael@0: * @return Parsed offset, 0 or positive number. michael@0: */ michael@0: static int32_t parseAbuttingAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, michael@0: OffsetFields minFields, OffsetFields maxFields, UBool fixedHourWidth); michael@0: michael@0: /** michael@0: * Parses offset represented by ASCII digits and separators. michael@0: *

michael@0: * Note: This method expects the input position is already at the start of michael@0: * ASCII digits and does not parse sign (+/-). michael@0: * @param text The text michael@0: * @param pos The parse position michael@0: * @param sep The separator character michael@0: * @param minFields The minimum Fields to be parsed michael@0: * @param maxFields The maximum Fields to be parsed michael@0: * @return Parsed offset, 0 or positive number. michael@0: */ michael@0: static int32_t parseAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, UChar sep, michael@0: OffsetFields minFields, OffsetFields maxFields); michael@0: michael@0: /** michael@0: * Unquotes the message format style pattern. michael@0: * @param pattern the pattern michael@0: * @param result receive the unquoted pattern. michael@0: * @return A reference to result. michael@0: */ michael@0: static UnicodeString& unquote(const UnicodeString& pattern, UnicodeString& result); michael@0: michael@0: /** michael@0: * Initialize localized GMT format offset hour/min/sec patterns. michael@0: * This method parses patterns into optimized run-time format. michael@0: * @param status receives the status. michael@0: */ michael@0: void initGMTOffsetPatterns(UErrorCode& status); michael@0: michael@0: /** michael@0: * Check if there are any GMT format offset patterns without michael@0: * any separators between hours field and minutes field and update michael@0: * fAbuttingOffsetHoursAndMinutes field. This method must be called michael@0: * after all patterns are parsed into pattern items. michael@0: */ michael@0: void checkAbuttingHoursAndMinutes(); michael@0: michael@0: /** michael@0: * Creates an instance of TimeZone for the given offset michael@0: * @param offset the offset michael@0: * @return A TimeZone with the given offset michael@0: */ michael@0: TimeZone* createTimeZoneForOffset(int32_t offset) const; michael@0: michael@0: /** michael@0: * Returns the time type for the given name type michael@0: * @param nameType the name type michael@0: * @return the time type (unknown/standard/daylight) michael@0: */ michael@0: static UTimeZoneFormatTimeType getTimeType(UTimeZoneNameType nameType); michael@0: michael@0: /** michael@0: * Returns the time zone ID of a match at the specified index within michael@0: * the MatchInfoCollection. michael@0: * @param matches the collection of matches michael@0: * @param idx the index withing matches michael@0: * @param tzID receives the resolved time zone ID michael@0: * @return a reference to tzID. michael@0: */ michael@0: UnicodeString& getTimeZoneID(const TimeZoneNames::MatchInfoCollection* matches, int32_t idx, UnicodeString& tzID) const; michael@0: michael@0: michael@0: /** michael@0: * Parse a zone ID. michael@0: * @param text the text contains a time zone ID string at the position. michael@0: * @param pos the position michael@0: * @param tzID receives the zone ID michael@0: * @return a reference to tzID michael@0: */ michael@0: UnicodeString& parseZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const; michael@0: michael@0: /** michael@0: * Parse a short zone ID. michael@0: * @param text the text contains a short time zone ID string at the position. michael@0: * @param pos the position michael@0: * @param tzID receives the short zone ID michael@0: * @return a reference to tzID michael@0: */ michael@0: UnicodeString& parseShortZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const; michael@0: michael@0: /** michael@0: * Parse an exemplar location string. michael@0: * @param text the text contains an exemplar location string at the position. michael@0: * @param pos the position. michael@0: * @param tzID receives the time zone ID michael@0: * @return a reference to tzID michael@0: */ michael@0: UnicodeString& parseExemplarLocation(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const; michael@0: }; michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif /* !UCONFIG_NO_FORMATTING */ michael@0: #endif