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 and Description
static ZonalOffset	UTC Constant for the UTC timezone representing a shift of 0 seconds with the canonical representation "Z".

Method Summary

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

clone, finalize, 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.

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()