Package net.time4j.tz

Class ZonalOffset

java.lang.Object
net.time4j.tz.ZonalOffset
All Implemented Interfaces:
Serializable, Comparable<ZonalOffset>, TZID
public final class ZonalOffset extends Object implements Comparable<ZonalOffset>, TZID, Serializable

Represents the shift of a local timestamp relative to UTC timezone usually in full seconds.

Following rule is the guideline (all data in seconds):

[Total Offset] = [Local Wall Time] - [POSIX Time]

Author:
Meno Hochschild
See Also:
Serialized Form

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static ZonalOffset
    UTC
    Constant for the UTC timezone representing a shift of 0 seconds with the canonical representation "Z".

  • Method Summary

    Modifier and Type
    Method
    Description
    static ZonalOffset
    atLongitude​(BigDecimal longitude)
    Creates a new shift based on a geographical longitude.
    static ZonalOffset
    atLongitude​(OffsetSign sign, int degrees, int arcMinutes, double arcSeconds)
    Creates a new shift based on a geographical longitude.
    String
    canonical()
    Returns a long canonical representation of this shift.
    int
    compareTo​(ZonalOffset obj)
    Compares the whole state with sign, hours, minutes, seconds and fractional seconds in ascending order.
    boolean
    equals​(Object obj)
    Compares the whole state.
    int
    getAbsoluteHours()
    Returns the hour part of this shift as absolute amount.
    int
    getAbsoluteMinutes()
    Returns the minute part of this shift as absolute amount.
    int
    getAbsoluteSeconds()
    Returns the second part of this shift as absolute amount.
    int
    getFractionalAmount()
    Returns the fractional second part of this shift in nanoseconds.
    int
    getIntegralAmount()
    Total shift in integer seconds without fractional part.
    OffsetSign
    getSign()
    Return the sign of this zonal shift.
    String
    getStdFormatPattern​(Locale locale)
    Obtains a typical localized format pattern in minute precision.
    int
    hashCode()
    Calculates the hash value.
    static ZonalOffset
    ofHours​(OffsetSign sign, int hours)
    Static factory method for a shift which has the given full hour part.
    static ZonalOffset
    ofHoursMinutes​(OffsetSign sign, int hours, int minutes)
    Static factory method for a shift which has given hour and minute parts.
    static ZonalOffset
    ofTotalSeconds​(int total)
    Creates a shift of the local time relative to UTC timezone in integer seconds.
    static ZonalOffset
    ofTotalSeconds​(int total, int fraction)
    Creates a shift of the local time relative to UTC timezone in integer seconds or fractional seconds.
    static ZonalOffset
    parse​(String canonical)
    Interpretes a canonical representation as zonal offset.
    String
    toString()
    Returns a complete short representation of this shift including the sign.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • UTC

      public static final ZonalOffset UTC

      Constant for the UTC timezone representing a shift of 0 seconds with the canonical representation "Z".

  • Method Details

    • atLongitude

      public static ZonalOffset atLongitude​(BigDecimal longitude)

      Creates a new shift based on a geographical longitude.

      Note that fractional offsets are not used in context of timezones, but can only be applied to conversions between PlainTimestamp and Moment.

      Parameters:
      longitude - geographical longitude in degrees defined in range -180.0 <= longitude <= 180.0
      Returns:
      zonal offset in decimal precision
      Throws:
      IllegalArgumentException - if range check fails

    • atLongitude

      public static ZonalOffset atLongitude​(OffsetSign sign, int degrees, int arcMinutes, double arcSeconds)

      Creates a new shift based on a geographical longitude.

      Note that fractional offsets are not used in context of timezones, but can only be applied to conversions between PlainTimestamp and Moment.

      Parameters:
      sign - sign of shift relative to zero meridian
      degrees - geographical length in degrees, defined in range 0 <= degrees <= 180
      arcMinutes - arc minute part (0 <= arcMinutes <= 59)
      arcSeconds - arc second part (0.0 <= arcSeconds < 60.0)
      Returns:
      zonal offset in decimal precision
      Throws:
      IllegalArgumentException - if range check fails (also if total absolute offset goes beyond 180 degrees)
      Since:
      4.26/3.30
      See Also:
      atLongitude(BigDecimal)

    • ofHours

      public static ZonalOffset ofHours​(OffsetSign sign, int hours)

      Static factory method for a shift which has the given full hour part.

      Is equivalent to ofHoursMinutes(sign, hours, 0).

      Parameters:
      sign - sign of shift relative to zero meridian
      hours - hour part (0 <= hours <= 18)
      Returns:
      zonal offset in hour precision
      Throws:
      IllegalArgumentException - if range check fails
      See Also:
      ofHoursMinutes(OffsetSign, int, int)

    • ofHoursMinutes

      public static ZonalOffset ofHoursMinutes​(OffsetSign sign, int hours, int minutes)

      Static factory method for a shift which has given hour and minute parts.

      The given numerical values are identical to the numerical parts of the canonical representation ±hh:mm". The second part is always 0. Only values in the range -18:00 <= [total-offset] <= +18:00 are allowed. When calculating the total offset the sign relates to both hour and minute part. Example: The expression ZonalOffset.ofHoursMinutes(BEHIND_UTC, 4, 30) has the representation -04:30 and a total shift in seconds of -(4 * 3600 + 30 * 60) = 16200.

      Parameters:
      sign - sign ofHoursMinutes shift relative to zero meridian
      hours - hour part (0 <= hours <= 18)
      minutes - minute part (0 <= minutes <= 59)
      Returns:
      zonal offset in minute precision
      Throws:
      IllegalArgumentException - if range check fails

    • ofTotalSeconds

      public static ZonalOffset ofTotalSeconds​(int total)

      Creates a shift of the local time relative to UTC timezone in integer seconds.

      Parameters:
      total - total shift in seconds defined in range -18 * 3600 <= total <= 18 * 3600
      Returns:
      zonal offset in second precision
      Throws:
      IllegalArgumentException - if range check fails
      See Also:
      getIntegralAmount()

    • ofTotalSeconds

      public static ZonalOffset ofTotalSeconds​(int total, int fraction)

      Creates a shift of the local time relative to UTC timezone in integer seconds or fractional seconds.

      Note that fractional offsets are not used in context of timezones, but can only be applied to conversions between PlainTimestamp and Moment.

      Parameters:
      total - total shift in seconds defined in range -18 * 3600 <= total <= 18 * 3600
      fraction - fraction of second
      Returns:
      zonal offset in (sub-)second precision
      Throws:
      IllegalArgumentException - if any arguments are out of range or have different signs
      See Also:
      getIntegralAmount(), getFractionalAmount()

    • getSign

      public OffsetSign getSign()

      Return the sign of this zonal shift.

      Returns:
      BEHIND_UTC if sign is negative else AHEAD_OF_UTC

    • getAbsoluteHours

      public int getAbsoluteHours()

      Returns the hour part of this shift as absolute amount.

      Returns:
      absolute hour part in range 0 <= x <= 18
      See Also:
      getSign()

    • getAbsoluteMinutes

      public int getAbsoluteMinutes()

      Returns the minute part of this shift as absolute amount.

      Returns:
      absolute minute part in range 0 <= x <= 59
      See Also:
      getSign()

    • getAbsoluteSeconds

      public int getAbsoluteSeconds()

      Returns the second part of this shift as absolute amount.

      Returns:
      absolute second part in range 0 <= x <= 59
      See Also:
      getSign()

    • getIntegralAmount

      public int getIntegralAmount()

      Total shift in integer seconds without fractional part.

      Returns:
      integral part in seconds -18 * 3600 <= x <= 18 * 3600
      See Also:
      getFractionalAmount()

    • getFractionalAmount

      public int getFractionalAmount()

      Returns the fractional second part of this shift in nanoseconds.

      Only longitudinal offsets may have fractional parts.

      Returns:
      fractional part in range -999999999 <= x <= 999999999
      See Also:
      getIntegralAmount()

    • compareTo

      public int compareTo​(ZonalOffset obj)

      Compares the whole state with sign, hours, minutes, seconds and fractional seconds in ascending order.

      Shifts with sign west for Greenwich (behind UTC) are considered as smaller than shifts with sign east for Greenwich (ahead of UTC).

      The natural order is consistent with equals().

      Specified by:
      compareTo in interface Comparable<ZonalOffset>

    • equals

      public boolean equals​(Object obj)

      Compares the whole state.

      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()

      Calculates the hash value.

      Overrides:
      hashCode in class Object

    • toString

      public String toString()

      Returns a complete short representation of this shift including the sign.

      Notes: If there are only full minutes or hours the representation is exactly as described in ISO-8601. Another long canonical representation can be obtained by the method canonical().

      Overrides:
      toString in class Object
      Returns:
      String in ISO-8601 format "±hh:mm" or "±hh:mm:ss" if there is a second part or "±hh:mm:ss.fffffffff" if any fractional part exists

    • canonical

      public String canonical()

      Returns a long canonical representation of this shift.

      Notes: If this instance denotes the UTC timezone then this method will yield the string "Z". Another short canonical representation can be obtained by the method toString().

      Specified by:
      canonical in interface TZID
      Returns:
      String in format "UTC±hh:mm" or "UTC±hh:mm:ss" if there is a second part or "UTC±hh:mm:ss.fffffffff" if any fractional part exists or "Z" in timezone UTC
      See Also:
      toString()

    • parse

      public static ZonalOffset parse​(String canonical)

      Interpretes a canonical representation as zonal offset.

      All string produced by the methods canonical() or toString() are supported. Due to the technical nature of canonical representations this method is not designed to parse any kind of user-defined input, especially the use of GMT-prefix is NOT canonical and outdated from a scientific point of view.

      Examples for supported formats:

      • UTC+5
      • UTC+05
      • UTC+5:30
      • UTC+05:30
      • UTC+5:30:21
      • UTC+05:30:21
      • UTC+5:30:21.123456789
      • UTC+05:30:21.123456789
      • +5
      • +05
      • +5:30
      • +05:30
      • +5:30:21
      • +05:30:21
      • +5:30:21.123456789
      • +05:30:21.123456789

      Note: All formats containing only the hour or the hour with only one digit are first supported in version 3.1 or later.

      Parameters:
      canonical - zonal offset in canonical form to be parsed
      Returns:
      parsed ZonalOffset
      Throws:
      IllegalArgumentException - if given input is not canonical
      Since:
      2.2
      See Also:
      canonical(), toString()

    • getStdFormatPattern

      public String getStdFormatPattern​(Locale locale)

      Obtains a typical localized format pattern in minute precision.

      The character "±" represents a localized offset sign. And the double letters "hh" and "mm" represent localized digits of hour respective minute part of the offset. All other characters are to be interpreted as literals. Many locales return the format "GMT±hh:mm".

      This method is mainly designed for the internal use of the expert format engine of Time4J.

      Parameters:
      locale - language setting
      Returns:
      localized offset pattern
      Since:
      3.23/4.19