Class TimeZoneFormat

    • 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 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.
      • getInstance

        public static TimeZoneFormat getInstance​(java.util.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.
      • 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()
      • 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()
      • 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; 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:
        java.lang.IllegalArgumentException - if the specified offset is out of supported range (-24 hours < offset < +24 hours).
        See Also:
        parseOffsetLocalizedGMT(String, ParsePosition)
      • 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; 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:
        java.lang.IllegalArgumentException - if the specified offset is out of supported range (-24 hours < offset < +24 hours).
        See Also:
        parseOffsetLocalizedGMT(String, ParsePosition)
      • 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 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)
      • 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 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)
      • 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 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.
        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 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)
      • 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 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.
        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 a TimeZone 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 final TimeZone parse​(java.lang.String text)
                             throws java.text.ParseException
        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:
        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 class java.text.Format
      • formatToCharacterIterator

        public java.text.AttributedCharacterIterator formatToCharacterIterator​(java.lang.Object obj)
        Overrides:
        formatToCharacterIterator in class java.text.Format
      • parseObject

        public java.lang.Object parseObject​(java.lang.String source,
                                            java.text.ParsePosition pos)
        Specified by:
        parseObject in class java.text.Format
      • isFrozen

        public boolean isFrozen()
        Determines whether the object has been frozen or not.
        Specified by:
        isFrozen in interface Freezable<TimeZoneFormat>