com.ibm.icu.text
Class TimeZoneFormat

java.lang.Object
  java.text.Format
      com.ibm.icu.text.UFormat
          com.ibm.icu.text.TimeZoneFormat

All Implemented Interfaces:

Freezable<TimeZoneFormat>, Serializable, Cloneable

Deprecated. This API might change or be removed in a future release.

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.

See Also:

SimpleDateFormat, TimeZoneNames, Serialized Form

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

Nested Class Summary

static class	TimeZoneFormat.GMTOffsetPatternType Deprecated. This API might change or be removed in a future release.
static class	TimeZoneFormat.Style Deprecated. This API might change or be removed in a future release.
static class	TimeZoneFormat.TimeType Deprecated. This API might change or be removed in a future release.

Nested classes/interfaces inherited from class java.text.Format

Format.Field

Constructor Summary

protected

TimeZoneFormat(ULocale locale) Deprecated. This API might change or be removed in a future release.

Method Summary

TimeZoneFormat	cloneAsThawed() Deprecated. This API might change or be removed in a future release.
StringBuffer	format(Object obj, StringBuffer toAppendTo, FieldPosition pos) Deprecated. This API might change or be removed in a future release.
String	format(TimeZoneFormat.Style style, TimeZone tz, long date) Deprecated. This API might change or be removed in a future release.
String	format(TimeZoneFormat.Style style, TimeZone tz, long date, Output<TimeZoneFormat.TimeType> timeType) Deprecated. This API might change or be removed in a future release.
String	formatOffsetLocalizedGMT(int offset) Deprecated. This API might change or be removed in a future release.
String	formatOffsetRFC822(int offset) Deprecated. This API might change or be removed in a future release.
AttributedCharacterIterator	formatToCharacterIterator(Object obj) Deprecated. This API might change or be removed in a future release.
TimeZoneFormat	freeze() Deprecated. This API might change or be removed in a future release.
String	getGMTOffsetDigits() Deprecated. This API might change or be removed in a future release.
String	getGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type) Deprecated. This API might change or be removed in a future release.
String	getGMTPattern() Deprecated. This API might change or be removed in a future release.
String	getGMTZeroFormat() Deprecated. This API might change or be removed in a future release.
static TimeZoneFormat	getInstance(ULocale locale) Deprecated. This API might change or be removed in a future release.
TimeZoneNames	getTimeZoneNames() Deprecated. This API might change or be removed in a future release.
boolean	isFrozen() Deprecated. This API might change or be removed in a future release.
boolean	isParseAllStyles() Deprecated. This API might change or be removed in a future release.
TimeZone	parse(String text) Deprecated. This API might change or be removed in a future release.
TimeZone	parse(String text, ParsePosition pos) Deprecated. This API might change or be removed in a future release.
TimeZone	parse(TimeZoneFormat.Style style, String text, ParsePosition pos, Output<TimeZoneFormat.TimeType> timeType) Deprecated. This API might change or be removed in a future release.
Object	parseObject(String source, ParsePosition pos) Deprecated. This API might change or be removed in a future release.
int	parseOffsetLocalizedGMT(String text, ParsePosition pos) Deprecated. This API might change or be removed in a future release.
int	parseOffsetRFC822(String text, ParsePosition pos) Deprecated. This API might change or be removed in a future release.
TimeZoneFormat	setGMTOffsetDigits(String digits) Deprecated. This API might change or be removed in a future release.
TimeZoneFormat	setGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type, String pattern) Deprecated. This API might change or be removed in a future release.
TimeZoneFormat	setGMTPattern(String pattern) Deprecated. This API might change or be removed in a future release.
TimeZoneFormat	setGMTZeroFormat(String gmtZeroFormat) Deprecated. This API might change or be removed in a future release.
TimeZoneFormat	setParseAllStyles(boolean parseAllStyles) Deprecated. This API might change or be removed in a future release.
TimeZoneFormat	setTimeZoneNames(TimeZoneNames tznames) Deprecated. This API might change or be removed in a future release.

Methods inherited from class com.ibm.icu.text.UFormat

getLocale

