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

        Note: The instance returned by this method is frozen. If you want to customize a TimeZoneFormat, you must use cloneAsThawed() to get a thawed copy first.

        Parameters:
        locale - the JDK locale.
        Returns:
        a frozen instance of TimeZoneFormat for the given locale.
      • getGMTPattern

        public String getGMTPattern()
        Returns the localized GMT format pattern.
        Returns:
        the localized GMT format pattern.
        See Also:
        setGMTPattern(String)
      • getGMTOffsetDigits

        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.
        See Also:
        setGMTOffsetDigits(String)
      • getGMTZeroFormat

        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.
        See Also:
        setGMTZeroFormat(String)
      • setGMTZeroFormat

        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.
        See Also:
        getGMTZeroFormat()
      • formatOffsetISO8601Basic

        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).
        See Also:
        formatOffsetISO8601Extended(int, boolean, boolean, boolean), parseOffsetISO8601(String, ParsePosition)
      • formatOffsetISO8601Extended

        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).
        See Also:
        formatOffsetISO8601Basic(int, boolean, boolean, boolean), parseOffsetISO8601(String, ParsePosition)
      • formatOffsetLocalizedGMT

        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).
        See Also:
        parseOffsetLocalizedGMT(String, ParsePosition)
      • formatOffsetShortLocalizedGMT

        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).
        See Also:
        parseOffsetLocalizedGMT(String, ParsePosition)
      • format

        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.
        See Also:
        TimeZoneFormat.Style, format(Style, TimeZone, long, Output)
      • format

        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.
        See Also:
        TimeZoneFormat.Style, format(Style, TimeZone, long)
      • parseOffsetISO8601

        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.
        See Also:
        formatOffsetISO8601Basic(int, boolean, boolean, boolean), formatOffsetISO8601Extended(int, boolean, boolean, boolean)
      • parseOffsetLocalizedGMT

        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.
        See Also:
        formatOffsetLocalizedGMT(int)
      • parseOffsetShortLocalizedGMT

        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.
        See Also:
        formatOffsetShortLocalizedGMT(int)
      • format

        public StringBuffer format​(Object obj,
                                   StringBuffer toAppendTo,
                                   FieldPosition pos)
        Appends the specified object to the specified string buffer using the rules of this format.

        field is an input/output parameter. If its field member contains an enum value specifying a field on input, then its beginIndex and endIndex members will be updated with the text offset of the first occurrence of this field in the formatted text.

        Specified by:
        format in class Format
        Parameters:
        obj - the object to format.
        toAppendTo - the string buffer where the formatted string is appended to.
        pos - on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text.
        Returns:
        the string buffer.
      • formatToCharacterIterator

        public AttributedCharacterIterator formatToCharacterIterator​(Object obj)
        Formats the specified object using the rules of this format and returns an AttributedCharacterIterator with the formatted string and no attributes.

        Subclasses should return an AttributedCharacterIterator with the appropriate attributes.

        Overrides:
        formatToCharacterIterator in class Format
        Parameters:
        obj - the object to format.
        Returns:
        an AttributedCharacterIterator with the formatted object and attributes.
      • parseObject

        public Object parseObject​(String source,
                                  ParsePosition pos)
        Parses the specified string starting at the index specified by position. If the string is successfully parsed then the index of the ParsePosition is updated to the index following the parsed text. On error, the index is unchanged and the error index of ParsePosition is set to the index where the error occurred.
        Specified by:
        parseObject in class Format
        Parameters:
        source - the string to parse.
        pos - input/output parameter, specifies the start index in string from where to start parsing. If parsing is successful, it is updated with the index following the parsed text; on error, the index is unchanged and the error index is set to the index where the error occurred.
        Returns:
        the object resulting from the parse or null if there is an error.
      • isFrozen

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