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 |
|
Time type enum used for receiving time type (standard time, daylight time or unknown) in |
Protected constructors | |
---|---|
TimeZoneFormat(locale: ULocale!) 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! |
formatOffsetLocalizedGMT(offset: Int) Returns the localized GMT(UTC) offset format for the given offset. |
open String! |
formatOffsetShortLocalizedGMT(offset: Int) Returns the short localized GMT(UTC) offset format for the given offset. |
open AttributedCharacterIterator! |
formatToCharacterIterator(obj: Any!) Formats an Object producing an |
open TimeZoneFormat! |
freeze() Freezes the object. |
open EnumSet<TimeZoneFormat.ParseOption!>! |
Returns the default parse options used by this |
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 |
open static TimeZoneFormat! |
getInstance(locale: Locale!) Returns a frozen instance of |
open TimeZoneNames! |
Returns the time zone display name data used by this instance. |
open Boolean |
isFrozen() Determines whether the object has been frozen or not. |
open TimeZone! |
parse(style: TimeZoneFormat.Style!, text: String!, pos: ParsePosition!, options: EnumSet<TimeZoneFormat.ParseOption!>!, timeType: Output<TimeZoneFormat.TimeType!>!) Returns a |
open TimeZone! |
parse(style: TimeZoneFormat.Style!, text: String!, pos: ParsePosition!, timeType: Output<TimeZoneFormat.TimeType!>!) Returns a |
TimeZone! |
parse(text: String!, pos: ParsePosition!) Returns a |
TimeZone! |
Returns a |
open Any! |
parseObject(source: String!, pos: ParsePosition!) Parses text from a string to produce an object. |
Int |
parseOffsetISO8601(text: String!, pos: ParsePosition!) Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 basic or extended time zone string. |
open Int |
parseOffsetLocalizedGMT(text: String!, pos: ParsePosition!) Returns offset from GMT(UTC) in milliseconds for the given localized GMT offset format string. |
open Int |
parseOffsetShortLocalizedGMT(text: String!, pos: ParsePosition!) Returns offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string. |
open TimeZoneFormat! |
setDefaultParseOptions(options: EnumSet<TimeZoneFormat.ParseOption!>!) Sets the default parse options. |
open TimeZoneFormat! |
setGMTOffsetDigits(digits: String!) Sets the decimal digit characters used for localized GMT format. |
open TimeZoneFormat! |
setGMTOffsetPattern(type: TimeZoneFormat.GMTOffsetPatternType!, pattern: String!) 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! |
setTimeZoneNames(tznames: TimeZoneNames!) Sets the time zone display name data to this instance. |
Protected constructors
TimeZoneFormat
protected TimeZoneFormat(locale: ULocale!)
The protected constructor for subclassing.
Parameters | |
---|---|
locale |
ULocale!: the locale |
Public methods
cloneAsThawed
open fun cloneAsThawed(): TimeZoneFormat!
Provides for the clone operation. Any clone is initially unfrozen.
format
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
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
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
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
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
open fun formatOffsetLocalizedGMT(offset: Int): String!
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()
)
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
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;
- 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()
)
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
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
open fun freeze(): TimeZoneFormat!
Freezes the object.
Return | |
---|---|
TimeZoneFormat! |
the object itself. |
getDefaultParseOptions
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
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. |
See Also
getGMTOffsetPattern
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
open fun getGMTPattern(): String!
Returns the localized GMT format pattern.
Return | |
---|---|
String! |
the localized GMT format pattern. |
See Also
getGMTZeroFormat
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. |
See Also
getInstance
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
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
open fun getTimeZoneNames(): TimeZoneNames!
Returns the time zone display name data used by this instance.
Return | |
---|---|
TimeZoneNames! |
the time zone display name data. |
See Also
isFrozen
open fun isFrozen(): Boolean
Determines whether the object has been frozen or not.
parse
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
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
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
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. |
See Also
parseObject
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
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
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. |
See Also
parseOffsetShortLocalizedGMT
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. |
See Also
setDefaultParseOptions
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
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. |
See Also
setGMTOffsetPattern
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
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
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. |
See Also
setTimeZoneNames
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. |
See Also