ZonalOffset (Time4J-Core 4.23 API)

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

Concurrency:
This class is immutable and can be used by multiple threads in parallel.

Field Summary

Fields
Modifier and Type Field and Description

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

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static ZonalOffset`	`atLongitude(BigDecimal longitude)` Creates a new shift based on a geographical longitude.
`static ZonalOffset`	`atLongitude(OffsetSign sign, int degrees, int arcMinutes, int 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 Detail
  - UTC
```
public static final ZonalOffset UTC
```
    Constant for the UTC timezone representing a shift of 0 seconds with the canonical representation "Z".
- Method Detail
  - 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,
                                      int 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 degreed, defined in range 0 <= degrees <= 180
    
    arcMinutes - arc minute part (0 <= arcMinutes <= 59)
    
    arcSeconds - arc second part (0 <= arcSeconds <= 59)
    
    Returns:
    
    zonal offset in decimal precision
    
    Throws:
    
    IllegalArgumentException - if range check fails (also if total absolute offset goes beyond 180 degrees)
    
    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

Class ZonalOffset

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UTC

Method Detail

atLongitude

atLongitude

ofHours

ofHoursMinutes

ofTotalSeconds

ofTotalSeconds

getSign

getAbsoluteHours

getAbsoluteMinutes

getAbsoluteSeconds

getIntegralAmount

getFractionalAmount

compareTo

equals

hashCode

toString

canonical

parse

getStdFormatPattern