com.ibm.icu.text

Class TimeZoneFormat

java.lang.Object

java.text.Format

com.ibm.icu.text.UFormat

com.ibm.icu.text.TimeZoneFormat

All Implemented Interfaces:

Freezable<TimeZoneFormat>, Serializable, Cloneable

public class TimeZoneFormat
extends UFormat
implements Freezable<TimeZoneFormat>, Serializable

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:

SimpleDateFormat, TimeZoneNames, Serialized Form

Status:

Stable ICU 49.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TimeZoneFormat.GMTOffsetPatternType Offset pattern type enum.
static class	TimeZoneFormat.ParseOption Parse option enum, used for specifying optional parse behavior.
static class	TimeZoneFormat.Style Time zone display format style enum used by format/parse APIs in TimeZoneFormat.
static class	TimeZoneFormat.TimeType Time type enum used for receiving time type (standard time, daylight time or unknown) in TimeZoneFormat 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

Constructors

Modifier	Constructor and Description
protected	TimeZoneFormat(ULocale locale) The protected constructor for subclassing.

Method Summary

Modifier and Type	Method and Description
TimeZoneFormat	cloneAsThawed() Provides for the clone operation.
StringBuffer	format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
String	format(TimeZoneFormat.Style style, TimeZone tz, long date) Returns the display name of the time zone at the given date for the style.
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.
String	formatOffsetISO8601Basic(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds) Returns the ISO 8601 basic time zone string for the given offset.
String	formatOffsetISO8601Extended(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds) Returns the ISO 8601 extended time zone string for the given offset.
String	formatOffsetLocalizedGMT(int offset) Returns the localized GMT(UTC) offset format for the given offset.
String	formatOffsetShortLocalizedGMT(int offset) Returns the short localized GMT(UTC) offset format for the given offset.
AttributedCharacterIterator	formatToCharacterIterator(Object obj)
TimeZoneFormat	freeze() Freezes the object.
EnumSet<TimeZoneFormat.ParseOption>	getDefaultParseOptions() Returns the default parse options used by this TimeZoneFormat instance.
String	getGMTOffsetDigits() Returns the decimal digit characters used for localized GMT format in a single string containing from 0 to 9 in the ascending order.
String	getGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type) Returns the offset pattern used for localized GMT format.
String	getGMTPattern() Returns the localized GMT format pattern.
String	getGMTZeroFormat() Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0).
static TimeZoneFormat	getInstance(Locale locale) Returns a frozen instance of TimeZoneFormat for the given Locale.
static TimeZoneFormat	getInstance(ULocale locale) Returns a frozen instance of TimeZoneFormat for the given locale.
TimeZoneNames	getTimeZoneNames() Returns the time zone display name data used by this instance.
boolean	isFrozen() Determines whether the object has been frozen or not.
TimeZone	parse(String text) Returns a TimeZone for the given text.
TimeZone	parse(String text, ParsePosition pos) Returns a TimeZone by parsing the time zone string according to the given parse position.
TimeZone	parse(TimeZoneFormat.Style style, String text, ParsePosition pos, EnumSet<TimeZoneFormat.ParseOption> options, Output<TimeZoneFormat.TimeType> timeType) Returns a TimeZone by parsing the time zone string according to the parse position, the style and the parse options.
TimeZone	parse(TimeZoneFormat.Style style, String text, ParsePosition pos, Output<TimeZoneFormat.TimeType> timeType) Returns a TimeZone by parsing the time zone string according to the parse position, the style and the default parse options.
Object	parseObject(String source, ParsePosition pos)
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.
TimeZoneFormat	setDefaultParseOptions(EnumSet<TimeZoneFormat.ParseOption> options) Sets the default parse options.
TimeZoneFormat	setGMTOffsetDigits(String digits) Sets the decimal digit characters used for localized GMT format.
TimeZoneFormat	setGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type, String pattern) Sets the offset pattern for the given offset type.
TimeZoneFormat	setGMTPattern(String pattern) Sets the localized GMT format pattern.
TimeZoneFormat	setGMTZeroFormat(String gmtZeroFormat) Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0).
TimeZoneFormat	setTimeZoneNames(TimeZoneNames tznames) Sets the time zone display name data to this instance.

