Added in API level 24

TimeZoneFormat

open class TimeZoneFormat : UFormat, Freezable<TimeZoneFormat!>, Serializable
kotlin.Any
   ↳ 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

Offset pattern type enum.

Parse option enum, used for specifying optional parse behavior.

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

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

The protected constructor for subclassing.
Public methods
open TimeZoneFormat!

Provides for the clone operation.
String!
format(style: TimeZoneFormat.Style!, tz: TimeZone!, date: Long)

Returns the display name of the time zone at the given date for the style.
open String!
format(style: TimeZoneFormat.Style!, tz: TimeZone!, date: Long, timeType: Output<TimeZoneFormat.TimeType!>!)

Returns the display name of the time zone at the given date for the style.
open StringBuffer!
format(obj: Any!, toAppendTo: StringBuffer!, pos: FieldPosition!)

Formats an object and appends the resulting text to a given string buffer.
String!
formatOffsetISO8601Basic(offset: Int, useUtcIndicator: Boolean, isShort: Boolean, ignoreSeconds: Boolean)

Returns the ISO 8601 basic time zone string for the given offset.
String!
formatOffsetISO8601Extended(offset: Int, useUtcIndicator: Boolean, isShort: Boolean, ignoreSeconds: Boolean)

Returns the ISO 8601 extended time zone string for the given offset.
open String!

Returns the localized GMT(UTC) offset format for the given offset.
open String!

Returns the short localized GMT(UTC) offset format for the given offset.
open AttributedCharacterIterator!

Formats an Object producing an AttributedCharacterIterator.
open TimeZoneFormat!

Freezes the object.
open EnumSet<TimeZoneFormat.ParseOption!>!

Returns the default parse options used by this TimeZoneFormat instance.
open String!

Returns the decimal digit characters used for localized GMT format in a single string containing from 0 to 9 in the ascending order.
open String!

Returns the offset pattern used for localized GMT format.
open String!

Returns the localized GMT format pattern.
open String!

Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0).
open static TimeZoneFormat!
getInstance(locale: ULocale!)

Returns a frozen instance of TimeZoneFormat for the given locale.
open static TimeZoneFormat!
getInstance(locale: Locale!)

Returns a frozen instance of TimeZoneFormat for the given java.util.Locale.
open TimeZoneNames!

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

Determines whether the object has been frozen or not.
open TimeZone!

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

Returns a TimeZone by parsing the time zone string according to the parse position, the style and the default parse options.
TimeZone!
parse(text: String!, pos: ParsePosition!)

Returns a TimeZone by parsing the time zone string according to the given parse position.
TimeZone!
parse(text: String!)

Returns a TimeZone for the given text.
open Any!
parseObject(source: String!, pos: ParsePosition!)

Parses text from a string to produce an object.
Int

Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 basic or extended time zone string.
open Int

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

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

Sets the default parse options.
open TimeZoneFormat!

Sets the decimal digit characters used for localized GMT format.
open TimeZoneFormat!

Sets the offset pattern for the given offset type.
open TimeZoneFormat!
setGMTPattern(pattern: String!)

Sets the localized GMT format pattern.
open TimeZoneFormat!
setGMTZeroFormat(gmtZeroFormat: String!)

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

Sets the time zone display name data to this instance.

Protected constructors

TimeZoneFormat

Added in API level 24
protected TimeZoneFormat(locale: ULocale!)

The protected constructor for subclassing.

Parameters
locale ULocale!: the locale

Public methods

cloneAsThawed

Added in API level 24
open fun cloneAsThawed(): TimeZoneFormat!

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

format

Added in API level 24
fun format(
    style: TimeZoneFormat.Style!, 
    tz: TimeZone!, 
    date: Long
): String!

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.
Return
String! the display name of the time zone.

format

Added in API level 24
open fun format(
    style: TimeZoneFormat.Style!, 
    tz: TimeZone!, 
    date: Long, 
    timeType: Output<TimeZoneFormat.TimeType!>!
): String!

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<TimeZoneFormat.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.
Return
String! the display name of the time zone.

format

