Class ZoneOffset
- All Implemented Interfaces:
Serializable
,Comparable<ZoneOffset>
,Calendrical
+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:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static final class
Rule implementation. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final int
The offset in seconds.private static final ReadWriteLock
Cache of time-zone offset by offset in seconds.private final String
The string form of the time-zone offset.private static final Map<String,
ZoneOffset> Cache of time-zone offset by id.private static final int
The number of minutes per hour.private static final Map<Integer,
ZoneOffset> Cache of time-zone offset by offset in seconds.private static final int
The number of seconds per hour.private static final int
The number of seconds per minute.private static final long
A serialization identifier for this class.static final ZoneOffset
The time-zone offset for UTC, with an id of 'Z'. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionint
compareTo
(ZoneOffset other) Compares this offset to another offset in descending order.boolean
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
Gets the total zone offset in seconds.int
Gets the hours field of the zone offset.getID()
Gets the normalized zone offset id.int
Gets the minutes field of the zone offset.int
Gets the seconds field of the zone offset.int
hashCode()
A hash code for the zone offset.static ZoneOffset
Obtains an instance ofZoneOffset
using the id.static ZoneOffset
of
(PeriodProvider periodProvider) Obtains an instance ofZoneOffset
from a period.static ZoneOffset
ofHours
(int hours) Obtains an instance ofZoneOffset
using an offset in hours.static ZoneOffset
ofHoursMinutes
(int hours, int minutes) Obtains an instance ofZoneOffset
using an offset in hours and minutes.static ZoneOffset
ofHoursMinutesSeconds
(int hours, int minutes, int seconds) Obtains an instance ofZoneOffset
using an offset in hours, minutes and seconds.static ZoneOffset
ofTotalSeconds
(int totalSeconds) Obtains an instance ofZoneOffset
specifying the total offset in secondsprivate static int
parseNumber
(String offsetID, int pos, boolean precededByColon) Parse a two digit zero-prefixed number.plus
(PeriodProvider periodProvider) Returns a copy of this offset with the specified period added.private Object
Resolves singletons.static CalendricalRule<ZoneOffset>
rule()
Gets the rule for the zone-offset.toPeriod()
Converts this offset to a period.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.Converts this offset to a time-zone.private static void
validate
(int hours, int minutes, int seconds) Validates the offset fields.
-
Field Details
-
CACHE_LOCK
Cache of time-zone offset by offset in seconds. -
SECONDS_CACHE
Cache of time-zone offset by offset in seconds. -
ID_CACHE
Cache of time-zone offset by id. -
UTC
The time-zone offset for UTC, with an id of 'Z'. -
SECONDS_PER_HOUR
private static final int SECONDS_PER_HOURThe number of seconds per hour.- See Also:
-
SECONDS_PER_MINUTE
private static final int SECONDS_PER_MINUTEThe number of seconds per minute.- See Also:
-
MINUTES_PER_HOUR
private static final int MINUTES_PER_HOURThe number of minutes per hour.- See Also:
-
serialVersionUID
private static final long serialVersionUIDA serialization identifier for this class.- See Also:
-
amountSeconds
private final int amountSecondsThe offset in seconds. -
id
The string form of the time-zone offset.
-
-
Constructor Details
-
ZoneOffset
private ZoneOffset(int totalSeconds) Constructor.- Parameters:
totalSeconds
- the total time-zone offset in seconds, from -64800 to +64800
-
-
Method Details
-
of
Obtains an instance ofZoneOffset
using the id.This method parses the string id of a
ZoneOffset
to return an instance. The parsing accepts all the formats generated bygetID()
, plus some additional formats:Z
- for UTC+hh:mm
-hh:mm
+hhmm
-hhmm
+hh:mm:ss
-hh:mm:ss
+hhmmss
-hhmmss
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:
IllegalArgumentException
- if the offset id is invalid
-
parseNumber
Parse a two digit zero-prefixed number.- Parameters:
offsetID
- the offset id, not nullpos
- the position to parse, validprecededByColon
- should this number be prefixed by a precededByColon- Returns:
- the parsed number, from 0 to 99
-
ofHours
Obtains an instance ofZoneOffset
using an offset in hours.- Parameters:
hours
- the time-zone offset in hours, from -18 to +18- Returns:
- the ZoneOffset, never null
- Throws:
IllegalArgumentException
- if the offset is not in the required range
-
ofHoursMinutes
Obtains an instance ofZoneOffset
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 +18minutes
- the time-zone offset in minutes, from 0 to ±59, sign matches hours- Returns:
- the ZoneOffset, never null
- Throws:
IllegalArgumentException
- if the offset is not in the required range
-
ofHoursMinutesSeconds
Obtains an instance ofZoneOffset
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 +18minutes
- the time-zone offset in minutes, from 0 to ±59, sign matches hours and secondsseconds
- the time-zone offset in seconds, from 0 to ±59, sign matches hours and minutes- Returns:
- the ZoneOffset, never null
- Throws:
IllegalArgumentException
- if the offset is not in the required range
-
of
Obtains an instance ofZoneOffset
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 aPeriod
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 +18minutes
- the time-zone offset in minutes, from 0 to ±59seconds
- the time-zone offset in seconds, from 0 to ±59- Throws:
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 +18minutes
- the time-zone offset in minutes, from 0 to ±59, sign matches hours and secondsseconds
- the time-zone offset in seconds, from 0 to ±59, sign matches hours and minutes- Returns:
- the total in seconds
-
ofTotalSeconds
Obtains an instance ofZoneOffset
specifying the total offset in secondsThe 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:
IllegalArgumentException
- if the offset is not in the required range
-
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
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()
orgetAmountSeconds()
.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()
orgetAmountSeconds()
.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()
orgetAmountSeconds()
.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
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 aPeriod
IllegalArgumentException
- if the offset is not in the required range
-
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 toP2H45M
, while-01:15
will be converted toP-1H-15M
.- Returns:
- the period equivalent to the zone offset amount, never null
-
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
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 interfaceComparable<ZoneOffset>
- Parameters:
other
- the other date to compare to, not null- Returns:
- the comparator value, negative if less, postive if greater
- Throws:
NullPointerException
- ifother
is null
-
equals
Checks if this instance is equal to the specified offset, comparing the amount of the offset in seconds. -
hashCode
public int hashCode()A hash code for the zone offset. -
toString
Returns a string representation of the zone offset, which is the same as the normalized id. -
get
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 interfaceCalendrical
- Parameters:
rule
- the rule to use, not null- Returns:
- the value for the rule, null if the value cannot be returned
-
rule
Gets the rule for the zone-offset.- Returns:
- the rule for the zone-offset, never null
-