Class ZoneOffset

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<ZoneOffset>, Calendrical

    public final class ZoneOffset
    extends java.lang.Object
    implements Calendrical, java.lang.Comparable<ZoneOffset>, java.io.Serializable
    A time-zone offset from UTC, such as +02:00.

    A time-zone offset is the period of time that a time-zone differs from UTC. This is usually a fixed number of hours and minutes.

    Different parts of the world have different time-zone offsets. The rules for how offsets vary by place and time of year are captured in the TimeZone class.

    For example, Paris is one hours ahead of UTC in winter and two hours ahead in summer. The TimeZone instance for Paris will reference two ZoneOffset instances - a +01:00 instance for winter, and a +02:00 instance for summer.

    In 2008, time-zone offsets around the world extended from -12:00 to +14:00. To prevent any problems with that range being extended, yet still provide validation, the range of offsets is restricted to -18:00 to 18:00 inclusive.

    This class is designed primarily for use with the ISOChronology. The fields of hours, minutes and seconds make assumptions that are valid for the standard ISO definitions of those fields. This class may be used with other calendar systems providing the definition of the time fields matches those of the ISO calendar system.

    Instances of ZoneOffset must be compared using equals(java.lang.Object). Implementations may choose to cache certain common offsets, however applications must not rely on such caching.

    ZoneOffset is immutable and thread-safe.

    See Also:
    Serialized Form
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      (package private) static class  ZoneOffset.Rule
      Rule implementation.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private int amountSeconds
      The offset in seconds.
      private static java.util.concurrent.locks.ReadWriteLock CACHE_LOCK
      Cache of time-zone offset by offset in seconds.
      private java.lang.String id
      The string form of the time-zone offset.
      private static java.util.Map<java.lang.String,​ZoneOffset> ID_CACHE
      Cache of time-zone offset by id.
      private static int MINUTES_PER_HOUR
      The number of minutes per hour.
      private static java.util.Map<java.lang.Integer,​ZoneOffset> SECONDS_CACHE
      Cache of time-zone offset by offset in seconds.
      private static int SECONDS_PER_HOUR
      The number of seconds per hour.
      private static int SECONDS_PER_MINUTE
      The number of seconds per minute.
      private static long serialVersionUID
      A serialization identifier for this class.
      static ZoneOffset UTC
      The time-zone offset for UTC, with an id of 'Z'.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private ZoneOffset​(int totalSeconds)
      Constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(ZoneOffset other)
      Compares this offset to another offset in descending order.
      boolean equals​(java.lang.Object other)
      Checks if this instance is equal to the specified offset, comparing the amount of the offset in seconds.
      <T> T get​(CalendricalRule<T> rule)
      Gets the value of the specified calendrical rule.
      int getAmountSeconds()
      Gets the total zone offset in seconds.
      int getHoursField()
      Gets the hours field of the zone offset.
      java.lang.String getID()
      Gets the normalized zone offset id.
      int getMinutesField()
      Gets the minutes field of the zone offset.
      int getSecondsField()
      Gets the seconds field of the zone offset.
      int hashCode()
      A hash code for the zone offset.
      static ZoneOffset of​(java.lang.String offsetID)
      Obtains an instance of ZoneOffset using the id.
      static ZoneOffset of​(PeriodProvider periodProvider)
      Obtains an instance of ZoneOffset from a period.
      static ZoneOffset ofHours​(int hours)
      Obtains an instance of ZoneOffset using an offset in hours.
      static ZoneOffset ofHoursMinutes​(int hours, int minutes)
      Obtains an instance of ZoneOffset using an offset in hours and minutes.
      static ZoneOffset ofHoursMinutesSeconds​(int hours, int minutes, int seconds)
      Obtains an instance of ZoneOffset using an offset in hours, minutes and seconds.
      static ZoneOffset ofTotalSeconds​(int totalSeconds)
      Obtains an instance of ZoneOffset specifying the total offset in seconds
      private static int parseNumber​(java.lang.String offsetID, int pos, boolean precededByColon)
      Parse a two digit zero-prefixed number.
      ZoneOffset plus​(PeriodProvider periodProvider)
      Returns a copy of this offset with the specified period added.
      private java.lang.Object readResolve()
      Resolves singletons.
      static CalendricalRule<ZoneOffset> rule()
      Gets the rule for the zone-offset.
      Period toPeriod()
      Converts this offset to a period.
      java.lang.String toString()
      Returns a string representation of the zone offset, which is the same as the normalized id.
      private static int totalSeconds​(int hours, int minutes, int seconds)
      Calculates the total offset in seconds.
      TimeZone toTimeZone()
      Converts this offset to a time-zone.
      private static void validate​(int hours, int minutes, int seconds)
      Validates the offset fields.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • CACHE_LOCK

        private static final java.util.concurrent.locks.ReadWriteLock CACHE_LOCK
        Cache of time-zone offset by offset in seconds.
      • SECONDS_CACHE

        private static final java.util.Map<java.lang.Integer,​ZoneOffset> SECONDS_CACHE
        Cache of time-zone offset by offset in seconds.
      • ID_CACHE

        private static final java.util.Map<java.lang.String,​ZoneOffset> ID_CACHE
        Cache of time-zone offset by id.
      • UTC

        public static final ZoneOffset UTC
        The time-zone offset for UTC, with an id of 'Z'.
      • SECONDS_PER_HOUR

        private static final int SECONDS_PER_HOUR
        The number of seconds per hour.
        See Also:
        Constant Field Values
      • SECONDS_PER_MINUTE

        private static final int SECONDS_PER_MINUTE
        The number of seconds per minute.
        See Also:
        Constant Field Values
      • MINUTES_PER_HOUR

        private static final int MINUTES_PER_HOUR
        The number of minutes per hour.
        See Also:
        Constant Field Values
      • serialVersionUID

        private static final long serialVersionUID
        A serialization identifier for this class.
        See Also:
        Constant Field Values
      • amountSeconds

        private final int amountSeconds
        The offset in seconds.
      • id

        private final transient java.lang.String id
        The string form of the time-zone offset.
    • Constructor Detail

      • ZoneOffset

        private ZoneOffset​(int totalSeconds)
        Constructor.
        Parameters:
        totalSeconds - the total time-zone offset in seconds, from -64800 to +64800
    • Method Detail

      • of

        public static ZoneOffset of​(java.lang.String offsetID)
        Obtains an instance of ZoneOffset using the id.

        This method parses the string id of a ZoneOffset to return an instance. The parsing accepts all the formats generated by getID(), plus some additional formats:

        • Z - for UTC
        • +hh:mm
        • -hh:mm
        • +hhmm
        • -hhmm
        • +hh:mm:ss
        • -hh:mm:ss
        • +hhmmss
        • -hhmmss
        Note that ± means either the plus or minus symbol.

        The ID of the returned offset will be normalized to one of the formats described by getID().

        The maximum supported range is from +18:00 to -18:00 inclusive.

        Parameters:
        offsetID - the offset id, not null
        Returns:
        the ZoneOffset, never null
        Throws:
        java.lang.IllegalArgumentException - if the offset id is invalid
      • parseNumber

        private static int parseNumber​(java.lang.String offsetID,
                                       int pos,
                                       boolean precededByColon)
        Parse a two digit zero-prefixed number.
        Parameters:
        offsetID - the offset id, not null
        pos - the position to parse, valid
        precededByColon - should this number be prefixed by a precededByColon
        Returns:
        the parsed number, from 0 to 99
      • ofHours

        public static ZoneOffset ofHours​(int hours)
        Obtains an instance of ZoneOffset using an offset in hours.
        Parameters:
        hours - the time-zone offset in hours, from -18 to +18
        Returns:
        the ZoneOffset, never null
        Throws:
        java.lang.IllegalArgumentException - if the offset is not in the required range
      • ofHoursMinutes

        public static ZoneOffset ofHoursMinutes​(int hours,
                                                int minutes)
        Obtains an instance of ZoneOffset using an offset in hours and minutes.

        The sign of the hours and minutes components must match. Thus, if the hours is negative, the minutes must be negative or zero. If the hours is zero, the minutes may be positive, negative or zero.

        Parameters:
        hours - the time-zone offset in hours, from -18 to +18
        minutes - the time-zone offset in minutes, from 0 to ±59, sign matches hours
        Returns:
        the ZoneOffset, never null
        Throws:
        java.lang.IllegalArgumentException - if the offset is not in the required range
      • ofHoursMinutesSeconds

        public static ZoneOffset ofHoursMinutesSeconds​(int hours,
                                                       int minutes,
                                                       int seconds)
        Obtains an instance of ZoneOffset using an offset in hours, minutes and seconds.

        The sign of the hours, minutes and seconds components must match. Thus, if the hours is negative, the minutes and seconds must be negative or zero.

        Parameters:
        hours - the time-zone offset in hours, from -18 to +18
        minutes - the time-zone offset in minutes, from 0 to ±59, sign matches hours and seconds
        seconds - the time-zone offset in seconds, from 0 to ±59, sign matches hours and minutes
        Returns:
        the ZoneOffset, never null
        Throws:
        java.lang.IllegalArgumentException - if the offset is not in the required range
      • of

        public static ZoneOffset of​(PeriodProvider periodProvider)
        Obtains an instance of ZoneOffset from a period.

        This creates an offset from the specified period, converting using Period.of(PeriodProvider). Only the hour, minute and second fields from the period are used - other fields are ignored. The sign of the hours, minutes and seconds components must match. Thus, if the hours is negative, the minutes and seconds must be negative or zero.

        Parameters:
        periodProvider - the period to use, not null
        Returns:
        the ZoneOffset, never null
        Throws:
        CalendricalException - if the specified period cannot be converted to a Period
        java.lang.IllegalArgumentException - if the offset is not in the required range
      • validate

        private static void validate​(int hours,
                                     int minutes,
                                     int seconds)
        Validates the offset fields.
        Parameters:
        hours - the time-zone offset in hours, from -18 to +18
        minutes - the time-zone offset in minutes, from 0 to ±59
        seconds - the time-zone offset in seconds, from 0 to ±59
        Throws:
        java.lang.IllegalArgumentException - if the offset is not in the required range
      • totalSeconds

        private static int totalSeconds​(int hours,
                                        int minutes,
                                        int seconds)
        Calculates the total offset in seconds.
        Parameters:
        hours - the time-zone offset in hours, from -18 to +18
        minutes - the time-zone offset in minutes, from 0 to ±59, sign matches hours and seconds
        seconds - the time-zone offset in seconds, from 0 to ±59, sign matches hours and minutes
        Returns:
        the total in seconds
      • ofTotalSeconds

        public static ZoneOffset ofTotalSeconds​(int totalSeconds)
        Obtains an instance of ZoneOffset specifying the total offset in seconds

        The offset must be in the range -18:00 to +18:00, which corresponds to -64800 to +64800.

        Parameters:
        totalSeconds - the total time-zone offset in seconds, from -64800 to +64800
        Returns:
        the ZoneOffset, never null
        Throws:
        java.lang.IllegalArgumentException - if the offset is not in the required range
      • readResolve

        private java.lang.Object readResolve()
        Resolves singletons.
        Returns:
        the singleton instance
      • getAmountSeconds

        public int getAmountSeconds()
        Gets the total zone offset in seconds.

        This is the primary way to access the offset amount. It returns the total of the hours, minutes and seconds fields as a single offset that can be added to a time.

        Returns:
        the total zone offset amount in seconds
      • getID

        public java.lang.String getID()
        Gets the normalized zone offset id.

        The id is minor variation to the standard ISO-8601 formatted string for the offset. There are three formats:

        • Z - for UTC (ISO-8601)
        • +hh:mm or -hh:mm - if the seconds are zero (ISO-8601)
        • +hh:mm:ss or -hh:mm:ss - if the seconds are non-zero (not ISO-8601)
        Returns:
        the zone offset ID, never null
      • getHoursField

        public int getHoursField()
        Gets the hours field of the zone offset.

        This method only has meaning when considered with the minutes and seconds fields. Most applications are advised to use toPeriod() or getAmountSeconds().

        The zone offset is divided into three fields - hours, minutes and seconds. This method returns the value of the hours field. The sign of the value returned by this method will match that of the minutes and seconds fields.

        Returns:
        the hours field of the zone offset amount, from -18 to 18
      • getMinutesField

        public int getMinutesField()
        Gets the minutes field of the zone offset.

        This method only has meaning when considered with the hours and minutes fields. Most applications are advised to use toPeriod() or getAmountSeconds().

        The zone offset is divided into three fields - hours, minutes and seconds. This method returns the value of the minutes field. The sign of the value returned by this method will match that of the hours and seconds fields.

        Returns:
        the minutes field of the zone offset amount, from -59 to 59 where the sign matches the hours and seconds
      • getSecondsField

        public int getSecondsField()
        Gets the seconds field of the zone offset.

        This method only has meaning when considered with the hours and minutes fields. Most applications are advised to use toPeriod() or getAmountSeconds().

        The zone offset is divided into three fields - hours, minutes and seconds. This method returns the value of the seconds field. The sign of the value returned by this method will match that of the hours and minutes fields.

        Returns:
        the seconds field of the zone offset amount, from -59 to 59 where the sign matches the hours and minutes
      • plus

        public ZoneOffset plus​(PeriodProvider periodProvider)
        Returns a copy of this offset with the specified period added.

        This adds the amount in hours, minutes and seconds from the specified period to this offset. This converts the period using Period.of(PeriodProvider). Only the hour, minute and second fields from the period are used - other fields are ignored.

        This instance is immutable and unaffected by this method call.

        Parameters:
        periodProvider - the period to add, not null
        Returns:
        a ZoneOffset based on this offset with the period added, never null
        Throws:
        CalendricalException - if the specified period cannot be converted to a Period
        java.lang.IllegalArgumentException - if the offset is not in the required range
      • toPeriod

        public Period toPeriod()
        Converts this offset to a period.

        The period returned will have fields for hour, minute and second. For negative offsets, the values in the period will all be negative.

        For example, +02:45 will be converted to P2H45M, while -01:15 will be converted to P-1H-15M.

        Returns:
        the period equivalent to the zone offset amount, never null
      • toTimeZone

        public TimeZone toTimeZone()
        Converts this offset to a time-zone.

        The returned time-zone will use this offset for all instants.

        Returns:
        the time-zone, never null
      • compareTo

        public int compareTo​(ZoneOffset other)
        Compares this offset to another offset in descending order.

        The offsets are compared in the order that they occur for the same time of day around the world. Thus, an offset of +10:00 comes before an offset of +09:00 and so on down to -18:00.

        Specified by:
        compareTo in interface java.lang.Comparable<ZoneOffset>
        Parameters:
        other - the other date to compare to, not null
        Returns:
        the comparator value, negative if less, postive if greater
        Throws:
        java.lang.NullPointerException - if other is null
      • equals

        public boolean equals​(java.lang.Object other)
        Checks if this instance is equal to the specified offset, comparing the amount of the offset in seconds.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        other - the other zone offset, null returns false
        Returns:
        true if this offset is the same as that specified
      • hashCode

        public int hashCode()
        A hash code for the zone offset.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a suitable hash code
      • toString

        public java.lang.String toString()
        Returns a string representation of the zone offset, which is the same as the normalized id.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the id
      • get

        public <T> T get​(CalendricalRule<T> rule)
        Gets the value of the specified calendrical rule.

        This method queries the value of the specified calendrical rule. If the value cannot be returned for the rule from this offset then null will be returned.

        Specified by:
        get in interface Calendrical
        Parameters:
        rule - the rule to use, not null
        Returns:
        the value for the rule, null if the value cannot be returned
      • rule

        public static CalendricalRule<ZoneOffset> rule()
        Gets the rule for the zone-offset.
        Returns:
        the rule for the zone-offset, never null