public class TimeZoneFormat extends UFormat implements Freezable<TimeZoneFormat>, Serializable
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.
SimpleDateFormat,
TimeZoneNames,
Serialized Form| Modifier and Type | Class and Description |
|---|---|
static class |
TimeZoneFormat.GMTOffsetPatternType
Offset pattern type enum.
|
static class |
TimeZoneFormat.ParseOption
Parse option enum, used for specifying optional parse behavior.
|
static class |
TimeZoneFormat.Style
Time zone display format style enum used by format/parse APIs in
TimeZoneFormat. |
static class |
TimeZoneFormat.TimeType
Time type enum used for receiving time type (standard time, daylight time or unknown)
in
TimeZoneFormat APIs. |
Format.Field| Modifier | Constructor and Description |
|---|---|
protected |
TimeZoneFormat(ULocale locale)
The protected constructor for subclassing.
|
| Modifier and Type | Method and Description |
|---|---|
TimeZoneFormat |
cloneAsThawed()
Provides for the clone operation.
|
StringBuffer |
format(Object obj,
StringBuffer toAppendTo,
FieldPosition pos)
Appends the specified object to the specified string buffer using the
rules of this format.
|
String |
format(TimeZoneFormat.Style style,
TimeZone tz,
long date)
Returns the display name of the time zone at the given date for
the style.
|
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.
|
String |
formatOffsetISO8601Basic(int offset,
boolean useUtcIndicator,
boolean isShort,
boolean ignoreSeconds)
Returns the ISO 8601 basic time zone string for the given offset.
|
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 the specified object using the rules of this format and returns
an
AttributedCharacterIterator with the formatted string and no
attributes. |
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 JDK 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.
|
TimeZone |
parse(String text)
Returns a
TimeZone for the given text. |
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,
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. |
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. |
Object |
parseObject(String source,
ParsePosition pos)
Parses the specified string starting at the index specified by
position. |
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.
|
clone, format, parseObjectprotected TimeZoneFormat(ULocale locale)
locale - the localepublic static TimeZoneFormat getInstance(ULocale locale)
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.
locale - the locale.TimeZoneFormat for the given locale.public static TimeZoneFormat getInstance(Locale locale)
TimeZoneFormat for the given JDK 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.
locale - the JDK locale.TimeZoneFormat for the given locale.public TimeZoneNames getTimeZoneNames()
setTimeZoneNames(TimeZoneNames)public TimeZoneFormat setTimeZoneNames(TimeZoneNames tznames)
tznames - the time zone display name data.UnsupportedOperationException - when this object is frozen.getTimeZoneNames()public String getGMTPattern()
setGMTPattern(String)public TimeZoneFormat setGMTPattern(String pattern)
pattern - the localized GMT format pattern stringIllegalArgumentException - when the pattern string does not contain "{0}"UnsupportedOperationException - when this object is frozen.getGMTPattern()public String getGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type)
type - the offset pattern enumsetGMTOffsetPattern(GMTOffsetPatternType, String)public TimeZoneFormat setGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type, String pattern)
type - the offset pattern.pattern - the pattern string.IllegalArgumentException - when the pattern string does not have required time field letters.UnsupportedOperationException - when this object is frozen.getGMTOffsetPattern(GMTOffsetPatternType)public String getGMTOffsetDigits()
setGMTOffsetDigits(String)public TimeZoneFormat setGMTOffsetDigits(String digits)
digits - a string contains the decimal digit characters from 0 to 9 n the ascending order.IllegalArgumentException - when the string did not contain ten characters.UnsupportedOperationException - when this object is frozen.getGMTOffsetDigits()public String getGMTZeroFormat()
setGMTZeroFormat(String)public TimeZoneFormat setGMTZeroFormat(String gmtZeroFormat)
gmtZeroFormat - the localized GMT format string for GMT(UTC).UnsupportedOperationException - when this object is frozen.getGMTZeroFormat()public TimeZoneFormat setDefaultParseOptions(EnumSet<TimeZoneFormat.ParseOption> options)
Note: By default, an instance of TimeZoneFormat>
created by {#link getInstance(ULocale) has no parse options set.
options - the default parse options.TimeZoneFormat.ParseOptionpublic EnumSet<TimeZoneFormat.ParseOption> getDefaultParseOptions()
TimeZoneFormat instance.TimeZoneFormat.ParseOptionpublic final String formatOffsetISO8601Basic(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds)
offset - the offset from GMT(UTC) in milliseconds.useUtcIndicator - true if ISO 8601 UTC indicator "Z" is used when the offset is 0.isShort - true if shortest form is used.ignoreSeconds - true if non-zero offset seconds is appended.IllegalArgumentException - if the specified offset is out of supported range
(-24 hours < offset < +24 hours).formatOffsetISO8601Extended(int, boolean, boolean, boolean),
parseOffsetISO8601(String, ParsePosition)public final String formatOffsetISO8601Extended(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds)
offset - the offset from GMT(UTC) in milliseconds.useUtcIndicator - true if ISO 8601 UTC indicator "Z" is used when the offset is 0.isShort - true if shortest form is used.ignoreSeconds - true if non-zero offset seconds is appended.IllegalArgumentException - if the specified offset is out of supported range
(-24 hours < offset < +24 hours).formatOffsetISO8601Basic(int, boolean, boolean, boolean),
parseOffsetISO8601(String, ParsePosition)public String formatOffsetLocalizedGMT(int offset)
getGMTPattern())
getGMTOffsetPattern(GMTOffsetPatternType))
getGMTOffsetDigits())
getGMTZeroFormat())
offset - the offset from GMT(UTC) in milliseconds.IllegalArgumentException - if the specified offset is out of supported range
(-24 hours < offset < +24 hours).parseOffsetLocalizedGMT(String, ParsePosition)public String formatOffsetShortLocalizedGMT(int offset)
getGMTPattern())
getGMTOffsetPattern(GMTOffsetPatternType))
getGMTOffsetDigits())
getGMTZeroFormat())
offset - the offset from GMT(UTC) in milliseconds.IllegalArgumentException - if the specified offset is out of supported range
(-24 hours < offset < +24 hours).parseOffsetLocalizedGMT(String, ParsePosition)public final String format(TimeZoneFormat.Style style, TimeZone tz, long date)
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.
style - the style enum (e.g. GENERIC_LONG, LOCALIZED_GMT...)tz - the time zone.date - the date.TimeZoneFormat.Style,
format(Style, TimeZone, long, Output)public String format(TimeZoneFormat.Style style, TimeZone tz, long date, Output<TimeZoneFormat.TimeType> timeType)
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.style - the style enum (e.g. GENERIC_LONG, LOCALIZED_GMT...)tz - the time zone.date - the date.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.TimeZoneFormat.Style,
format(Style, TimeZone, long)public final int parseOffsetISO8601(String text, ParsePosition pos)
ParsePosition pos and returns 0.text - the text contains ISO 8601 style time zone string (e.g. "-08", "-0800", "-08:00", and "Z")
at the position.pos - the position.formatOffsetISO8601Basic(int, boolean, boolean, boolean),
formatOffsetISO8601Extended(int, boolean, boolean, boolean)public int parseOffsetLocalizedGMT(String text, ParsePosition pos)
ParsePosition pos
and returns 0.text - the text contains a localized GMT offset string at the position.pos - the position.formatOffsetLocalizedGMT(int)public int parseOffsetShortLocalizedGMT(String text, ParsePosition pos)
ParsePosition pos
and returns 0.text - the text contains a short localized GMT offset string at the position.pos - the position.formatOffsetShortLocalizedGMT(int)public TimeZone parse(TimeZoneFormat.Style style, String text, ParsePosition pos, EnumSet<TimeZoneFormat.ParseOption> options, Output<TimeZoneFormat.TimeType> timeType)
TimeZone by parsing the time zone string according to
the parse position, the style and the parse options.text - the text contains a time zone string at the position.style - the format style.pos - the position.options - the parse options.timeType - The output argument for receiving the time type (standard/daylight/unknown),
or specify null if the information is not necessary.TimeZone, or null if the input could not be parsed.TimeZoneFormat.Style,
format(Style, TimeZone, long, Output)public TimeZone parse(TimeZoneFormat.Style style, String text, ParsePosition pos, Output<TimeZoneFormat.TimeType> timeType)
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).
text - the text contains a time zone string at the position.style - the format stylepos - the position.timeType - The output argument for receiving the time type (standard/daylight/unknown),
or specify null if the information is not necessary.TimeZone, or null if the input could not be parsed.TimeZoneFormat.Style,
parse(Style, String, ParsePosition, EnumSet, Output),
format(Style, TimeZone, long, Output),
setDefaultParseOptions(EnumSet)public final TimeZone parse(String text, ParsePosition pos)
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).
text - the text contains a time zone string at the position.pos - the position.TimeZone, or null if the input could not be parsed.parse(Style, String, ParsePosition, EnumSet, Output)public final TimeZone parse(String text) throws ParseException
TimeZone for the given text.
Note: The behavior of this method is equivalent to parse(String, ParsePosition).
text - the time zone stringTimeZone.ParseException - when the input could not be parsed as a time zone string.parse(String, ParsePosition)public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
field is an input/output parameter. If its field
member contains an enum value specifying a field on input, then its
beginIndex and endIndex members will be updated with the
text offset of the first occurrence of this field in the formatted text.
public AttributedCharacterIterator formatToCharacterIterator(Object obj)
AttributedCharacterIterator with the formatted string and no
attributes.
Subclasses should return an AttributedCharacterIterator with the
appropriate attributes.
formatToCharacterIterator in class Formatobj - the object to format.AttributedCharacterIterator with the formatted object
and attributes.public Object parseObject(String source, ParsePosition pos)
position. If the string is successfully parsed then the index of
the ParsePosition is updated to the index following the parsed
text. On error, the index is unchanged and the error index of
ParsePosition is set to the index where the error occurred.parseObject in class Formatsource - the string to parse.pos - input/output parameter, specifies the start index in
string from where to start parsing. If parsing is
successful, it is updated with the index following the parsed
text; on error, the index is unchanged and the error index is
set to the index where the error occurred.null if there is
an error.public boolean isFrozen()
isFrozen in interface Freezable<TimeZoneFormat>public TimeZoneFormat freeze()
freeze in interface Freezable<TimeZoneFormat>public TimeZoneFormat cloneAsThawed()
cloneAsThawed in interface Freezable<TimeZoneFormat>