Methods inherited from class java.text.Format

clone, format, parseObject

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TimeZoneFormat

protected TimeZoneFormat(ULocale locale)

Deprecated. This API might change or be removed in a future release.

The protected constructor for subclassing.

Parameters:

locale - the locale

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

Method Detail

getInstance

public static TimeZoneFormat getInstance(ULocale locale)

Deprecated. This API might change or be removed in a future release.

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.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getTimeZoneNames

public TimeZoneNames getTimeZoneNames()

Deprecated. This API might change or be removed in a future release.

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

Returns:

the time zone display name data.

See Also:

setTimeZoneNames(TimeZoneNames)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

setTimeZoneNames

public TimeZoneFormat setTimeZoneNames(TimeZoneNames tznames)

Deprecated. This API might change or be removed in a future release.

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.

See Also:

getTimeZoneNames()

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getGMTPattern

public String getGMTPattern()

Deprecated. This API might change or be removed in a future release.

Returns the localized GMT format pattern.

Returns:

the localized GMT format pattern.

See Also:

setGMTPattern(String)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

setGMTPattern

public TimeZoneFormat setGMTPattern(String pattern)

Deprecated. This API might change or be removed in a future release.

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:

getGMTPattern()

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getGMTOffsetPattern

public String getGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type)

Deprecated. This API might change or be removed in a future release.

Returns the offset pattern used for localized GMT format.

Parameters:

type - the offset pattern enum

Returns:

the offset pattern enum.

See Also:

setGMTOffsetPattern(GMTOffsetPatternType, String)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

setGMTOffsetPattern

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

Deprecated. This API might change or be removed in a future release.

Sets the offset pattern for the given offset type.

Parameters:

type - the offset pettern.

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.

See Also:

getGMTOffsetPattern(GMTOffsetPatternType)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getGMTOffsetDigits

public String getGMTOffsetDigits()

Deprecated. This API might change or be removed in a future release.

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.

See Also:

setGMTOffsetDigits(String)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

setGMTOffsetDigits

public TimeZoneFormat setGMTOffsetDigits(String digits)

Deprecated. This API might change or be removed in a future release.

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.

See Also:

getGMTOffsetDigits()

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getGMTZeroFormat

public String getGMTZeroFormat()

Deprecated. This API might change or be removed in a future release.

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

Returns:

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

See Also:

setGMTZeroFormat(String)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

setGMTZeroFormat

public TimeZoneFormat setGMTZeroFormat(String gmtZeroFormat)

Deprecated. This API might change or be removed in a future release.

Returns 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.

See Also:

getGMTZeroFormat()

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

isParseAllStyles

public boolean isParseAllStyles()

Deprecated. This API might change or be removed in a future release.

Returns true when this TimeZoneFormat is configured for parsing display names including names that are only used by other styles by parse(Style, String, ParsePosition, Output).

Note: An instance created by getInstance(ULocale) is configured NOT parsing all styles (false).

Returns:

true when this instance is configure for parsing all available names.

See Also:

setParseAllStyles(boolean)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

setParseAllStyles

public TimeZoneFormat setParseAllStyles(boolean parseAllStyles)

Deprecated. This API might change or be removed in a future release.

Sets if parse(Style, String, ParsePosition, Output) to parse display names including names that are only used by other styles.

Parameters:

parseAllStyles - true to parse all available names.

Returns:

this object.

Throws:

UnsupportedOperationException - when this object is frozen.

See Also:

isParseAllStyles()

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

formatOffsetRFC822

public final String formatOffsetRFC822(int offset)

Deprecated. This API might change or be removed in a future release.

Returns the RFC822 style time zone string for the given offset. For example, "-0800".

Parameters:

offset - the offset for GMT(UTC) in milliseconds.

Returns:

the RFC822 style GMT(UTC) offset format.

See Also:

parseOffsetRFC822(String, ParsePosition)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

formatOffsetLocalizedGMT

public String formatOffsetLocalizedGMT(int offset)

Deprecated. This API might change or be removed in a future release.

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(GMTOffsetPatternType))
• Offset digits (e.g. "0123456789" - see getGMTOffsetDigits())
• GMT zero format (e.g. "GMT" - see getGMTZeroFormat())

