public final class ZoneOffset extends Object implements Calendrical, Comparable<ZoneOffset>, Serializable
+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.
Modifier and Type | Field and Description |
---|---|
static ZoneOffset |
UTC
The time-zone offset for UTC, with an id of 'Z'.
|
Modifier and Type | Method and Description |
---|---|
int |
compareTo(ZoneOffset other)
Compares this offset to another offset in descending order.
|
boolean |
equals(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.
|
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(PeriodProvider periodProvider)
Obtains an instance of
ZoneOffset from a period. |
static ZoneOffset |
of(String offsetID)
Obtains an instance of
ZoneOffset using the id. |
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 |
ZoneOffset |
plus(PeriodProvider periodProvider)
Returns a copy of this offset with the specified period added.
|
static CalendricalRule<ZoneOffset> |
rule()
Gets the rule for the zone-offset.
|
Period |
toPeriod()
Converts this offset to a period.
|
String |
toString()
Returns a string representation of the zone offset, which is the same
as the normalized id.
|
TimeZone |
toTimeZone()
Converts this offset to a time-zone.
|
public static final ZoneOffset UTC
public static ZoneOffset of(String offsetID)
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
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.
offsetID
- the offset id, not nullIllegalArgumentException
- if the offset id is invalidpublic static ZoneOffset ofHours(int hours)
ZoneOffset
using an offset in hours.hours
- the time-zone offset in hours, from -18 to +18IllegalArgumentException
- if the offset is not in the required rangepublic static ZoneOffset ofHoursMinutes(int hours, int minutes)
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.
hours
- the time-zone offset in hours, from -18 to +18minutes
- the time-zone offset in minutes, from 0 to ±59, sign matches hoursIllegalArgumentException
- if the offset is not in the required rangepublic static ZoneOffset ofHoursMinutesSeconds(int hours, int minutes, int seconds)
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.
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 minutesIllegalArgumentException
- if the offset is not in the required rangepublic static ZoneOffset of(PeriodProvider periodProvider)
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.
periodProvider
- the period to use, not nullCalendricalException
- if the specified period cannot be converted to a Period
IllegalArgumentException
- if the offset is not in the required rangepublic static ZoneOffset ofTotalSeconds(int totalSeconds)
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.
totalSeconds
- the total time-zone offset in seconds, from -64800 to +64800IllegalArgumentException
- if the offset is not in the required rangepublic int getAmountSeconds()
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.
public String getID()
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)
public int getHoursField()
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.
public int getMinutesField()
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.
public int getSecondsField()
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.
public ZoneOffset plus(PeriodProvider periodProvider)
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.
periodProvider
- the period to add, not nullZoneOffset
based on this offset with the period added, never nullCalendricalException
- if the specified period cannot be converted to a Period
IllegalArgumentException
- if the offset is not in the required rangepublic Period toPeriod()
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
.
public TimeZone toTimeZone()
The returned time-zone will use this offset for all instants.
public int compareTo(ZoneOffset other)
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
.
compareTo
in interface Comparable<ZoneOffset>
other
- the other date to compare to, not nullNullPointerException
- if other
is nullpublic boolean equals(Object other)
public int hashCode()
public String toString()
public <T> T get(CalendricalRule<T> 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.
get
in interface Calendrical
rule
- the rule to use, not nullpublic static CalendricalRule<ZoneOffset> rule()
Copyright © 2014. All rights reserved.