Added in API level 24

Summary: Protected Ctors | Methods | Inherited Methods

TimeZoneFormat

---

Kotlin |Java

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

java.lang.Object
↳	java.text.Format
	↳	android.icu.text.UFormat
		↳	android.icu.text.TimeZoneFormat

---

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

Summary

Protected constructors
TimeZoneFormat(ULocale locale) The protected constructor for subclassing.

Public methods
TimeZoneFormat	cloneAsThawed() Provides for the clone operation.
StringBuffer	format(Object obj, StringBuffer toAppendTo, FieldPosition pos) Formats an object and appends the resulting text to a given string buffer.
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.
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.
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.
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) Formats an Object producing an AttributedCharacterIterator.
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.
final TimeZone	parse(String text) Returns a TimeZone for the given text.
final 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, 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.
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.
Object	parseObject(String source, ParsePosition pos) Parses text from a string to produce an object.
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.
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.

Inherited methods
From class java.text.Format Object clone() Creates and returns a copy of this object. final String format(Object obj) Formats an object to produce a string. abstract StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) Formats an object and appends the resulting text to a given string buffer. AttributedCharacterIterator formatToCharacterIterator(Object obj) Formats an Object producing an AttributedCharacterIterator. Object parseObject(String source) Parses text from the beginning of the given string to produce an object. abstract Object parseObject(String source, ParsePosition pos) Parses text from a string to produce an object.
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface android.icu.util.Freezable abstract TimeZoneFormat cloneAsThawed() Provides for the clone operation. abstract TimeZoneFormat freeze() Freezes the object. abstract boolean isFrozen() Determines whether the object has been frozen or not.

Protected constructors

TimeZoneFormat

Added in API level 24

protected TimeZoneFormat (ULocale locale)

The protected constructor for subclassing.

Parameters
locale	ULocale: the locale

Public methods

cloneAsThawed

Added in API level 24

public TimeZoneFormat cloneAsThawed ()

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

Returns
TimeZoneFormat

format

Added in API level 24

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

Formats an object and appends the resulting text to a given string buffer. If the pos argument identifies a field used by the format, then its indices are set to the beginning and end of the first such field encountered.

Parameters
obj	Object: The object to format
toAppendTo	StringBuffer: where the text is to be appended
pos	FieldPosition: A FieldPosition identifying a field in the formatted text

Returns
StringBuffer	the string buffer passed in as toAppendTo, with formatted text appended

format

Added in API level 24

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(android.icu.text.TimeZoneFormat.Style, android.icu.util.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	TimeZoneFormat.Style: the style enum (e.g. GENERIC_LONG, LOCALIZED_GMT...)
tz	TimeZone: the time zone.
date	long: the date.
timeType	Output: 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
String	the display name of the time zone.

See also:

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

format

Added in API level 24

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	TimeZoneFormat.Style: the style enum (e.g. GENERIC_LONG, LOCALIZED_GMT...)
tz	TimeZone: the time zone.
date	long: the date.

Returns
String	the display name of the time zone.

See also:

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

formatOffsetISO8601Basic

Added in API level 24

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	int: the offset from GMT(UTC) in milliseconds.
useUtcIndicator	boolean: true if ISO 8601 UTC indicator "Z" is used when the offset is 0.
isShort	boolean: true if shortest form is used.
ignoreSeconds	boolean: true if non-zero offset seconds is appended.

Returns
String	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)

formatOffsetISO8601Extended

Added in API level 24

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	int: the offset from GMT(UTC) in milliseconds.
useUtcIndicator	boolean: true if ISO 8601 UTC indicator "Z" is used when the offset is 0.
isShort	boolean: true if shortest form is used.
ignoreSeconds	boolean: true if non-zero offset seconds is appended.

Returns
String	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)

formatOffsetLocalizedGMT

Added in API level 24

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(android.icu.text.TimeZoneFormat.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	int: the offset from GMT(UTC) in milliseconds.

Returns
String	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)