Parameters:

offset - the offset from GMT(UTC) in milliseconds.

Returns:

the localized GMT format string

See Also:

parseOffsetLocalizedGMT(String, ParsePosition)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

format

public final String format(TimeZoneFormat.Style style,
                           TimeZone tz,
                           long date)

Deprecated. This API might change or be removed in a future release.

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.

See Also:

TimeZoneFormat.Style, format(Style, TimeZone, long, Output)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

format

public String format(TimeZoneFormat.Style style,
                     TimeZone tz,
                     long date,
                     Output<TimeZoneFormat.TimeType> timeType)

Deprecated. This API might change or be removed in a future release.

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.

See Also:

TimeZoneFormat.Style, format(Style, TimeZone, long)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

parseOffsetRFC822

public final int parseOffsetRFC822(String text,
                                   ParsePosition pos)

Deprecated. This API might change or be removed in a future release.

Returns offset from GMT(UTC) in milliseconds for the given RFC822 style time zone string. When the given string is not an RFC822 time zone string, this method sets the current position as the error index to ParsePosition pos and returns 0.

Parameters:

text - the text contains RFC822 style time zone string (e.g. "-0800") at the position.

pos - the position.

Returns:

the offset from GMT(UTC) in milliseconds for the given RFC822 style time zone string.

See Also:

formatOffsetRFC822(int)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

parseOffsetLocalizedGMT

public int parseOffsetLocalizedGMT(String text,
                                   ParsePosition pos)

Deprecated. This API might change or be removed in a future release.

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.

See Also:

formatOffsetLocalizedGMT(int)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

parse

public TimeZone parse(TimeZoneFormat.Style style,
                      String text,
                      ParsePosition pos,
                      Output<TimeZoneFormat.TimeType> timeType)

Deprecated. This API might change or be removed in a future release.

Returns a TimeZone by parsing the time zone string according to the given parse position.

Note: By default, this method supports 1) RFC822 style time zone format, 2) Localized GMT offset format and 3) all display names that are used for the given style. If you want to parse all display names including names that are only used for styles other than the specified style, then you should set true to setParseAllStyles(boolean).

Parameters:

text - the text contains a time zone string at the position.

style - the format style

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.

See Also:

TimeZoneFormat.Style, format(Style, TimeZone, long, Output), setParseAllStyles(boolean)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

parse

public final TimeZone parse(String text,
                            ParsePosition pos)

Deprecated. This API might change or be removed in a future release.

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, null) with setParseAllStyles(true).

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.

See Also:

parse(Style, String, ParsePosition, Output)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

parse

public final TimeZone parse(String text)
                     throws ParseException

Deprecated. This API might change or be removed in a future release.

Returns a TimeZone for the given text.

Parameters:

text - the time zone string

Returns:

A TimeZone.

Throws:

ParseException - when the input could not be parsed as a time zone string.

See Also:

parse(String, ParsePosition), parse(Style, String, ParsePosition, Output)

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

format

public StringBuffer format(Object obj,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Deprecated. This API might change or be removed in a future release.

Specified by:

format in class Format

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

Deprecated. This API might change or be removed in a future release.

Overrides:

formatToCharacterIterator in class Format

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

parseObject

public Object parseObject(String source,
                          ParsePosition pos)

Deprecated. This API might change or be removed in a future release.

Specified by:

parseObject in class Format

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

isFrozen

public boolean isFrozen()

Deprecated. This API might change or be removed in a future release.

Determines whether the object has been frozen or not.

Specified by:

isFrozen in interface Freezable<TimeZoneFormat>

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

freeze

public TimeZoneFormat freeze()

Deprecated. This API might change or be removed in a future release.

Freezes the object.

Specified by:

freeze in interface Freezable<TimeZoneFormat>

Returns:

the object itself.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

cloneAsThawed

public TimeZoneFormat cloneAsThawed()

Deprecated. This API might change or be removed in a future release.

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

Specified by:

cloneAsThawed in interface Freezable<TimeZoneFormat>

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.