Methods inherited from class com.ibm.icu.text.UFormat

getLocale

Methods inherited from class java.text.Format

clone, format, parseObject

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TimeZoneFormat

protected TimeZoneFormat(ULocale locale)

The protected constructor for subclassing.

Parameters:

locale - the locale

Status:

Stable ICU 49.

Method Detail

getInstance

public static TimeZoneFormat getInstance(ULocale locale)

Returns a frozen instance of TimeZoneFormat 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.

Status:

Stable ICU 49.

getInstance

public static TimeZoneFormat getInstance(Locale locale)

Returns a frozen instance of TimeZoneFormat 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.

Status:

Stable ICU 54.

getTimeZoneNames

public TimeZoneNames getTimeZoneNames()

Returns the time zone display name data used by this instance.

Returns:

the time zone display name data.

See Also:

setTimeZoneNames(TimeZoneNames)

Status:

Stable ICU 49.

setTimeZoneNames

public TimeZoneFormat setTimeZoneNames(TimeZoneNames tznames)

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:

getTimeZoneNames()

Status:

Stable ICU 49.

getGMTPattern

public String getGMTPattern()

Returns the localized GMT format pattern.

Returns:

the localized GMT format pattern.

See Also:

setGMTPattern(String)

Status:

Stable ICU 49.

setGMTPattern

public TimeZoneFormat setGMTPattern(String pattern)

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:

getGMTPattern()

Status:

Stable ICU 49.

getGMTOffsetPattern

public String getGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type)

Returns the offset pattern used for localized GMT format.

Parameters:

type - the offset pattern enum

See Also:

setGMTOffsetPattern(GMTOffsetPatternType, String)

Status:

Stable ICU 49.

setGMTOffsetPattern

public TimeZoneFormat setGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type,
                                          String pattern)

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:

getGMTOffsetPattern(GMTOffsetPatternType)

Status:

Stable ICU 49.

getGMTOffsetDigits

public String 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(String)

Status:

Stable ICU 49.

setGMTOffsetDigits

public TimeZoneFormat setGMTOffsetDigits(String digits)

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:

getGMTOffsetDigits()

Status:

Stable ICU 49.

getGMTZeroFormat

public String 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(String)

Status:

Stable ICU 49.

setGMTZeroFormat

public TimeZoneFormat setGMTZeroFormat(String gmtZeroFormat)

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:

getGMTZeroFormat()

Status:

Stable ICU 49.

setDefaultParseOptions

public TimeZoneFormat setDefaultParseOptions(EnumSet<TimeZoneFormat.ParseOption> options)

Sets the default parse options.

Note: By default, an instance of TimeZoneFormat created by getInstance(ULocale) has no parse options set.

Parameters:

options - the default parse options.

Returns:

this object.

See Also:

TimeZoneFormat.ParseOption

Status:

Stable ICU 49.

getDefaultParseOptions

public EnumSet<TimeZoneFormat.ParseOption> getDefaultParseOptions()

Returns the default parse options used by this TimeZoneFormat instance.

Returns:

the default parse options.

See Also:

TimeZoneFormat.ParseOption

Status:

Stable ICU 49.

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(int, boolean, boolean, boolean), parseOffsetISO8601(String, ParsePosition)

Status:

Stable ICU 51.

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:

formatOffsetISO8601Basic(int, boolean, boolean, boolean), parseOffsetISO8601(String, ParsePosition)

Status:

Stable ICU 51.

formatOffsetLocalizedGMT

public String formatOffsetLocalizedGMT(int offset)

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())

This format always uses 2 digit hours and minutes. When the given offset has non-zero seconds, 2 digit seconds field will be appended. For example, GMT+05:00 and GMT+05:28:06.

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:

parseOffsetLocalizedGMT(String, ParsePosition)

Status:

Stable ICU 49.