Added in API level 24
open fun format(
    obj: Any!, 
    toAppendTo: StringBuffer!, 
    pos: FieldPosition!
): StringBuffer!

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 Any!: The object to format
toAppendTo StringBuffer!: where the text is to be appended
pos FieldPosition!: A FieldPosition identifying a field in the formatted text
Return
StringBuffer! the string buffer passed in as toAppendTo, with formatted text appended
Exceptions
java.lang.NullPointerException if toAppendTo or pos is null
java.lang.IllegalArgumentException if the Format cannot format the given object

formatOffsetISO8601Basic

Added in API level 24
fun formatOffsetISO8601Basic(
    offset: Int, 
    useUtcIndicator: Boolean, 
    isShort: Boolean, 
    ignoreSeconds: Boolean
): String!

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.
Return
String! the ISO 8601 basic format.
Exceptions
java.lang.IllegalArgumentException if the specified offset is out of supported range (-24 hours < offset < +24 hours).

formatOffsetISO8601Extended

Added in API level 24
fun formatOffsetISO8601Extended(
    offset: Int, 
    useUtcIndicator: Boolean, 
    isShort: Boolean, 
    ignoreSeconds: Boolean
): String!

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.
Return
String! the ISO 8601 extended format.
Exceptions
java.lang.IllegalArgumentException if the specified offset is out of supported range (-24 hours < offset < +24 hours).

formatOffsetLocalizedGMT

Added in API level 24
open fun formatOffsetLocalizedGMT(offset: Int): String!

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.
Return
String! the localized GMT format string
Exceptions
java.lang.IllegalArgumentException if the specified offset is out of supported range (-24 hours < offset < +24 hours).

formatOffsetShortLocalizedGMT

Added in API level 24
open fun formatOffsetShortLocalizedGMT(offset: Int): String!

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.
Return
String! the short localized GMT format string
Exceptions
java.lang.IllegalArgumentException if the specified offset is out of supported range (-24 hours < offset < +24 hours).

formatToCharacterIterator

Added in API level 24
open fun formatToCharacterIterator(obj: Any!): AttributedCharacterIterator!

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 Any!: The object to format
Return
AttributedCharacterIterator! AttributedCharacterIterator describing the formatted value.
Exceptions
java.lang.NullPointerException if obj is null.
java.lang.IllegalArgumentException when the Format cannot format the given object.

freeze

Added in API level 24
open fun freeze(): TimeZoneFormat!

Freezes the object.

Return
TimeZoneFormat! the object itself.

getDefaultParseOptions

Added in API level 24
open fun getDefaultParseOptions(): EnumSet<TimeZoneFormat.ParseOption!>!

Returns the default parse options used by this TimeZoneFormat instance.

Return
EnumSet<TimeZoneFormat.ParseOption!>! the default parse options.

getGMTOffsetDigits

Added in API level 24
open fun getGMTOffsetDigits(): String!

Returns the decimal digit characters used for localized GMT format in a single string containing from 0 to 9 in the ascending order.

Return
String! the decimal digits for localized GMT format.

getGMTOffsetPattern

Added in API level 24
open fun getGMTOffsetPattern(type: TimeZoneFormat.GMTOffsetPatternType!): String!

Returns the offset pattern used for localized GMT format.

Parameters
type TimeZoneFormat.GMTOffsetPatternType!: the offset pattern enum

getGMTPattern

Added in API level 24
open fun getGMTPattern(): String!

Returns the localized GMT format pattern.

Return
String! the localized GMT format pattern.

getGMTZeroFormat

Added in API level 24
open fun getGMTZeroFormat(): String!

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

Return
String! the localized GMT string string for GMT(UTC) itself.

getInstance

Added in API level 24
open static fun getInstance(locale: ULocale!): TimeZoneFormat!

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.
Return
TimeZoneFormat! a frozen instance of TimeZoneFormat for the given locale.

getInstance

Added in API level 24
open static fun getInstance(locale: Locale!): TimeZoneFormat!

Returns a frozen instance of TimeZoneFormat for the given java.util.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.
Return
TimeZoneFormat! a frozen instance of TimeZoneFormat for the given locale.

getTimeZoneNames

Added in API level 24
open fun getTimeZoneNames(): TimeZoneNames!

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

Return
TimeZoneNames! the time zone display name data.

isFrozen

Added in API level 24
open fun isFrozen(): Boolean

Determines whether the object has been frozen or not.

parse

