Class TimeZoneFormat
- java.lang.Object
-
- java.text.Format
-
- com.ibm.icu.text.UFormat
-
- com.ibm.icu.text.TimeZoneFormat
-
- All Implemented Interfaces:
Freezable<TimeZoneFormat>
,java.io.Serializable
,java.lang.Cloneable
public class TimeZoneFormat extends UFormat implements Freezable<TimeZoneFormat>, java.io.Serializable
TimeZoneFormat
supports time zone display name formatting and parsing. An instance of TimeZoneFormat works as a subformatter ofSimpleDateFormat
, but you can also directly get a new instance ofTimeZoneFormat
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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
TimeZoneFormat.GMTOffsetField
Used for representing localized GMT time fields in the parsed pattern object.static class
TimeZoneFormat.GMTOffsetPatternType
Offset pattern type enum.private static class
TimeZoneFormat.OffsetFields
Numeric offset field combinationsstatic 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 inTimeZoneFormat
.static class
TimeZoneFormat.TimeType
Time type enum used for receiving time type (standard time, daylight time or unknown) inTimeZoneFormat
APIs.private static class
TimeZoneFormat.TimeZoneFormatCache
ImplementsTimeZoneFormat
object cache-
Nested classes/interfaces inherited from class com.ibm.icu.text.UFormat
UFormat.SpanField
-
-
Field Summary
Fields Modifier and Type Field Description private boolean
_abuttingOffsetHoursAndMinutes
private boolean
_frozen
private java.lang.String[]
_gmtOffsetDigits
private java.lang.Object[][]
_gmtOffsetPatternItems
private java.lang.String[]
_gmtOffsetPatterns
private java.lang.String
_gmtPattern
private java.lang.String
_gmtPatternPrefix
private java.lang.String
_gmtPatternSuffix
private java.lang.String
_gmtZeroFormat
private TimeZoneGenericNames
_gnames
private ULocale
_locale
private boolean
_parseAllStyles
private boolean
_parseTZDBNames
private java.lang.String
_region
private TimeZoneNames
_tzdbNames
private static TimeZoneFormat.TimeZoneFormatCache
_tzfCache
private TimeZoneNames
_tznames
private static java.util.EnumSet<TimeZoneGenericNames.GenericNameType>
ALL_GENERIC_NAME_TYPES
private static java.util.EnumSet<TimeZoneNames.NameType>
ALL_SIMPLE_NAME_TYPES
private static java.lang.String[]
ALT_GMT_STRINGS
private static java.lang.String
ASCII_DIGITS
private static java.lang.String[]
DEFAULT_GMT_DIGITS
private static char
DEFAULT_GMT_OFFSET_SEP
private static java.lang.String
DEFAULT_GMT_PATTERN
private static java.lang.String
DEFAULT_GMT_ZERO
private static int
ISO_LOCAL_STYLE_FLAG
private static int
ISO_Z_STYLE_FLAG
private static java.lang.String
ISO8601_UTC
private static int
MAX_OFFSET
private static int
MAX_OFFSET_HOUR
private static int
MAX_OFFSET_MINUTE
private static int
MAX_OFFSET_SECOND
private static int
MILLIS_PER_HOUR
private static int
MILLIS_PER_MINUTE
private static int
MILLIS_PER_SECOND
private static TimeZoneFormat.GMTOffsetPatternType[]
PARSE_GMT_OFFSET_TYPES
private static java.io.ObjectStreamField[]
serialPersistentFields
private static long
serialVersionUID
private static TextTrieMap<java.lang.String>
SHORT_ZONE_ID_TRIE
private static java.lang.String
TZID_GMT
private static java.lang.String
UNKNOWN_LOCATION
private static int
UNKNOWN_OFFSET
private static java.lang.String
UNKNOWN_SHORT_ZONE_ID
private static java.lang.String
UNKNOWN_ZONE_ID
private static TextTrieMap<java.lang.String>
ZONE_ID_TRIE
-
Constructor Summary
Constructors Modifier Constructor Description protected
TimeZoneFormat(ULocale locale)
The protected constructor for subclassing.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private void
appendOffsetDigits(java.lang.StringBuilder buf, int n, int minDigits)
Appends localized digits to the buffer.private void
checkAbuttingHoursAndMinutes()
TimeZoneFormat
cloneAsThawed()
Provides for the clone operation.private static java.lang.String
expandOffsetPattern(java.lang.String offsetHM)
Appends seconds field to the offset pattern with hour/minutejava.lang.String
format(TimeZoneFormat.Style style, TimeZone tz, long date)
Returns the display name of the time zone at the given date for the style.java.lang.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.java.lang.StringBuffer
format(java.lang.Object obj, java.lang.StringBuffer toAppendTo, java.text.FieldPosition pos)
private java.lang.String
formatExemplarLocation(TimeZone tz)
Private method returning the time zone's exemplar location string.private java.lang.String
formatOffsetISO8601(int offset, boolean isBasic, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds)
java.lang.String
formatOffsetISO8601Basic(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds)
Returns the ISO 8601 basic time zone string for the given offset.java.lang.String
formatOffsetISO8601Extended(int offset, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds)
Returns the ISO 8601 extended time zone string for the given offset.java.lang.String
formatOffsetLocalizedGMT(int offset)
Returns the localized GMT(UTC) offset format for the given offset.private java.lang.String
formatOffsetLocalizedGMT(int offset, boolean isShort)
Private method used for localized GMT formatting.java.lang.String
formatOffsetShortLocalizedGMT(int offset)
Returns the short localized GMT(UTC) offset format for the given offset.private java.lang.String
formatSpecific(TimeZone tz, TimeZoneNames.NameType stdType, TimeZoneNames.NameType dstType, long date, Output<TimeZoneFormat.TimeType> timeType)
Private method returning the time zone's specific format string.java.text.AttributedCharacterIterator
formatToCharacterIterator(java.lang.Object obj)
TimeZoneFormat
freeze()
Freezes the object.java.util.EnumSet<TimeZoneFormat.ParseOption>
getDefaultParseOptions()
Returns the default parse options used by thisTimeZoneFormat
instance.java.lang.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.java.lang.String
getGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type)
Returns the offset pattern used for localized GMT format.java.lang.String
getGMTPattern()
Returns the localized GMT format pattern.java.lang.String
getGMTZeroFormat()
Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0).static TimeZoneFormat
getInstance(ULocale locale)
Returns a frozen instance ofTimeZoneFormat
for the given locale.static TimeZoneFormat
getInstance(java.util.Locale locale)
Returns a frozen instance ofTimeZoneFormat
for the givenLocale
.private java.lang.String
getTargetRegion()
Private method returning the target region.private TimeZoneFormat.TimeType
getTimeType(TimeZoneNames.NameType nameType)
Returns the time type for the given name typeprivate TimeZone
getTimeZoneForOffset(int offset)
Creates an instance of TimeZone for the given offsetprivate TimeZoneGenericNames
getTimeZoneGenericNames()
Private method returning the instance of TimeZoneGenericNames used by this object.private java.lang.String
getTimeZoneID(java.lang.String tzID, java.lang.String mzID)
Private method returns a time zone ID.TimeZoneNames
getTimeZoneNames()
Returns the time zone display name data used by this instance.private TimeZoneNames
getTZDBTimeZoneNames()
Private method returning the instance of TZDBTimeZoneNames.private void
initGMTOffsetPatterns(java.lang.String[] gmtOffsetPatterns)
Initialize localized GMT format offset hour/min/sec patterns.private void
initGMTPattern(java.lang.String gmtPattern)
Parses the localized GMT pattern string and initialize localized gmt pattern fields including#_gmtPatternTokens
.boolean
isFrozen()
Determines whether the object has been frozen or not.TimeZone
parse(TimeZoneFormat.Style style, java.lang.String text, java.text.ParsePosition pos, Output<TimeZoneFormat.TimeType> timeType)
Returns aTimeZone
by parsing the time zone string according to the parse position, the style and the default parse options.TimeZone
parse(TimeZoneFormat.Style style, java.lang.String text, java.text.ParsePosition pos, java.util.EnumSet<TimeZoneFormat.ParseOption> options, Output<TimeZoneFormat.TimeType> timeType)
Returns aTimeZone
by parsing the time zone string according to the parse position, the style and the parse options.TimeZone
parse(java.lang.String text)
Returns aTimeZone
for the given text.TimeZone
parse(java.lang.String text, java.text.ParsePosition pos)
Returns aTimeZone
by parsing the time zone string according to the given parse position.private static int
parseAbuttingAsciiOffsetFields(java.lang.String text, java.text.ParsePosition pos, TimeZoneFormat.OffsetFields minFields, TimeZoneFormat.OffsetFields maxFields, boolean fixedHourWidth)
Parses offset represented by contiguous ASCII digitsprivate int
parseAbuttingOffsetFields(java.lang.String text, int start, int[] parsedLen)
Parses abutting localized GMT offset fields (such as 0800) into offset.private static int
parseAsciiOffsetFields(java.lang.String text, java.text.ParsePosition pos, char sep, TimeZoneFormat.OffsetFields minFields, TimeZoneFormat.OffsetFields maxFields)
Parses offset represented by ASCII digits and separators.private int
parseDefaultOffsetFields(java.lang.String text, int start, char separator, int[] parsedLen)
Parses the input GMT offset fields with the default offset pattern.private java.lang.String
parseExemplarLocation(java.lang.String text, java.text.ParsePosition pos)
Parse an exemplar location string.java.lang.Object
parseObject(java.lang.String source, java.text.ParsePosition pos)
private int
parseOffsetDefaultLocalizedGMT(java.lang.String text, int start, int[] parsedLen)
Parses the input text using the default format patterns (e.g.private int
parseOffsetFields(java.lang.String text, int start, boolean isShort, int[] parsedLen)
Parses localized GMT offset fields into offset.private int
parseOffsetFieldsWithPattern(java.lang.String text, int start, java.lang.Object[] patternItems, boolean forceSingleHourDigit, int[] fields)
Parses localized GMT offset fields with the given patternprivate int
parseOffsetFieldWithLocalizedDigits(java.lang.String text, int start, int minDigits, int maxDigits, int minVal, int maxVal, int[] parsedLen)
Reads an offset field value.int
parseOffsetISO8601(java.lang.String text, java.text.ParsePosition pos)
Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 basic or extended time zone string.private static int
parseOffsetISO8601(java.lang.String text, java.text.ParsePosition pos, boolean extendedOnly, Output<java.lang.Boolean> hasDigitOffset)
Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 time zone string (basic format, extended format, or UTC indicator).int
parseOffsetLocalizedGMT(java.lang.String text, java.text.ParsePosition pos)
Returns offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.private int
parseOffsetLocalizedGMT(java.lang.String text, java.text.ParsePosition pos, boolean isShort, Output<java.lang.Boolean> hasDigitOffset)
Returns offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.private int
parseOffsetLocalizedGMTPattern(java.lang.String text, int start, boolean isShort, int[] parsedLen)
Parse localized GMT format generated by the pattern used by this formatter, except GMT Zero format.private static java.lang.Object[]
parseOffsetPattern(java.lang.String pattern, java.lang.String letters)
Parse the GMT offset pattern into runtime optimized formatint
parseOffsetShortLocalizedGMT(java.lang.String text, java.text.ParsePosition pos)
Returns offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string.private static java.lang.String
parseShortZoneID(java.lang.String text, java.text.ParsePosition pos)
Parse a short zone ID.private int
parseSingleLocalizedDigit(java.lang.String text, int start, int[] len)
Reads a single decimal digit, either localized digits used by this object or any Unicode numeric character.private static java.lang.String
parseZoneID(java.lang.String text, java.text.ParsePosition pos)
Parse a zone ID.private void
readObject(java.io.ObjectInputStream ois)
TimeZoneFormat
setDefaultParseOptions(java.util.EnumSet<TimeZoneFormat.ParseOption> options)
Sets the default parse options.TimeZoneFormat
setGMTOffsetDigits(java.lang.String digits)
Sets the decimal digit characters used for localized GMT format.TimeZoneFormat
setGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type, java.lang.String pattern)
Sets the offset pattern for the given offset type.TimeZoneFormat
setGMTPattern(java.lang.String pattern)
Sets the localized GMT format pattern.TimeZoneFormat
setGMTZeroFormat(java.lang.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.private static java.lang.String[]
toCodePoints(java.lang.String str)
Break input String into String[].private static java.lang.String
truncateOffsetPattern(java.lang.String offsetHM)
Truncates minutes field from the offset pattern with hour/minuteprivate static java.lang.String
unquote(java.lang.String s)
Unquotes the message format style pattern.private void
writeObject(java.io.ObjectOutputStream oos)
-
-
-
Field Detail
-
serialVersionUID
private static final long serialVersionUID
- See Also:
- Constant Field Values
-
ISO_Z_STYLE_FLAG
private static final int ISO_Z_STYLE_FLAG
- See Also:
- Constant Field Values
-
ISO_LOCAL_STYLE_FLAG
private static final int ISO_LOCAL_STYLE_FLAG
- See Also:
- Constant Field Values
-
_locale
private ULocale _locale
-
_tznames
private TimeZoneNames _tznames
-
_gmtPattern
private java.lang.String _gmtPattern
-
_gmtOffsetPatterns
private java.lang.String[] _gmtOffsetPatterns
-
_gmtOffsetDigits
private java.lang.String[] _gmtOffsetDigits
-
_gmtZeroFormat
private java.lang.String _gmtZeroFormat
-
_parseAllStyles
private boolean _parseAllStyles
-
_parseTZDBNames
private boolean _parseTZDBNames
-
_gnames
private transient volatile TimeZoneGenericNames _gnames
-
_gmtPatternPrefix
private transient java.lang.String _gmtPatternPrefix
-
_gmtPatternSuffix
private transient java.lang.String _gmtPatternSuffix
-
_gmtOffsetPatternItems
private transient java.lang.Object[][] _gmtOffsetPatternItems
-
_abuttingOffsetHoursAndMinutes
private transient boolean _abuttingOffsetHoursAndMinutes
-
_region
private transient java.lang.String _region
-
_frozen
private transient volatile boolean _frozen
-
_tzdbNames
private transient volatile TimeZoneNames _tzdbNames
-
TZID_GMT
private static final java.lang.String TZID_GMT
- See Also:
- Constant Field Values
-
ALT_GMT_STRINGS
private static final java.lang.String[] ALT_GMT_STRINGS
-
DEFAULT_GMT_PATTERN
private static final java.lang.String DEFAULT_GMT_PATTERN
- See Also:
- Constant Field Values
-
DEFAULT_GMT_ZERO
private static final java.lang.String DEFAULT_GMT_ZERO
- See Also:
- Constant Field Values
-
DEFAULT_GMT_DIGITS
private static final java.lang.String[] DEFAULT_GMT_DIGITS
-
DEFAULT_GMT_OFFSET_SEP
private static final char DEFAULT_GMT_OFFSET_SEP
- See Also:
- Constant Field Values
-
ASCII_DIGITS
private static final java.lang.String ASCII_DIGITS
- See Also:
- Constant Field Values
-
ISO8601_UTC
private static final java.lang.String ISO8601_UTC
- See Also:
- Constant Field Values
-
UNKNOWN_ZONE_ID
private static final java.lang.String UNKNOWN_ZONE_ID
- See Also:
- Constant Field Values
-
UNKNOWN_SHORT_ZONE_ID
private static final java.lang.String UNKNOWN_SHORT_ZONE_ID
- See Also:
- Constant Field Values
-
UNKNOWN_LOCATION
private static final java.lang.String UNKNOWN_LOCATION
- See Also:
- Constant Field Values
-
PARSE_GMT_OFFSET_TYPES
private static final TimeZoneFormat.GMTOffsetPatternType[] PARSE_GMT_OFFSET_TYPES
-
MILLIS_PER_HOUR
private static final int MILLIS_PER_HOUR
- See Also:
- Constant Field Values
-
MILLIS_PER_MINUTE
private static final int MILLIS_PER_MINUTE
- See Also:
- Constant Field Values
-
MILLIS_PER_SECOND
private static final int MILLIS_PER_SECOND
- See Also:
- Constant Field Values
-
MAX_OFFSET
private static final int MAX_OFFSET
- See Also:
- Constant Field Values
-
MAX_OFFSET_HOUR
private static final int MAX_OFFSET_HOUR
- See Also:
- Constant Field Values
-
MAX_OFFSET_MINUTE
private static final int MAX_OFFSET_MINUTE
- See Also:
- Constant Field Values
-
MAX_OFFSET_SECOND
private static final int MAX_OFFSET_SECOND
- See Also:
- Constant Field Values
-
UNKNOWN_OFFSET
private static final int UNKNOWN_OFFSET
- See Also:
- Constant Field Values
-
_tzfCache
private static TimeZoneFormat.TimeZoneFormatCache _tzfCache
-
ALL_SIMPLE_NAME_TYPES
private static final java.util.EnumSet<TimeZoneNames.NameType> ALL_SIMPLE_NAME_TYPES
-
ALL_GENERIC_NAME_TYPES
private static final java.util.EnumSet<TimeZoneGenericNames.GenericNameType> ALL_GENERIC_NAME_TYPES
-
ZONE_ID_TRIE
private static volatile TextTrieMap<java.lang.String> ZONE_ID_TRIE
-
SHORT_ZONE_ID_TRIE
private static volatile TextTrieMap<java.lang.String> SHORT_ZONE_ID_TRIE
-
serialPersistentFields
private static final java.io.ObjectStreamField[] serialPersistentFields
-
-
Constructor Detail
-
TimeZoneFormat
protected TimeZoneFormat(ULocale locale)
The protected constructor for subclassing.- Parameters:
locale
- the locale
-
-
Method Detail
-
getInstance
public static TimeZoneFormat getInstance(ULocale locale)
Returns a frozen instance ofTimeZoneFormat
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.
-
getInstance
public static TimeZoneFormat getInstance(java.util.Locale locale)
Returns a frozen instance ofTimeZoneFormat
for the givenLocale
.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
- theLocale
.- Returns:
- a frozen instance of
TimeZoneFormat
for the given locale.
-
getTimeZoneNames
public TimeZoneNames getTimeZoneNames()
Returns the time zone display name data used by this instance.- Returns:
- the time zone display name data.
- See Also:
setTimeZoneNames(TimeZoneNames)
-
getTimeZoneGenericNames
private TimeZoneGenericNames getTimeZoneGenericNames()
Private method returning the instance of TimeZoneGenericNames used by this object. The instance of TimeZoneGenericNames might not be available until the first use (lazy instantiation) because it is only required for handling generic names (that are not used by DateFormat's default patterns) and it requires relatively heavy one time initialization.- Returns:
- the instance of TimeZoneGenericNames used by this object.
-
getTZDBTimeZoneNames
private TimeZoneNames getTZDBTimeZoneNames()
Private method returning the instance of TZDBTimeZoneNames. The instance if used only for parsing whenTimeZoneFormat.ParseOption.TZ_DATABASE_ABBREVIATIONS
is enabled.- Returns:
- an instance of TZDBTimeZoneNames.
-
setTimeZoneNames
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:
java.lang.UnsupportedOperationException
- when this object is frozen.- See Also:
getTimeZoneNames()
-
getGMTPattern
public java.lang.String getGMTPattern()
Returns the localized GMT format pattern.- Returns:
- the localized GMT format pattern.
- See Also:
setGMTPattern(String)
-
setGMTPattern
public TimeZoneFormat setGMTPattern(java.lang.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:
java.lang.IllegalArgumentException
- when the pattern string does not contain "{0}"java.lang.UnsupportedOperationException
- when this object is frozen.- See Also:
getGMTPattern()
-
getGMTOffsetPattern
public java.lang.String getGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type)
Returns the offset pattern used for localized GMT format.- Parameters:
type
- the offset pattern enum- See Also:
setGMTOffsetPattern(GMTOffsetPatternType, String)
-
setGMTOffsetPattern
public TimeZoneFormat setGMTOffsetPattern(TimeZoneFormat.GMTOffsetPatternType type, java.lang.String pattern)
Sets the offset pattern for the given offset type.- Parameters:
type
- the offset pattern.pattern
- the pattern string.- Returns:
- this object.
- Throws:
java.lang.IllegalArgumentException
- when the pattern string does not have required time field letters.java.lang.UnsupportedOperationException
- when this object is frozen.- See Also:
getGMTOffsetPattern(GMTOffsetPatternType)
-
getGMTOffsetDigits
public java.lang.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.
- See Also:
setGMTOffsetDigits(String)
-
setGMTOffsetDigits
public TimeZoneFormat setGMTOffsetDigits(java.lang.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:
java.lang.IllegalArgumentException
- when the string did not contain ten characters.java.lang.UnsupportedOperationException
- when this object is frozen.- See Also:
getGMTOffsetDigits()
-
getGMTZeroFormat
public java.lang.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.
- See Also:
setGMTZeroFormat(String)
-
setGMTZeroFormat
public TimeZoneFormat setGMTZeroFormat(java.lang.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:
java.lang.UnsupportedOperationException
- when this object is frozen.- See Also:
getGMTZeroFormat()
-
setDefaultParseOptions
public TimeZoneFormat setDefaultParseOptions(java.util.EnumSet<TimeZoneFormat.ParseOption> options)
Sets the default parse options.Note: By default, an instance of
TimeZoneFormat
created bygetInstance(ULocale)
has no parse options set.- Parameters:
options
- the default parse options.- Returns:
- this object.
- See Also:
TimeZoneFormat.ParseOption
-
getDefaultParseOptions
public java.util.EnumSet<TimeZoneFormat.ParseOption> getDefaultParseOptions()
Returns the default parse options used by thisTimeZoneFormat
instance.- Returns:
- the default parse options.
- See Also:
TimeZoneFormat.ParseOption
-
formatOffsetISO8601Basic
public final java.lang.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:
java.lang.IllegalArgumentException
- if the specified offset is out of supported range (-24 hours < offset < +24 hours).- See Also:
formatOffsetISO8601Extended(int, boolean, boolean, boolean)
,parseOffsetISO8601(String, ParsePosition)
-
formatOffsetISO8601Extended
public final java.lang.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:
java.lang.IllegalArgumentException
- if the specified offset is out of supported range (-24 hours < offset < +24 hours).- See Also:
formatOffsetISO8601Basic(int, boolean, boolean, boolean)
,parseOffsetISO8601(String, ParsePosition)
-
formatOffsetLocalizedGMT
public java.lang.String formatOffsetLocalizedGMT(int offset)
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
- Throws:
java.lang.IllegalArgumentException
- if the specified offset is out of supported range (-24 hours < offset < +24 hours).- See Also:
parseOffsetLocalizedGMT(String, ParsePosition)
- GMT format pattern (e.g. "GMT {0}" - see
-
formatOffsetShortLocalizedGMT
public java.lang.String formatOffsetShortLocalizedGMT(int offset)
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(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 short localized GMT format string
- Throws:
java.lang.IllegalArgumentException
- if the specified offset is out of supported range (-24 hours < offset < +24 hours).- See Also:
parseOffsetLocalizedGMT(String, ParsePosition)
- GMT format pattern (e.g. "GMT {0}" - see
-
format
public final java.lang.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 forGENERIC_LONG
style, the implementation may useGENERIC_LOCATION
orLOCALIZED_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)
-
format
public java.lang.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 argumentOutput<TimeType> timeType
in addition to the argument list offormat(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)
-
parseOffsetISO8601
public final int parseOffsetISO8601(java.lang.String text, java.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 toParsePosition 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.
- See Also:
formatOffsetISO8601Basic(int, boolean, boolean, boolean)
,formatOffsetISO8601Extended(int, boolean, boolean, boolean)
-
parseOffsetLocalizedGMT
public int parseOffsetLocalizedGMT(java.lang.String text, java.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 toParsePosition 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)
-
parseOffsetShortLocalizedGMT
public int parseOffsetShortLocalizedGMT(java.lang.String text, java.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 toParsePosition 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.
- See Also:
formatOffsetShortLocalizedGMT(int)
-
parse
public TimeZone parse(TimeZoneFormat.Style style, java.lang.String text, java.text.ParsePosition pos, java.util.EnumSet<TimeZoneFormat.ParseOption> options, Output<TimeZoneFormat.TimeType> timeType)
Returns aTimeZone
by parsing the time zone string according to the parse position, the style and the parse options.- Parameters:
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.- Returns:
- A
TimeZone
, or null if the input could not be parsed. - See Also:
TimeZoneFormat.Style
,format(Style, TimeZone, long, Output)
-
parse
public TimeZone parse(TimeZoneFormat.Style style, java.lang.String text, java.text.ParsePosition pos, Output<TimeZoneFormat.TimeType> timeType)
Returns aTimeZone
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
- 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.- Returns:
- A
TimeZone
, or null if the input could not be parsed. - See Also:
TimeZoneFormat.Style
,parse(Style, String, ParsePosition, EnumSet, Output)
,format(Style, TimeZone, long, Output)
,setDefaultParseOptions(EnumSet)
-
parse
public final TimeZone parse(java.lang.String text, java.text.ParsePosition pos)
Returns aTimeZone
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. - See Also:
parse(Style, String, ParsePosition, EnumSet, Output)
-
parse
public final TimeZone parse(java.lang.String text) throws java.text.ParseException
Returns aTimeZone
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:
java.text.ParseException
- when the input could not be parsed as a time zone string.- See Also:
parse(String, ParsePosition)
-
format
public java.lang.StringBuffer format(java.lang.Object obj, java.lang.StringBuffer toAppendTo, java.text.FieldPosition pos)
- Specified by:
format
in classjava.text.Format
-
formatToCharacterIterator
public java.text.AttributedCharacterIterator formatToCharacterIterator(java.lang.Object obj)
- Overrides:
formatToCharacterIterator
in classjava.text.Format
-
parseObject
public java.lang.Object parseObject(java.lang.String source, java.text.ParsePosition pos)
- Specified by:
parseObject
in classjava.text.Format
-
formatOffsetLocalizedGMT
private java.lang.String formatOffsetLocalizedGMT(int offset, boolean isShort)
Private method used for localized GMT formatting.- Parameters:
offset
- the zone's UTC offsetisShort
- true if the short localized GMT format is desired- Returns:
- the localized GMT string
-
formatOffsetISO8601
private java.lang.String formatOffsetISO8601(int offset, boolean isBasic, boolean useUtcIndicator, boolean isShort, boolean ignoreSeconds)
-
formatSpecific
private java.lang.String formatSpecific(TimeZone tz, TimeZoneNames.NameType stdType, TimeZoneNames.NameType dstType, long date, Output<TimeZoneFormat.TimeType> timeType)
Private method returning the time zone's specific format string.- Parameters:
tz
- the time zonestdType
- the name type used for standard timedstType
- the name type used for daylight timedate
- the datetimeType
- when null, actual time type is set- Returns:
- the time zone's specific format name string
-
formatExemplarLocation
private java.lang.String formatExemplarLocation(TimeZone tz)
Private method returning the time zone's exemplar location string. This method will never return null.- Parameters:
tz
- the time zone- Returns:
- the time zone's exemplar location name.
-
getTimeZoneID
private java.lang.String getTimeZoneID(java.lang.String tzID, java.lang.String mzID)
Private method returns a time zone ID. If tzID is not null, the value of tzID is returned. If tzID is null, then this method look up a time zone ID for the current region. This is a small helper method used by the parse implementation method- Parameters:
tzID
- the time zone ID or nullmzID
- the meta zone ID or null- Returns:
- A time zone ID
- Throws:
java.lang.IllegalArgumentException
- when both tzID and mzID are null
-
getTargetRegion
private java.lang.String getTargetRegion()
Private method returning the target region. The target regions is determined by the locale of this instance. When a generic name is coming from a meta zone, this region is used for checking if the time zone is a reference zone of the meta zone.- Returns:
- the target region
-
getTimeType
private TimeZoneFormat.TimeType getTimeType(TimeZoneNames.NameType nameType)
Returns the time type for the given name type- Parameters:
nameType
- the name type- Returns:
- the time type (unknown/standard/daylight)
-
initGMTPattern
private void initGMTPattern(java.lang.String gmtPattern)
Parses the localized GMT pattern string and initialize localized gmt pattern fields including#_gmtPatternTokens
. This method must be also called at deserialization time.- Parameters:
gmtPattern
- the localized GMT pattern string such as "GMT {0}"- Throws:
java.lang.IllegalArgumentException
- when the pattern string does not contain "{0}"
-
unquote
private static java.lang.String unquote(java.lang.String s)
Unquotes the message format style pattern.- Parameters:
s
- the pattern- Returns:
- the unquoted pattern string
-
initGMTOffsetPatterns
private void initGMTOffsetPatterns(java.lang.String[] gmtOffsetPatterns)
Initialize localized GMT format offset hour/min/sec patterns. This method parses patterns into optimized run-time format. This method must be called at deserialization time.- Parameters:
gmtOffsetPatterns
- patterns, String[4]- Throws:
java.lang.IllegalArgumentException
- when patterns are not valid
-
checkAbuttingHoursAndMinutes
private void checkAbuttingHoursAndMinutes()
-
parseOffsetPattern
private static java.lang.Object[] parseOffsetPattern(java.lang.String pattern, java.lang.String letters)
Parse the GMT offset pattern into runtime optimized format- Parameters:
pattern
- the offset pattern stringletters
- the required pattern letters such as "Hm"- Returns:
- An array of Object. Each array entry is either String (representing pattern literal) or GMTOffsetField (hour/min/sec field)
-
expandOffsetPattern
private static java.lang.String expandOffsetPattern(java.lang.String offsetHM)
Appends seconds field to the offset pattern with hour/minute- Parameters:
offsetHM
- the offset pattern including hours and minutes fields- Returns:
- the offset pattern including hours, minutes and seconds fields
-
truncateOffsetPattern
private static java.lang.String truncateOffsetPattern(java.lang.String offsetHM)
Truncates minutes field from the offset pattern with hour/minute- Parameters:
offsetHM
- the offset pattern including hours and minutes fields- Returns:
- the offset pattern including only hours field
-
appendOffsetDigits
private void appendOffsetDigits(java.lang.StringBuilder buf, int n, int minDigits)
Appends localized digits to the buffer.Note: This code assumes that the input number is 0 - 59
- Parameters:
buf
- the target buffern
- the integer numberminDigits
- the minimum digits width
-
getTimeZoneForOffset
private TimeZone getTimeZoneForOffset(int offset)
Creates an instance of TimeZone for the given offset- Parameters:
offset
- the offset- Returns:
- A TimeZone with the given offset
-
parseOffsetLocalizedGMT
private int parseOffsetLocalizedGMT(java.lang.String text, java.text.ParsePosition pos, boolean isShort, Output<java.lang.Boolean> hasDigitOffset)
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 toParsePosition pos
and returns 0.- Parameters:
text
- the text contains a localized GMT offset string at the position.pos
- the position.isShort
- true if this parser to try the short format firsthasDigitOffset
- receiving if the parsed zone string contains offset digits.- Returns:
- the offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.
-
parseOffsetLocalizedGMTPattern
private int parseOffsetLocalizedGMTPattern(java.lang.String text, int start, boolean isShort, int[] parsedLen)
Parse localized GMT format generated by the pattern used by this formatter, except GMT Zero format.- Parameters:
text
- the input textstart
- the start indexisShort
- true if the short localized GMT format is parsed.parsedLen
- the parsed length, or 0 on failure.- Returns:
- the parsed offset in milliseconds.
-
parseOffsetFields
private int parseOffsetFields(java.lang.String text, int start, boolean isShort, int[] parsedLen)
Parses localized GMT offset fields into offset.- Parameters:
text
- the input textstart
- the start indexisShort
- true if this is a short format - currently not usedparsedLen
- the parsed length, or 0 on failure.- Returns:
- the parsed offset in milliseconds.
-
parseOffsetFieldsWithPattern
private int parseOffsetFieldsWithPattern(java.lang.String text, int start, java.lang.Object[] patternItems, boolean forceSingleHourDigit, int[] fields)
Parses localized GMT offset fields with the given pattern- Parameters:
text
- the input textstart
- the start indexpatternItems
- the pattern (already itemized)forceSingleHourDigit
- true if hours field is parsed as a single digitfields
- receives the parsed hours/minutes/seconds- Returns:
- parsed length
-
parseOffsetDefaultLocalizedGMT
private int parseOffsetDefaultLocalizedGMT(java.lang.String text, int start, int[] parsedLen)
Parses the input text using the default format patterns (e.g. "UTC{0}").- Parameters:
text
- the input textstart
- the start indexparsedLen
- the parsed length, or 0 on failure- Returns:
- the parsed offset in milliseconds.
-
parseDefaultOffsetFields
private int parseDefaultOffsetFields(java.lang.String text, int start, char separator, int[] parsedLen)
Parses the input GMT offset fields with the default offset pattern.- Parameters:
text
- the input textstart
- the start indexseparator
- the separator character, e.g. ':'parsedLen
- the parsed length, or 0 on failure.- Returns:
- the parsed offset in milliseconds.
-
parseAbuttingOffsetFields
private int parseAbuttingOffsetFields(java.lang.String text, int start, int[] parsedLen)
Parses abutting localized GMT offset fields (such as 0800) into offset.- Parameters:
text
- the input textstart
- the start indexparsedLen
- the parsed length, or 0 on failure- Returns:
- the parsed offset in milliseconds.
-
parseOffsetFieldWithLocalizedDigits
private int parseOffsetFieldWithLocalizedDigits(java.lang.String text, int start, int minDigits, int maxDigits, int minVal, int maxVal, int[] parsedLen)
Reads an offset field value. This method will stop parsing when 1) number of digits reachesmaxDigits
2) just before already parsed number exceedsmaxVal
- Parameters:
text
- the textstart
- the start offsetminDigits
- the minimum number of required digitsmaxDigits
- the maximum number of digitsminVal
- the minimum valuemaxVal
- the maximum valueparsedLen
- the actual parsed length is set to parsedLen[0], must not be null.- Returns:
- the integer value parsed
-
parseSingleLocalizedDigit
private int parseSingleLocalizedDigit(java.lang.String text, int start, int[] len)
Reads a single decimal digit, either localized digits used by this object or any Unicode numeric character.- Parameters:
text
- the textstart
- the start indexlen
- the actual length read from the text the start index is not a decimal number.- Returns:
- the integer value of the parsed digit, or -1 on failure.
-
toCodePoints
private static java.lang.String[] toCodePoints(java.lang.String str)
Break input String into String[]. Each array element represents a code point. This method is used for parsing localized digit characters and support characters in Unicode supplemental planes.- Parameters:
str
- the string- Returns:
- the array of code points in String[]
-
parseOffsetISO8601
private static int parseOffsetISO8601(java.lang.String text, java.text.ParsePosition pos, boolean extendedOnly, Output<java.lang.Boolean> hasDigitOffset)
Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 time zone string (basic format, extended format, or UTC indicator). When the given string is not an ISO 8601 time zone string, this method sets the current position as the error index toParsePosition pos
and returns 0.- Parameters:
text
- the text contains ISO 8601 style time zone string (e.g. "-08", "-08:00", "Z") at the position.pos
- the position.extendedOnly
-true
if parsing the text as ISO 8601 extended offset format (e.g. "-08:00"), orfalse
to evaluate the text as basic format.hasDigitOffset
- receiving if the parsed zone string contains offset digits.- Returns:
- the offset from GMT(UTC) in milliseconds for the given ISO 8601 style time zone string.
-
parseAbuttingAsciiOffsetFields
private static int parseAbuttingAsciiOffsetFields(java.lang.String text, java.text.ParsePosition pos, TimeZoneFormat.OffsetFields minFields, TimeZoneFormat.OffsetFields maxFields, boolean fixedHourWidth)
Parses offset represented by contiguous ASCII digitsNote: This method expects the input position is already at the start of ASCII digits and does not parse sign (+/-).
- Parameters:
text
- The text contains a sequence of ASCII digitspos
- The parse positionminFields
- The minimum Fields to be parsedmaxFields
- The maximum Fields to be parsedfixedHourWidth
- true if hours field must be width of 2- Returns:
- Parsed offset, 0 or positive number.
-
parseAsciiOffsetFields
private static int parseAsciiOffsetFields(java.lang.String text, java.text.ParsePosition pos, char sep, TimeZoneFormat.OffsetFields minFields, TimeZoneFormat.OffsetFields maxFields)
Parses offset represented by ASCII digits and separators.Note: This method expects the input position is already at the start of ASCII digits and does not parse sign (+/-).
- Parameters:
text
- The textpos
- The parse positionsep
- The separator characterminFields
- The minimum Fields to be parsedmaxFields
- The maximum Fields to be parsed- Returns:
- Parsed offset, 0 or positive number.
-
parseZoneID
private static java.lang.String parseZoneID(java.lang.String text, java.text.ParsePosition pos)
Parse a zone ID.- Parameters:
text
- the text contains a time zone ID string at the position.pos
- the position.- Returns:
- The zone ID parsed.
-
parseShortZoneID
private static java.lang.String parseShortZoneID(java.lang.String text, java.text.ParsePosition pos)
Parse a short zone ID.- Parameters:
text
- the text contains a time zone ID string at the position.pos
- the position.- Returns:
- The zone ID for the parsed short zone ID.
-
parseExemplarLocation
private java.lang.String parseExemplarLocation(java.lang.String text, java.text.ParsePosition pos)
Parse an exemplar location string.- Parameters:
text
- the text contains an exemplar location string at the position.pos
- the position.- Returns:
- The zone ID for the parsed exemplar location.
-
writeObject
private void writeObject(java.io.ObjectOutputStream oos) throws java.io.IOException
- Parameters:
oos
- the object output stream- Throws:
java.io.IOException
-
readObject
private void readObject(java.io.ObjectInputStream ois) throws java.lang.ClassNotFoundException, java.io.IOException
- Parameters:
ois
- the object input stream- Throws:
java.lang.ClassNotFoundException
java.io.IOException
-
isFrozen
public boolean isFrozen()
Determines whether the object has been frozen or not.- Specified by:
isFrozen
in interfaceFreezable<TimeZoneFormat>
-
freeze
public TimeZoneFormat freeze()
Freezes the object.- Specified by:
freeze
in interfaceFreezable<TimeZoneFormat>
- Returns:
- the object itself.
-
cloneAsThawed
public TimeZoneFormat cloneAsThawed()
Provides for the clone operation. Any clone is initially unfrozen.- Specified by:
cloneAsThawed
in interfaceFreezable<TimeZoneFormat>
-
-