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:
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 |
enum |
TimeZoneFormat.TimeType
Time type enum used for receiving time type (standard time, daylight time or unknown)
in |
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 |
TimeZoneFormat
|
freeze()
Freezes the object. |
EnumSet<TimeZoneFormat.ParseOption>
|
getDefaultParseOptions()
Returns the default parse options used by this |
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 |
static
TimeZoneFormat
|
getInstance(ULocale locale)
Returns a frozen instance of |
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 |
final
TimeZone
|
parse(String text, ParsePosition pos)
Returns a |
TimeZone
|
parse(TimeZoneFormat.Style style, String text, ParsePosition pos, Output<TimeZoneFormat.TimeType> timeType)
Returns a |
TimeZone
|
parse(TimeZoneFormat.Style style, String text, ParsePosition pos, EnumSet<TimeZoneFormat.ParseOption> options, Output<TimeZoneFormat.TimeType> timeType)
Returns a |
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
| |
From
class
java.lang.Object
| |
From
interface
android.icu.util.Freezable
| |
TimeZoneFormat (ULocale locale)
The protected constructor for subclassing.
| Parameters | |
|---|---|
locale |
ULocale:
the locale
|
TimeZoneFormat cloneAsThawed ()
Provides for the clone operation. Any clone is initially unfrozen.
| Returns | |
|---|---|
TimeZoneFormat |
|
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 |
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. |
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. |
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). |
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). |
String formatOffsetLocalizedGMT (int offset)
Returns the localized GMT(UTC) offset format for the given offset. The localized GMT offset is defined by;
Developers
getGMTPattern())
getGMTOffsetPattern(GMTOffsetPatternType))
getGMTOffsetDigits())
getGMTZeroFormat())
| 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). |
String formatOffsetShortLocalizedGMT (int offset)
Returns the short localized GMT(UTC) offset format for the given offset. The short localized GMT offset is defined by;
getGMTPattern())
getGMTOffsetPattern(GMTOffsetPatternType))
getGMTOffsetDigits())
getGMTZeroFormat())
| 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). |
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. |
TimeZoneFormat freeze ()
Freezes the object.
| Returns | |
|---|---|
TimeZoneFormat |
the object itself. |
EnumSet<TimeZoneFormat.ParseOption> getDefaultParseOptions ()
Returns the default parse options used by this TimeZoneFormat instance.
| Returns | |
|---|---|
EnumSet<TimeZoneFormat.ParseOption> |
the default parse options. |
See also:
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:
String getGMTOffsetPattern (TimeZoneFormat.GMTOffsetPatternType type)
Returns the offset pattern used for localized GMT format.
| Parameters | |
|---|---|
type |
TimeZoneFormat.GMTOffsetPatternType:
the offset pattern enum |
| Returns | |
|---|---|
String |
|
String getGMTPattern ()
Returns the localized GMT format pattern.
| Returns | |
|---|---|
String |
the localized GMT format pattern. |
See also:
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:
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.
|
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.
|
TimeZoneNames getTimeZoneNames ()
Returns the time zone display name data used by this instance.
| Returns | |
|---|---|
TimeZoneNames |
the time zone display name data. |
See also:
boolean isFrozen ()
Determines whether the object has been frozen or not.
| Returns | |
|---|---|
boolean |
|
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. |
See also:
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. |
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. |
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. |
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. |
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. |
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:
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:
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. |
See also:
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:
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. |
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:
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:
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: