Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

TimeZoneFormat

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.

Summary

Nested classes

enum TimeZoneFormat.GMTOffsetPatternType

Offset pattern type enum. 

enum TimeZoneFormat.ParseOption

Parse option enum, used for specifying optional parse behavior. 

enum TimeZoneFormat.Style

Time zone display format style enum used by format/parse APIs in TimeZoneFormat

enum TimeZoneFormat.TimeType

Time type enum used for receiving time type (standard time, daylight time or unknown) in TimeZoneFormat APIs. 

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

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

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.

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

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

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;

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

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;

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

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.

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.

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

getGMTPattern

added in API level 24
public String getGMTPattern ()

Returns the localized GMT format pattern.

Returns
String the localized GMT format pattern.

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.

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.

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(String, 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.

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.

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.

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.

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.

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.

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.

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 {#link getInstance(ULocale) has no parse options set.

Parameters
options EnumSet: the default parse options.

Returns
TimeZoneFormat this object.

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.

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.

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:

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:

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: