TimeZoneFormat

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.

Nested Class Summary

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 Constructor Summary

TimeZoneFormat(ULocale locale)
The protected constructor for subclassing.

Public Method Summary

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 Method Summary

Protected Constructors

protected TimeZoneFormat (ULocale locale)

The protected constructor for subclassing.

Parameters
locale the locale

Public Methods

public TimeZoneFormat cloneAsThawed ()

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

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 The object to format
toAppendTo where the text is to be appended
pos A FieldPosition identifying a field in the formatted text
Returns
  • the string buffer passed in as toAppendTo, with formatted text appended

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 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.
Returns
  • the display name of the time zone.

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 the style enum (e.g. GENERIC_LONG, LOCALIZED_GMT...)
tz the time zone.
date the date.
Returns
  • the display name of the time zone.

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 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.
Returns
  • the ISO 8601 basic format.
Throws
IllegalArgumentException if the specified offset is out of supported range (-24 hours < offset < +24 hours).

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 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.
Returns
  • the ISO 8601 extended format.
Throws
IllegalArgumentException if the specified offset is out of supported range (-24 hours < offset < +24 hours).

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 the offset from GMT(UTC) in milliseconds.
Returns
  • the localized GMT format string
Throws
IllegalArgumentException if the specified offset is out of supported range (-24 hours < offset < +24 hours).

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 the offset from GMT(UTC) in milliseconds.
Returns
  • the short localized GMT format string
Throws
IllegalArgumentException if the specified offset is out of supported range (-24 hours < offset < +24 hours).

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 The object to format
Returns
  • AttributedCharacterIterator describing the formatted value.

public TimeZoneFormat freeze ()

Freezes the object.

Returns
  • the object itself.

public EnumSet<TimeZoneFormat.ParseOption> getDefaultParseOptions ()

Returns the default parse options used by this TimeZoneFormat instance.

Returns
  • the default parse options.

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
  • the decimal digits for localized GMT format.

public String getGMTOffsetPattern (TimeZoneFormat.GMTOffsetPatternType type)

Returns the offset pattern used for localized GMT format.

Parameters
type the offset pattern enum

public String getGMTPattern ()

Returns the localized GMT format pattern.

Returns
  • the localized GMT format pattern.

public String getGMTZeroFormat ()

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

Returns
  • the localized GMT string string for GMT(UTC) itself.

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 the Locale.
Returns
  • a frozen instance of TimeZoneFormat for the given locale.

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

public TimeZoneNames getTimeZoneNames ()

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

Returns
  • the time zone display name data.

public boolean isFrozen ()

Determines whether the object has been frozen or not.

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 the time zone string
Returns
  • A TimeZone.
Throws
ParseException when the input could not be parsed as a time zone string.

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 the text contains a time zone string at the position.
pos the position.
Returns
  • A TimeZone, or null if the input could not be parsed.

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

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 the format style.
text the text contains a time zone string at the position.
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.
Returns
  • A TimeZone, or null if the input could not be parsed.

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 A String, part of which should be parsed.
pos A ParsePosition object with index and error index information as described above.
Returns
  • An Object parsed from the string. In case of error, returns null.

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 the text contains ISO 8601 style time zone string (e.g. "-08", "-0800", "-08:00", and "Z") at the position.
pos the position.
Returns
  • the offset from GMT(UTC) in milliseconds for the given ISO 8601 style time zone string.

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 the text contains a localized GMT offset string at the position.
pos the position.
Returns
  • the offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.

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 the text contains a short localized GMT offset string at the position.
pos the position.
Returns
  • the offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string.

public TimeZoneFormat setDefaultParseOptions (EnumSet<TimeZoneFormat.ParseOption> options)

Sets the default parse options.

Note: By default, an instance of TimeZoneFormat created by getInstance(ULocale) has no parse options set.

Parameters
options the default parse options.
Returns
  • this object.

public TimeZoneFormat setGMTOffsetDigits (String digits)

Sets the decimal digit characters used for localized GMT format.

Parameters
digits a string contains the decimal digit characters from 0 to 9 n the ascending order.
Returns
  • this object.
Throws
IllegalArgumentException when the string did not contain ten characters.
UnsupportedOperationException when this object is frozen.

public TimeZoneFormat setGMTOffsetPattern (TimeZoneFormat.GMTOffsetPatternType type, String pattern)

Sets the offset pattern for the given offset type.

Parameters
type the offset pattern.
pattern the pattern string.
Returns
  • this object.
Throws
IllegalArgumentException when the pattern string does not have required time field letters.
UnsupportedOperationException when this object is frozen.

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 the localized GMT format pattern string
Returns
  • this object.
Throws
IllegalArgumentException when the pattern string does not contain "{0}"
UnsupportedOperationException when this object is frozen.
See Also

public TimeZoneFormat setGMTZeroFormat (String gmtZeroFormat)

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

Parameters
gmtZeroFormat the localized GMT format string for GMT(UTC).
Returns
  • this object.
Throws
UnsupportedOperationException when this object is frozen.

public TimeZoneFormat setTimeZoneNames (TimeZoneNames tznames)

Sets the time zone display name data to this instance.

Parameters
tznames the time zone display name data.
Returns
  • this object.
Throws
UnsupportedOperationException when this object is frozen.