Added in API level 24
open fun parse(
    style: TimeZoneFormat.Style!, 
    text: String!, 
    pos: ParsePosition!, 
    options: EnumSet<TimeZoneFormat.ParseOption!>!, 
    timeType: Output<TimeZoneFormat.TimeType!>!
): TimeZone!

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

Parameters
text String!: the text contains a time zone string at the position.
style TimeZoneFormat.Style!: the format style.
pos ParsePosition!: the position.
options EnumSet<TimeZoneFormat.ParseOption!>!: the parse options.
timeType Output<TimeZoneFormat.TimeType!>!: The output argument for receiving the time type (standard/daylight/unknown), or specify null if the information is not necessary.
Return
TimeZone! A TimeZone, or null if the input could not be parsed.

parse

Added in API level 24
open fun parse(
    style: TimeZoneFormat.Style!, 
    text: String!, 
    pos: ParsePosition!, 
    timeType: Output<TimeZoneFormat.TimeType!>!
): TimeZone!

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

parse

Added in API level 24
fun parse(
    text: String!, 
    pos: ParsePosition!
): TimeZone!

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.
Return
TimeZone! A TimeZone, or null if the input could not be parsed.

parse

Added in API level 24
fun parse(text: String!): TimeZone!

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
Return
TimeZone! A TimeZone.
Exceptions
java.text.ParseException when the input could not be parsed as a time zone string.

parseObject

Added in API level 24
open fun parseObject(
    source: String!, 
    pos: ParsePosition!
): Any!

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.
Return
Any! An Object parsed from the string. In case of error, returns null.
Exceptions
java.lang.NullPointerException if source or pos is null.

parseOffsetISO8601

Added in API level 24
fun parseOffsetISO8601(
    text: String!, 
    pos: ParsePosition!
): Int

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.
Return
Int the offset from GMT(UTC) in milliseconds for the given ISO 8601 style time zone string.

parseOffsetLocalizedGMT

Added in API level 24
open fun parseOffsetLocalizedGMT(
    text: String!, 
    pos: ParsePosition!
): Int

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.
Return
Int the offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.

parseOffsetShortLocalizedGMT

Added in API level 24
open fun parseOffsetShortLocalizedGMT(
    text: String!, 
    pos: ParsePosition!
): Int

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.
Return
Int the offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string.

setDefaultParseOptions

Added in API level 24
open fun setDefaultParseOptions(options: EnumSet<TimeZoneFormat.ParseOption!>!): TimeZoneFormat!

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<TimeZoneFormat.ParseOption!>!: the default parse options.
Return
TimeZoneFormat! this object.

setGMTOffsetDigits

Added in API level 24
open fun setGMTOffsetDigits(digits: String!): TimeZoneFormat!

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.
Return
TimeZoneFormat! this object.
Exceptions
java.lang.IllegalArgumentException when the string did not contain ten characters.
java.lang.UnsupportedOperationException when this object is frozen.

setGMTOffsetPattern

Added in API level 24
open fun setGMTOffsetPattern(
    type: TimeZoneFormat.GMTOffsetPatternType!, 
    pattern: String!
): TimeZoneFormat!

Sets the offset pattern for the given offset type.

Parameters
type TimeZoneFormat.GMTOffsetPatternType!: the offset pattern.
pattern String!: the pattern string.
Return
TimeZoneFormat! this object.
Exceptions
java.lang.IllegalArgumentException when the pattern string does not have required time field letters.
java.lang.UnsupportedOperationException when this object is frozen.

setGMTPattern

Added in API level 24
open fun setGMTPattern(pattern: String!): TimeZoneFormat!

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
Return
TimeZoneFormat! this object.
Exceptions
java.lang.IllegalArgumentException when the pattern string does not contain "{0}"
java.lang.UnsupportedOperationException when this object is frozen.

See Also

setGMTZeroFormat

Added in API level 24
open fun setGMTZeroFormat(gmtZeroFormat: String!): TimeZoneFormat!

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).
Return
TimeZoneFormat! this object.
Exceptions
java.lang.UnsupportedOperationException when this object is frozen.

setTimeZoneNames

Added in API level 24
open fun setTimeZoneNames(tznames: TimeZoneNames!): TimeZoneFormat!

Sets the time zone display name data to this instance.

Parameters
tznames TimeZoneNames!: the time zone display name data.
Return
TimeZoneFormat! this object.
Exceptions
java.lang.UnsupportedOperationException when this object is frozen.