formatOffsetShortLocalizedGMT

Added in API level 24

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(android.icu.text.TimeZoneFormat.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	int: the offset from GMT(UTC) in milliseconds.

Returns
String	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)

formatToCharacterIterator

Added in API level 24

public AttributedCharacterIterator formatToCharacterIterator (Object obj)

Formats an Object producing an AttributedCharacterIterator. You can use the returned AttributedCharacterIterator to build the resulting String, as well as to determine information about the resulting String.

Each attribute key of the AttributedCharacterIterator will be of type Field. It is up to each Format implementation to define what the legal values are for each attribute in the AttributedCharacterIterator, but typically the attribute key is also used as the attribute value.

The default implementation creates an AttributedCharacterIterator with no attributes. Subclasses that support fields should override this and create an AttributedCharacterIterator with meaningful attributes.

Parameters
obj	Object: The object to format

Returns
AttributedCharacterIterator	AttributedCharacterIterator describing the formatted value.

freeze

Added in API level 24

public TimeZoneFormat freeze ()

Freezes the object.

Returns
TimeZoneFormat	the object itself.

getDefaultParseOptions

Added in API level 24

public EnumSet<TimeZoneFormat.ParseOption> getDefaultParseOptions ()

Returns the default parse options used by this TimeZoneFormat instance.

Returns
EnumSet<TimeZoneFormat.ParseOption>	the default parse options.

See also:

• TimeZoneFormat.ParseOption

getGMTOffsetDigits

Added in API level 24

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
String	the decimal digits for localized GMT format.

See also:

• setGMTOffsetDigits(String)

getGMTOffsetPattern

Added in API level 24

public String getGMTOffsetPattern (TimeZoneFormat.GMTOffsetPatternType type)

Returns the offset pattern used for localized GMT format.

Parameters
type	TimeZoneFormat.GMTOffsetPatternType: the offset pattern enum

Returns
String

See also:

• setGMTOffsetPattern(GMTOffsetPatternType, String)

getGMTPattern

Added in API level 24

public String getGMTPattern ()

Returns the localized GMT format pattern.

Returns
String	the localized GMT format pattern.

See also:

• setGMTPattern(String)

getGMTZeroFormat

Added in API level 24

public String getGMTZeroFormat ()

Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0).

Returns
String	the localized GMT string string for GMT(UTC) itself.

See also:

• setGMTZeroFormat(String)

getInstance

Added in API level 24

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	Locale: the Locale.

Returns
TimeZoneFormat	a frozen instance of TimeZoneFormat for the given locale.

getInstance

Added in API level 24

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	ULocale: the locale.

Returns
TimeZoneFormat	a frozen instance of TimeZoneFormat for the given locale.

getTimeZoneNames

Added in API level 24

public TimeZoneNames getTimeZoneNames ()

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

Returns
TimeZoneNames	the time zone display name data.

See also:

• setTimeZoneNames(TimeZoneNames)

isFrozen

Added in API level 24

public boolean isFrozen ()

Determines whether the object has been frozen or not.

Returns
boolean

parse

Added in API level 24

public final TimeZone parse (String text)

Returns a TimeZone for the given text.

Note: The behavior of this method is equivalent to parse(java.lang.String, java.text.ParsePosition).

Parameters
text	String: the time zone string

Returns
TimeZone	A TimeZone.

Throws
ParseException	when the input could not be parsed as a time zone string.

See also:

• parse(String, ParsePosition)

parse

Added in API level 24

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	String: the text contains a time zone string at the position.
pos	ParsePosition: the position.

Returns
TimeZone	A TimeZone, or null if the input could not be parsed.

See also:

• parse(Style, String, ParsePosition, EnumSet, Output)

parse

Added in API level 24

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
style	TimeZoneFormat.Style: the format style
text	String: the text contains a time zone string at the position.
pos	ParsePosition: the position.
timeType	Output: The output argument for receiving the time type (standard/daylight/unknown), or specify null if the information is not necessary.

