Class TimeZoneFormat
- All Implemented Interfaces:
Freezable<TimeZoneFormat>
,Serializable
,Cloneable
TimeZoneFormat
supports time zone display name formatting and parsing.
An instance of TimeZoneFormat works as a subformatter of SimpleDateFormat
,
but you can also directly get a new instance of TimeZoneFormat
and
formatting/parsing time zone display names.
ICU implements the time zone display names defined by UTS#35
Unicode Locale Data Markup Language (LDML). TimeZoneNames
represents the
time zone display name data model and this class implements the algorithm for actual
formatting and parsing.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
Offset pattern type enum.static enum
Parse option enum, used for specifying optional parse behavior.static enum
Time zone display format style enum used by format/parse APIs inTimeZoneFormat
.static enum
Time type enum used for receiving time type (standard time, daylight time or unknown) inTimeZoneFormat
APIs.Nested classes/interfaces inherited from class com.ibm.icu.text.UFormat
UFormat.SpanField
Nested classes/interfaces inherited from class java.text.Format
Format.Field
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
TimeZoneFormat
(ULocale locale) The protected constructor for subclassing. -
Method Summary
Modifier and TypeMethodDescriptionProvides for the clone operation.final String
format
(TimeZoneFormat.Style style, TimeZone tz, long date) Returns the display name of the time zone at the given date for the style.format
(TimeZoneFormat.Style style, TimeZone tz, long date, Output<TimeZoneFormat.TimeType> timeType) Returns the display name of the time zone at the given date for the style.format
(Object obj, StringBuffer toAppendTo, FieldPosition pos) final String
formatOffsetISO8601Basic
(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds) Returns the ISO 8601 basic time zone string for the given offset.final String
formatOffsetISO8601Extended
(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds) Returns the ISO 8601 extended time zone string for the given offset.formatOffsetLocalizedGMT
(int offset) Returns the localized GMT(UTC) offset format for the given offset.formatOffsetShortLocalizedGMT
(int offset) Returns the short localized GMT(UTC) offset format for the given offset.freeze()
Freezes the object.Returns the default parse options used by thisTimeZoneFormat
instance.Returns the decimal digit characters used for localized GMT format in a single string containing from 0 to 9 in the ascending order.Returns the offset pattern used for localized GMT format.Returns the localized GMT format pattern.Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0).static TimeZoneFormat
getInstance
(ULocale locale) Returns a frozen instance ofTimeZoneFormat
for the given locale.static TimeZoneFormat
getInstance
(Locale locale) Returns a frozen instance ofTimeZoneFormat
for the givenLocale
.Returns the time zone display name data used by this instance.boolean
isFrozen()
Determines whether the object has been frozen or not.parse
(TimeZoneFormat.Style style, String text, ParsePosition pos, Output<TimeZoneFormat.TimeType> timeType) Returns aTimeZone
by parsing the time zone string according to the parse position, the style and the default parse options.parse
(TimeZoneFormat.Style style, String text, ParsePosition pos, EnumSet<TimeZoneFormat.ParseOption> options, Output<TimeZoneFormat.TimeType> timeType) Returns aTimeZone
by parsing the time zone string according to the parse position, the style and the parse options.final TimeZone
Returns aTimeZone
for the given text.final TimeZone
parse
(String text, ParsePosition pos) Returns aTimeZone
by parsing the time zone string according to the given parse position.parseObject
(String source, ParsePosition pos) final int
parseOffsetISO8601
(String text, ParsePosition pos) Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 basic or extended time zone string.int
parseOffsetLocalizedGMT
(String text, ParsePosition pos) Returns offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.int
parseOffsetShortLocalizedGMT
(String text, ParsePosition pos) Returns offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string.Sets the default parse options.setGMTOffsetDigits
(String digits) Sets the decimal digit characters used for localized GMT format.setGMTOffsetPattern
(TimeZoneFormat.GMTOffsetPatternType type, String pattern) Sets the offset pattern for the given offset type.setGMTPattern
(String pattern) Sets the localized GMT format pattern.setGMTZeroFormat
(String gmtZeroFormat) Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0).setTimeZoneNames
(TimeZoneNames tznames) Sets the time zone display name data to this instance.Methods inherited from class java.text.Format
clone, format, parseObject
-
Constructor Details
-
TimeZoneFormat
The protected constructor for subclassing.- Parameters:
locale
- the locale
-
-
Method Details
-
getInstance
Returns a frozen instance ofTimeZoneFormat
for the given locale.Note: The instance returned by this method is frozen. If you want to customize a TimeZoneFormat, you must use
cloneAsThawed()
to get a thawed copy first.- Parameters:
locale
- the locale.- Returns:
- a frozen instance of
TimeZoneFormat
for the given locale.
-
getInstance
Returns a frozen instance ofTimeZoneFormat
for the givenLocale
.Note: The instance returned by this method is frozen. If you want to customize a TimeZoneFormat, you must use
cloneAsThawed()
to get a thawed copy first.- Parameters:
locale
- theLocale
.- Returns:
- a frozen instance of
TimeZoneFormat
for the given locale.
-
getTimeZoneNames
Returns the time zone display name data used by this instance.- Returns:
- the time zone display name data.
- See Also:
-
setTimeZoneNames
Sets the time zone display name data to this instance.- Parameters:
tznames
- the time zone display name data.- Returns:
- this object.
- Throws:
UnsupportedOperationException
- when this object is frozen.- See Also:
-
getGMTPattern
Returns the localized GMT format pattern.- Returns:
- the localized GMT format pattern.
- See Also:
-
setGMTPattern
Sets the localized GMT format pattern. The pattern must contain a single argument {0}, for example "GMT {0}".- Parameters:
pattern
- the localized GMT format pattern string- Returns:
- this object.
- Throws:
IllegalArgumentException
- when the pattern string does not contain "{0}"UnsupportedOperationException
- when this object is frozen.- See Also:
-
getGMTOffsetPattern
Returns the offset pattern used for localized GMT format.- Parameters:
type
- the offset pattern enum- See Also:
-
setGMTOffsetPattern
Sets the offset pattern for the given offset type.- Parameters:
type
- the offset pattern.pattern
- the pattern string.- Returns:
- this object.
- Throws:
IllegalArgumentException
- when the pattern string does not have required time field letters.UnsupportedOperationException
- when this object is frozen.- See Also:
-
getGMTOffsetDigits
Returns the decimal digit characters used for localized GMT format in a single string containing from 0 to 9 in the ascending order.- Returns:
- the decimal digits for localized GMT format.
- See Also:
-
setGMTOffsetDigits
Sets the decimal digit characters used for localized GMT format.- Parameters:
digits
- a string contains the decimal digit characters from 0 to 9 n the ascending order.- Returns:
- this object.
- Throws:
IllegalArgumentException
- when the string did not contain ten characters.UnsupportedOperationException
- when this object is frozen.- See Also:
-
getGMTZeroFormat
Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0).- Returns:
- the localized GMT string string for GMT(UTC) itself.
- See Also:
-
setGMTZeroFormat
Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0).- Parameters:
gmtZeroFormat
- the localized GMT format string for GMT(UTC).- Returns:
- this object.
- Throws:
UnsupportedOperationException
- when this object is frozen.- See Also:
-
setDefaultParseOptions
Sets the default parse options.Note: By default, an instance of
TimeZoneFormat
created bygetInstance(ULocale)
has no parse options set.- Parameters:
options
- the default parse options.- Returns:
- this object.
- See Also:
-
getDefaultParseOptions
Returns the default parse options used by thisTimeZoneFormat
instance.- Returns:
- the default parse options.
- See Also:
-
formatOffsetISO8601Basic
public final String formatOffsetISO8601Basic(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds) Returns the ISO 8601 basic time zone string for the given offset. For example, "-08", "-0830" and "Z"- Parameters:
offset
- the offset from GMT(UTC) in milliseconds.useUtcIndicator
- true if ISO 8601 UTC indicator "Z" is used when the offset is 0.isShort
- true if shortest form is used.ignoreSeconds
- true if non-zero offset seconds is appended.- Returns:
- the ISO 8601 basic format.
- Throws:
IllegalArgumentException
- if the specified offset is out of supported range (-24 hours < offset < +24 hours).- See Also:
-
formatOffsetISO8601Extended
public final String formatOffsetISO8601Extended(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds) Returns the ISO 8601 extended time zone string for the given offset. For example, "-08:00", "-08:30" and "Z"- Parameters:
offset
- the offset from GMT(UTC) in milliseconds.useUtcIndicator
- true if ISO 8601 UTC indicator "Z" is used when the offset is 0.isShort
- true if shortest form is used.ignoreSeconds
- true if non-zero offset seconds is appended.- Returns:
- the ISO 8601 extended format.
- Throws:
IllegalArgumentException
- if the specified offset is out of supported range (-24 hours < offset < +24 hours).- See Also:
-
formatOffsetLocalizedGMT
Returns the localized GMT(UTC) offset format for the given offset. The localized GMT offset is defined by;- GMT format pattern (e.g. "GMT {0}" - see
getGMTPattern()
) - Offset time pattern (e.g. "+HH:mm" - see
getGMTOffsetPattern(GMTOffsetPatternType)
) - Offset digits (e.g. "0123456789" - see
getGMTOffsetDigits()
) - GMT zero format (e.g. "GMT" - see
getGMTZeroFormat()
)
- Parameters:
offset
- the offset from GMT(UTC) in milliseconds.- Returns:
- the localized GMT format string
- Throws:
IllegalArgumentException
- if the specified offset is out of supported range (-24 hours < offset < +24 hours).- See Also:
- GMT format pattern (e.g. "GMT {0}" - see
-
formatOffsetShortLocalizedGMT
Returns the short localized GMT(UTC) offset format for the given offset. The short localized GMT offset is defined by;- GMT format pattern (e.g. "GMT {0}" - see
getGMTPattern()
) - Offset time pattern (e.g. "+HH:mm" - see
getGMTOffsetPattern(GMTOffsetPatternType)
) - Offset digits (e.g. "0123456789" - see
getGMTOffsetDigits()
) - GMT zero format (e.g. "GMT" - see
getGMTZeroFormat()
)
- Parameters:
offset
- the offset from GMT(UTC) in milliseconds.- Returns:
- the short localized GMT format string
- Throws:
IllegalArgumentException
- if the specified offset is out of supported range (-24 hours < offset < +24 hours).- See Also:
- GMT format pattern (e.g. "GMT {0}" - see
-
format
Returns the display name of the time zone at the given date for the style.Note: A style may have fallback styles defined. For example, when
GENERIC_LONG
is requested, but there is no display name data available forGENERIC_LONG
style, the implementation may useGENERIC_LOCATION
orLOCALIZED_GMT
. See UTS#35 UNICODE LOCALE DATA MARKUP LANGUAGE (LDML) Appendix J: Time Zone Display Name for the details.- Parameters:
style
- the style enum (e.g.GENERIC_LONG
,LOCALIZED_GMT
...)tz
- the time zone.date
- the date.- Returns:
- the display name of the time zone.
- See Also:
-
format
public String format(TimeZoneFormat.Style style, TimeZone tz, long date, Output<TimeZoneFormat.TimeType> timeType) Returns the display name of the time zone at the given date for the style. This method takes an extra argumentOutput<TimeType> timeType
in addition to the argument list offormat(Style, TimeZone, long)
. The argument is used for receiving the time type (standard time or daylight saving time, or unknown) actually used for the display name.- Parameters:
style
- the style enum (e.g.GENERIC_LONG
,LOCALIZED_GMT
...)tz
- the time zone.date
- the date.timeType
- the output argument for receiving the time type (standard/daylight/unknown) used for the display name, or specify null if the information is not necessary.- Returns:
- the display name of the time zone.
- See Also:
-
parseOffsetISO8601
Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 basic or extended time zone string. When the given string is not an ISO 8601 time zone string, this method sets the current position as the error index toParsePosition pos
and returns 0.- Parameters:
text
- the text contains ISO 8601 style time zone string (e.g. "-08", "-0800", "-08:00", and "Z") at the position.pos
- the position.- Returns:
- the offset from GMT(UTC) in milliseconds for the given ISO 8601 style time zone string.
- See Also:
-
parseOffsetLocalizedGMT
Returns offset from GMT(UTC) in milliseconds for the given localized GMT offset format string. When the given string cannot be parsed, this method sets the current position as the error index toParsePosition pos
and returns 0.- Parameters:
text
- the text contains a localized GMT offset string at the position.pos
- the position.- Returns:
- the offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.
- See Also:
-
parseOffsetShortLocalizedGMT
Returns offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string. When the given string cannot be parsed, this method sets the current position as the error index toParsePosition pos
and returns 0.- Parameters:
text
- the text contains a short localized GMT offset string at the position.pos
- the position.- Returns:
- the offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string.
- See Also:
-
parse
public TimeZone parse(TimeZoneFormat.Style style, String text, ParsePosition pos, EnumSet<TimeZoneFormat.ParseOption> options, Output<TimeZoneFormat.TimeType> timeType) Returns aTimeZone
by parsing the time zone string according to the parse position, the style and the parse options.- Parameters:
style
- the format style.text
- the text contains a time zone string at the position.pos
- the position.options
- the parse options.timeType
- The output argument for receiving the time type (standard/daylight/unknown), or specify null if the information is not necessary.- Returns:
- A
TimeZone
, or null if the input could not be parsed. - See Also:
-
parse
public TimeZone parse(TimeZoneFormat.Style style, String text, ParsePosition pos, Output<TimeZoneFormat.TimeType> timeType) Returns aTimeZone
by parsing the time zone string according to the parse position, the style and the default parse options.Note: This method is equivalent to
parse(style, text, pos, null, timeType)
.- Parameters:
style
- the format styletext
- the text contains a time zone string at the position.pos
- the position.timeType
- The output argument for receiving the time type (standard/daylight/unknown), or specify null if the information is not necessary.- Returns:
- A
TimeZone
, or null if the input could not be parsed. - See Also:
-
parse
Returns aTimeZone
by parsing the time zone string according to the given parse position.Note: This method is equivalent to
parse(Style.GENERIC_LOCATION, text, pos, EnumSet.of(ParseOption.ALL_STYLES), timeType)
.- Parameters:
text
- the text contains a time zone string at the position.pos
- the position.- Returns:
- A
TimeZone
, or null if the input could not be parsed. - See Also:
-
parse
Returns aTimeZone
for the given text.Note: The behavior of this method is equivalent to
parse(String, ParsePosition)
.- Parameters:
text
- the time zone string- Returns:
- A
TimeZone
. - Throws:
ParseException
- when the input could not be parsed as a time zone string.- See Also:
-
format
-
formatToCharacterIterator
- Overrides:
formatToCharacterIterator
in classFormat
-
parseObject
- Specified by:
parseObject
in classFormat
-
isFrozen
public boolean isFrozen()Determines whether the object has been frozen or not.- Specified by:
isFrozen
in interfaceFreezable<TimeZoneFormat>
-
freeze
Freezes the object.- Specified by:
freeze
in interfaceFreezable<TimeZoneFormat>
- Returns:
- the object itself.
-
cloneAsThawed
Provides for the clone operation. Any clone is initially unfrozen.- Specified by:
cloneAsThawed
in interfaceFreezable<TimeZoneFormat>
-