formatOffsetShortLocalizedGMT

public String formatOffsetShortLocalizedGMT(int offset)

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())

This format uses the shortest representation of offset. The hours field does not have leading zero and lower fields with zero will be truncated. For example, GMT+5 and GMT+530.

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:

parseOffsetLocalizedGMT(String, ParsePosition)

Status:

Stable ICU 51.

format

public 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.

Note: A style may have fallback styles defined. For example, when GENERIC_LONG is requested, but there is no display name data available for GENERIC_LONG style, the implementation may use GENERIC_LOCATION or LOCALIZED_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:

TimeZoneFormat.Style, format(Style, TimeZone, long, Output)

Status:

Stable ICU 49.

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 argument Output<TimeType> timeType in addition to the argument list of format(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:

TimeZoneFormat.Style, format(Style, TimeZone, long)

Status:

Stable ICU 49.

parseOffsetISO8601

public 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. When the given string is not an ISO 8601 time zone string, this method sets the current position as the error index to ParsePosition 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:

formatOffsetISO8601Basic(int, boolean, boolean, boolean), formatOffsetISO8601Extended(int, boolean, boolean, boolean)

Status:

Stable ICU 49.

parseOffsetLocalizedGMT

public int parseOffsetLocalizedGMT(String text,
                                   ParsePosition pos)

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 to ParsePosition 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:

formatOffsetLocalizedGMT(int)

Status:

Stable ICU 49.

parseOffsetShortLocalizedGMT

public int parseOffsetShortLocalizedGMT(String text,
                                        ParsePosition pos)

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 to ParsePosition 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:

formatOffsetShortLocalizedGMT(int)

Status:

Stable ICU 51.

parse

public TimeZone parse(TimeZoneFormat.Style style,
                      String text,
                      ParsePosition pos,
                      EnumSet<TimeZoneFormat.ParseOption> options,
                      Output<TimeZoneFormat.TimeType> timeType)

Returns a TimeZone by parsing the time zone string according to the parse position, the style and the parse options.

Parameters:

text - the text contains a time zone string at the position.

style - the format style.

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:

TimeZoneFormat.Style, format(Style, TimeZone, long, Output)

Status:

Stable ICU 49.

parse

public TimeZone parse(TimeZoneFormat.Style style,
                      String text,
                      ParsePosition pos,
                      Output<TimeZoneFormat.TimeType> timeType)

Returns a TimeZone 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:

text - the text contains a time zone string at the position.

style - the format style

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:

TimeZoneFormat.Style, parse(Style, String, ParsePosition, EnumSet, Output), format(Style, TimeZone, long, Output), setDefaultParseOptions(EnumSet)

Status:

Stable ICU 49.

parse

public final TimeZone parse(String text,
                            ParsePosition pos)

Returns a TimeZone 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(Style, String, ParsePosition, EnumSet, Output)

Status:

Stable ICU 49.

parse

public final TimeZone parse(String text)
                     throws ParseException

Returns a TimeZone 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:

parse(String, ParsePosition)

Status:

Stable ICU 49.

format

public StringBuffer format(Object obj,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Specified by:

format in class Format

Status:

Stable ICU 49.

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

Overrides:

formatToCharacterIterator in class Format

Status:

Stable ICU 49.

parseObject

public Object parseObject(String source,
                          ParsePosition pos)

Specified by:

parseObject in class Format

Status:

Stable ICU 49.

isFrozen

public boolean isFrozen()

Determines whether the object has been frozen or not.

Specified by:

isFrozen in interface Freezable<TimeZoneFormat>

Status:

Stable ICU 49.

freeze

public TimeZoneFormat freeze()

Freezes the object.

Specified by:

freeze in interface Freezable<TimeZoneFormat>

Returns:

the object itself.

Status:

Stable ICU 49.

cloneAsThawed

public TimeZoneFormat cloneAsThawed()

Provides for the clone operation. Any clone is initially unfrozen.

Specified by:

cloneAsThawed in interface Freezable<TimeZoneFormat>

Status:

Stable ICU 49.