Returns
TimeZone	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)

parse

Added in API level 24

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
style	TimeZoneFormat.Style: the format style.
text	String: the text contains a time zone string at the position.
pos	ParsePosition: the position.
options	EnumSet: the parse options.
timeType	Output: The output argument for receiving the time type (standard/daylight/unknown), or specify null if the information is not necessary.

Returns
TimeZone	A TimeZone, or null if the input could not be parsed.

See also:

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

parseObject

Added in API level 24

public Object parseObject (String source, 
                ParsePosition pos)

Parses text from a string to produce an object.

The method attempts to parse text starting at the index given by pos. If parsing succeeds, then the index of pos is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string), and the parsed object is returned. The updated pos can be used to indicate the starting point for the next call to this method. If an error occurs, then the index of pos is not changed, the error index of pos is set to the index of the character where the error occurred, and null is returned.

Parameters
source	String: A String, part of which should be parsed.
pos	ParsePosition: A ParsePosition object with index and error index information as described above.

Returns
Object	An Object parsed from the string. In case of error, returns null.

parseOffsetISO8601

Added in API level 24

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	String: the text contains ISO 8601 style time zone string (e.g. "-08", "-0800", "-08:00", and "Z") at the position.
pos	ParsePosition: the position.

Returns
int	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)

parseOffsetLocalizedGMT

Added in API level 24

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	String: the text contains a localized GMT offset string at the position.
pos	ParsePosition: the position.

Returns
int	the offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.

See also:

• formatOffsetLocalizedGMT(int)

parseOffsetShortLocalizedGMT

Added in API level 24

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	String: the text contains a short localized GMT offset string at the position.
pos	ParsePosition: the position.

Returns
int	the offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string.

See also:

• formatOffsetShortLocalizedGMT(int)

setDefaultParseOptions

Added in API level 24

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

Sets the default parse options.

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

Parameters
options	EnumSet: the default parse options.

Returns
TimeZoneFormat	this object.

See also:

• TimeZoneFormat.ParseOption

setGMTOffsetDigits

Added in API level 24

public TimeZoneFormat setGMTOffsetDigits (String digits)

Sets the decimal digit characters used for localized GMT format.

Parameters
digits	String: a string contains the decimal digit characters from 0 to 9 n the ascending order.

Returns
TimeZoneFormat	this object.

Throws
IllegalArgumentException	when the string did not contain ten characters.
UnsupportedOperationException	when this object is frozen.

See also:

• getGMTOffsetDigits()

setGMTOffsetPattern

Added in API level 24

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

Sets the offset pattern for the given offset type.

Parameters
type	TimeZoneFormat.GMTOffsetPatternType: the offset pattern.
pattern	String: the pattern string.

Returns
TimeZoneFormat	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)

setGMTPattern

Added in API level 24

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	String: the localized GMT format pattern string

Returns
TimeZoneFormat	this object.

Throws
IllegalArgumentException	when the pattern string does not contain "{0}"
UnsupportedOperationException	when this object is frozen.

See also:

• getGMTPattern()

setGMTZeroFormat

Added in API level 24

public TimeZoneFormat setGMTZeroFormat (String gmtZeroFormat)

Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0).

Parameters
gmtZeroFormat	String: the localized GMT format string for GMT(UTC).

Returns
TimeZoneFormat	this object.

Throws
UnsupportedOperationException	when this object is frozen.

See also:

• getGMTZeroFormat()

setTimeZoneNames

Added in API level 24

public TimeZoneFormat setTimeZoneNames (TimeZoneNames tznames)

Sets the time zone display name data to this instance.

Parameters
tznames	TimeZoneNames: the time zone display name data.

Returns
TimeZoneFormat	this object.

Throws
UnsupportedOperationException	when this object is frozen.

See also:

• getTimeZoneNames()