public final class OffsetDateTime extends Object implements DateTime, DateTime.WithAdjuster, Comparable<OffsetDateTime>, Serializable
2007-12-03T10:15:30+01:00
.
OffsetDateTime
is an immutable representation of a date-time with an offset.
This class stores all date and time fields, to a precision of nanoseconds,
as well as the offset from UTC. For example, the value
"2nd October 2007 at 13:45.30.123456789 +02:00" can be stored in an OffsetDateTime
.
OffsetDateTime
and Instant
both store an instant on the time-line
to nanosecond precision. The main difference is that this class also stores the
offset from UTC. Instant
should be used when you only need to compare the
object to other instants. OffsetDateTime
should be used when you want to actively
query and manipulate the date and time fields, although you should also consider using
ZonedDateTime
.
DateTime.MinusAdjuster, DateTime.PlusAdjuster, DateTime.WithAdjuster
Modifier and Type | Method and Description |
---|---|
ZonedDateTime |
atZoneSameInstant(ZoneId zone)
Returns a zoned date-time formed from the instant represented by this
date-time and the specified time-zone.
|
ZonedDateTime |
atZoneSimilarLocal(ZoneId zone)
Returns a zoned date-time formed from this date-time and the specified time-zone.
|
ZonedDateTime |
atZoneSimilarLocal(ZoneId zone,
ZoneResolver resolver)
Returns a zoned date-time formed from this date-time and the specified time-zone
taking control of what occurs in time-line gaps and overlaps.
|
int |
compareTo(OffsetDateTime other)
Compares this
OffsetDateTime to another date-time. |
DateTime |
doAdjustment(DateTime calendrical)
Implementation of the strategy to make an adjustment to the specified date-time object.
|
boolean |
equalInstant(OffsetDateTime other)
Checks if the instant of this
OffsetDateTime is equal to that of the specified date-time. |
boolean |
equals(Object obj)
Checks if this date-time is equal to another date-time.
|
<R> R |
extract(Class<R> type)
Extracts date-time information in a generic way.
|
static OffsetDateTime |
from(DateTimeAccessor calendrical)
Obtains an instance of
OffsetDateTime from a calendrical. |
int |
get(DateTimeField field)
Gets the value of the specified date-time field as an
int . |
int |
getDayOfMonth()
Gets the day-of-month field.
|
DayOfWeek |
getDayOfWeek()
Gets the day-of-week field, which is an enum
DayOfWeek . |
int |
getDayOfYear()
Gets the day-of-year field.
|
int |
getHour()
Gets the hour-of-day field.
|
long |
getLong(DateTimeField field)
Gets the value of the specified date-time field as a
Long . |
int |
getMinute()
Gets the minute-of-hour field.
|
Month |
getMonth()
Gets the month-of-year field using the
Month enum. |
int |
getMonthValue()
Gets the month-of-year field from 1 to 12.
|
int |
getNano()
Gets the nano-of-second field.
|
ZoneOffset |
getOffset()
Gets the zone offset.
|
int |
getSecond()
Gets the second-of-minute field.
|
int |
getYear()
Gets the year field.
|
int |
hashCode()
A hash code for this date-time.
|
boolean |
isAfter(OffsetDateTime other)
Checks if the instant of this
OffsetDateTime is after that of the specified date-time. |
boolean |
isBefore(OffsetDateTime other)
Checks if the instant of this
OffsetDateTime is before that of the specified date-time. |
OffsetDateTime |
minus(DateTime.MinusAdjuster adjuster)
Returns a copy of this date-time with the specified period subtracted.
|
OffsetDateTime |
minus(long periodAmount,
PeriodUnit unit)
Returns a copy of this date-time with the specified period subtracted.
|
OffsetDateTime |
minusDays(long days)
Returns a copy of this
OffsetDateTime with the specified period in days subtracted. |
OffsetDateTime |
minusHours(long hours)
Returns a copy of this
OffsetDateTime with the specified period in hours subtracted. |
OffsetDateTime |
minusMinutes(long minutes)
Returns a copy of this
OffsetDateTime with the specified period in minutes subtracted. |
OffsetDateTime |
minusMonths(long months)
Returns a copy of this
OffsetDateTime with the specified period in months subtracted. |
OffsetDateTime |
minusNanos(long nanos)
Returns a copy of this
OffsetDateTime with the specified period in nanoseconds subtracted. |
OffsetDateTime |
minusSeconds(long seconds)
Returns a copy of this
OffsetDateTime with the specified period in seconds subtracted. |
OffsetDateTime |
minusWeeks(long weeks)
Returns a copy of this
OffsetDateTime with the specified period in weeks subtracted. |
OffsetDateTime |
minusYears(long years)
Returns a copy of this
OffsetDateTime with the specified period in years subtracted. |
static OffsetDateTime |
now()
Obtains the current date-time from the system clock in the default time-zone.
|
static OffsetDateTime |
now(Clock clock)
Obtains the current date-time from the specified clock.
|
static OffsetDateTime |
of(int year,
int month,
int dayOfMonth,
int hour,
int minute,
int second,
int nanoOfSecond,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime from year, month,
day, hour, minute, second and nanosecond. |
static OffsetDateTime |
of(int year,
int month,
int dayOfMonth,
int hour,
int minute,
int second,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime from year, month,
day, hour, minute and second, setting the nanosecond to zero. |
static OffsetDateTime |
of(int year,
int month,
int dayOfMonth,
int hour,
int minute,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime from year, month,
day, hour and minute, setting the second and nanosecond to zero. |
static OffsetDateTime |
of(int year,
Month month,
int dayOfMonth,
int hour,
int minute,
int second,
int nanoOfSecond,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime from year, month,
day, hour, minute, second and nanosecond. |
static OffsetDateTime |
of(int year,
Month month,
int dayOfMonth,
int hour,
int minute,
int second,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime from year, month,
day, hour, minute and second, setting the nanosecond to zero. |
static OffsetDateTime |
of(int year,
Month month,
int dayOfMonth,
int hour,
int minute,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime from year, month,
day, hour and minute, setting the second and nanosecond to zero. |
static OffsetDateTime |
of(LocalDate date,
LocalTime time,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime from a date, time and offset. |
static OffsetDateTime |
of(LocalDate date,
OffsetTime offsetTime)
Obtains an instance of
OffsetDateTime from a local date and offset time. |
static OffsetDateTime |
of(LocalDateTime dateTime,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime from a date-time and offset. |
static OffsetDateTime |
ofEpochSecond(long epochSecond,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime using seconds from the
epoch of 1970-01-01T00:00:00Z. |
static OffsetDateTime |
ofInstant(Instant instant,
ZoneId zone)
Obtains an instance of
OffsetDateTime from an Instant and time-zone. |
static OffsetDateTime |
ofInstant(Instant instant,
ZoneOffset offset)
Obtains an instance of
OffsetDateTime from an Instant and offset. |
static OffsetDateTime |
ofInstantUTC(Instant instant)
Obtains an instance of
OffsetDateTime from an Instant
using the UTC offset. |
static OffsetDateTime |
parse(CharSequence text)
Obtains an instance of
OffsetDateTime from a text string such as 2007-12-03T10:15:30+01:00 . |
static OffsetDateTime |
parse(CharSequence text,
CalendricalFormatter formatter)
Obtains an instance of
OffsetDateTime from a text string using a specific formatter. |
long |
periodUntil(DateTime endDateTime,
PeriodUnit unit)
Calculates the period from this date-time until the given date-time in the specified unit.
|
OffsetDateTime |
plus(DateTime.PlusAdjuster adjuster)
Returns a copy of this date-time with the specified period added.
|
OffsetDateTime |
plus(long periodAmount,
PeriodUnit unit)
Returns a copy of this date-time with the specified period added.
|
OffsetDateTime |
plusDays(long days)
Returns a copy of this OffsetDateTime with the specified period in days added.
|
OffsetDateTime |
plusHours(long hours)
Returns a copy of this
OffsetDateTime with the specified period in hours added. |
OffsetDateTime |
plusMinutes(long minutes)
Returns a copy of this
OffsetDateTime with the specified period in minutes added. |
OffsetDateTime |
plusMonths(long months)
Returns a copy of this
OffsetDateTime with the specified period in months added. |
OffsetDateTime |
plusNanos(long nanos)
Returns a copy of this
OffsetDateTime with the specified period in nanoseconds added. |
OffsetDateTime |
plusSeconds(long seconds)
Returns a copy of this
OffsetDateTime with the specified period in seconds added. |
OffsetDateTime |
plusWeeks(long weeks)
Returns a copy of this OffsetDateTime with the specified period in weeks added.
|
OffsetDateTime |
plusYears(long years)
Returns a copy of this
OffsetDateTime with the specified period in years added. |
DateTimeValueRange |
range(DateTimeField field)
Gets the range of valid values for the specified date-time field.
|
OffsetDateTime |
resolveOffset(ZoneId zone)
Resolves this date-time against the specified time-zone updating the offset.
|
long |
toEpochSecond()
Converts this date-time to the number of seconds from the epoch
of 1970-01-01T00:00:00Z.
|
Instant |
toInstant()
Converts this date-time to an
Instant . |
LocalDate |
toLocalDate()
Converts this date-time to a
LocalDate . |
LocalDateTime |
toLocalDateTime()
Converts this date-time to a
LocalDateTime . |
LocalTime |
toLocalTime()
Converts this date-time to a
LocalTime . |
OffsetDate |
toOffsetDate()
Converts this date-time to an
OffsetDate . |
OffsetTime |
toOffsetTime()
Converts this date-time to an
OffsetTime . |
String |
toString()
Outputs this date-time as a
String , such as 2007-12-03T10:15:30+01:00 . |
String |
toString(CalendricalFormatter formatter)
Outputs this date-time as a
String using the formatter. |
OffsetDateTime |
with(DateTime.WithAdjuster adjuster)
Returns an adjusted date-time based on this date-time.
|
OffsetDateTime |
with(DateTimeField field,
long newValue)
Returns a copy of this date-time with the specified field altered.
|
OffsetDateTime |
withDate(int year,
int month,
int dayOfMonth)
Returns a copy of this
OffsetDateTime with the date values altered. |
OffsetDateTime |
withDate(int year,
Month month,
int dayOfMonth)
Returns a copy of this
OffsetDateTime with the date values altered. |
OffsetDateTime |
withDayOfMonth(int dayOfMonth)
Returns a copy of this
OffsetDateTime with the day-of-month altered. |
OffsetDateTime |
withDayOfYear(int dayOfYear)
Returns a copy of this
OffsetDateTime with the day-of-year altered. |
OffsetDateTime |
withHour(int hour)
Returns a copy of this
OffsetDateTime with the hour-of-day value altered. |
OffsetDateTime |
withMinute(int minute)
Returns a copy of this
OffsetDateTime with the minute-of-hour value altered. |
OffsetDateTime |
withMonth(int month)
Returns a copy of this
OffsetDateTime with the month-of-year altered. |
OffsetDateTime |
withNano(int nanoOfSecond)
Returns a copy of this
OffsetDateTime with the nano-of-second value altered. |
OffsetDateTime |
withOffsetSameInstant(ZoneOffset offset)
Returns a copy of this
OffsetDateTime with the specified offset ensuring
that the result is at the same instant. |
OffsetDateTime |
withOffsetSameLocal(ZoneOffset offset)
Returns a copy of this
OffsetDateTime with the specified offset ensuring
that the result has the same local date-time. |
OffsetDateTime |
withSecond(int second)
Returns a copy of this
OffsetDateTime with the second-of-minute value altered. |
OffsetDateTime |
withTime(int hour,
int minute)
Returns a copy of this
OffsetDateTime with the time values altered. |
OffsetDateTime |
withTime(int hour,
int minute,
int second)
Returns a copy of this
OffsetDateTime with the time values altered. |
OffsetDateTime |
withTime(int hour,
int minute,
int second,
int nanoOfSecond)
Returns a copy of this OffsetDateTime with the time values altered.
|
OffsetDateTime |
withYear(int year)
Returns a copy of this
OffsetDateTime with the year altered. |
public static OffsetDateTime now()
This will query the system clock
in the default
time-zone to obtain the current date-time.
The offset will be calculated from the time-zone in the clock.
Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.
public static OffsetDateTime now(Clock clock)
This will query the specified clock to obtain the current date-time. The offset will be calculated from the time-zone in the clock.
Using this method allows the use of an alternate clock for testing.
The alternate clock may be introduced using dependency injection
.
clock
- the clock to use, not nullpublic static OffsetDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, ZoneOffset offset)
OffsetDateTime
from year, month,
day, hour and minute, setting the second and nanosecond to zero.
The day must be valid for the year and month, otherwise an exception will be thrown. The second and nanosecond fields will be set to zero.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59offset
- the zone offset, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearpublic static OffsetDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second, ZoneOffset offset)
OffsetDateTime
from year, month,
day, hour, minute and second, setting the nanosecond to zero.
The day must be valid for the year and month, otherwise an exception will be thrown. The nanosecond field will be set to zero.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59offset
- the zone offset, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearpublic static OffsetDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneOffset offset)
OffsetDateTime
from year, month,
day, hour, minute, second and nanosecond.
The day must be valid for the year and month, otherwise an exception will be thrown.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999offset
- the zone offset, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearpublic static OffsetDateTime of(int year, int month, int dayOfMonth, int hour, int minute, ZoneOffset offset)
OffsetDateTime
from year, month,
day, hour and minute, setting the second and nanosecond to zero.
The day must be valid for the year and month, otherwise an exception will be thrown. The second and nanosecond fields will be set to zero.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59offset
- the zone offset, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearpublic static OffsetDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, ZoneOffset offset)
OffsetDateTime
from year, month,
day, hour, minute and second, setting the nanosecond to zero.
The day must be valid for the year and month, otherwise an exception will be thrown. The nanosecond field will be set to zero.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59offset
- the zone offset, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearpublic static OffsetDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneOffset offset)
OffsetDateTime
from year, month,
day, hour, minute, second and nanosecond.
The day must be valid for the year and month, otherwise an exception will be thrown.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999offset
- the zone offset, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearpublic static OffsetDateTime of(LocalDate date, LocalTime time, ZoneOffset offset)
OffsetDateTime
from a date, time and offset.date
- the local date, not nulltime
- the local time, not nulloffset
- the zone offset, not nullpublic static OffsetDateTime of(LocalDate date, OffsetTime offsetTime)
OffsetDateTime
from a local date and offset time.date
- the local date, not nulloffsetTime
- the offset time to use, not nullpublic static OffsetDateTime of(LocalDateTime dateTime, ZoneOffset offset)
OffsetDateTime
from a date-time and offset.dateTime
- the local date-time, not nulloffset
- the zone offset, not nullpublic static OffsetDateTime ofInstantUTC(Instant instant)
OffsetDateTime
from an Instant
using the UTC offset.
The resulting date-time represents exactly the same instant on the time-line.
Calling toInstant()
will return an instant equal to the one used here.
instant
- the instant to create a date-time from, not nullDateTimeException
- if the instant exceeds the supported date rangepublic static OffsetDateTime ofInstant(Instant instant, ZoneOffset offset)
OffsetDateTime
from an Instant
and offset.
The resulting date-time represents exactly the same instant on the time-line.
Calling toInstant()
will return an instant equal to the one used here.
instant
- the instant to create the date-time from, not nulloffset
- the zone offset to use, not nullDateTimeException
- if the instant exceeds the supported date rangepublic static OffsetDateTime ofInstant(Instant instant, ZoneId zone)
OffsetDateTime
from an Instant
and time-zone.
The resulting date-time represents exactly the same instant on the time-line.
Calling toInstant()
will return an instant equal to the one used here.
instant
- the instant to create the date-time from, not nullzone
- the time-zone to use, not nullDateTimeException
- if the instant exceeds the supported date rangepublic static OffsetDateTime ofEpochSecond(long epochSecond, ZoneOffset offset)
OffsetDateTime
using seconds from the
epoch of 1970-01-01T00:00:00Z.
The nanosecond field is set to zero.
epochSecond
- the number of seconds from the epoch of 1970-01-01T00:00:00ZDateTimeException
- if the result exceeds the supported rangepublic static OffsetDateTime from(DateTimeAccessor calendrical)
OffsetDateTime
from a calendrical.
A calendrical represents some form of date and time information.
This factory converts the arbitrary calendrical to an instance of OffsetDateTime
.
calendrical
- the calendrical to convert, not nullDateTimeException
- if unable to convert to an OffsetDateTime
public static OffsetDateTime parse(CharSequence text)
OffsetDateTime
from a text string such as 2007-12-03T10:15:30+01:00
.
The string must represent a valid date-time and is parsed using
DateTimeFormatters.isoOffsetDateTime()
.
text
- the text to parse such as "2007-12-03T10:15:30+01:00", not nullDateTimeParseException
- if the text cannot be parsedpublic static OffsetDateTime parse(CharSequence text, CalendricalFormatter formatter)
OffsetDateTime
from a text string using a specific formatter.
The text is parsed using the formatter, returning a date-time.
text
- the text to parse, not nullformatter
- the formatter to use, not nullDateTimeParseException
- if the text cannot be parsedpublic DateTimeValueRange range(DateTimeField field)
DateTimeAccessor
All fields can be expressed as a long
integer.
This method returns an object that describes the valid range for that value.
Note that the result only describes the minimum and maximum valid values and it is important not to read too much into them. For example, there could be values within the range that are invalid for the field.
This method will return a result whether or not the implementation supports the field.
LocalDateTimeField
before
delegating on to the doRange method
on the specified field.range
in interface DateTimeAccessor
field
- the field to get, not nullpublic int get(DateTimeField field)
DateTimeAccessor
int
.
This queries the date-time for the value for the specified field. The returned value will always be within the valid range of values for the field. If the date-time cannot return the value an exception will be thrown.
LocalDateTimeField
before
delegating on to the doGet method
on the specified field.get
in interface DateTimeAccessor
field
- the field to get, not nullpublic long getLong(DateTimeField field)
DateTimeAccessor
Long
.
This queries the date-time for the value for the specified field. The returned value may be outside the valid range of values for the field. If the date-time cannot return the value, it will throw an exception.
LocalDateTimeField
before
delegating on to the doGet method
on the specified field.getLong
in interface DateTimeAccessor
field
- the field to get, not nullpublic ZoneOffset getOffset()
public OffsetDateTime withOffsetSameLocal(ZoneOffset offset)
OffsetDateTime
with the specified offset ensuring
that the result has the same local date-time.
This method returns an object with the same LocalDateTime
and the specified ZoneOffset
.
No calculation is needed or performed.
For example, if this time represents 2007-12-03T10:30+02:00
and the offset specified is
+03:00
, then this method will return 2007-12-03T10:30+03:00
.
To take into account the difference between the offsets, and adjust the time fields,
use withOffsetSameInstant(javax.time.ZoneOffset)
.
This instance is immutable and unaffected by this method call.
offset
- the zone offset to change to, not nullOffsetDateTime
based on this date-time with the requested offset, not nullpublic OffsetDateTime withOffsetSameInstant(ZoneOffset offset)
OffsetDateTime
with the specified offset ensuring
that the result is at the same instant.
This method returns an object with the specified ZoneOffset
and a LocalDateTime
adjusted by the difference between the two offsets.
This will result in the old and new objects representing the same instant.
This is useful for finding the local time in a different offset.
For example, if this time represents 2007-12-03T10:30+02:00
and the offset specified is
+03:00
, then this method will return 2007-12-03T11:30+03:00
.
To change the offset without adjusting the local time use withOffsetSameLocal(javax.time.ZoneOffset)
.
This instance is immutable and unaffected by this method call.
offset
- the zone offset to change to, not nullOffsetDateTime
based on this date-time with the requested offset, not nullDateTimeException
- if the result exceeds the supported date rangepublic int getYear()
This method returns the primitive int
value for the year.
public int getMonthValue()
This method returns the month as an int
from 1 to 12.
Application code is frequently clearer if the enum Month
is used by calling getMonth()
.
getMonth()
public Month getMonth()
Month
enum.
This method returns the enum Month
for the month.
This avoids confusion as to what int
values mean.
If you need access to the primitive int
value then the enum
provides the int value
.
getMonthValue()
public int getDayOfMonth()
This method returns the primitive int
value for the day-of-month.
public int getDayOfYear()
This method returns the primitive int
value for the day-of-year.
public DayOfWeek getDayOfWeek()
DayOfWeek
.
This method returns the enum DayOfWeek
for the day-of-week.
This avoids confusion as to what int
values mean.
If you need access to the primitive int
value then the enum
provides the int value
.
Additional information can be obtained from the DayOfWeek
.
This includes textual names of the values.
public int getHour()
public int getMinute()
public int getSecond()
public int getNano()
public OffsetDateTime with(DateTime.WithAdjuster adjuster)
This adjusts the date-time according to the rules of the specified adjuster.
A simple adjuster might simply set the one of the fields, such as the year field.
A more complex adjuster might set the date-time to the last day of the month.
A selection of common adjustments is provided in DateTimeAdjusters
.
These include finding the "last day of the month" and "next Wednesday".
The adjuster is responsible for handling special cases, such as the varying
lengths of month and leap years.
In addition, all principal classes implement the DateTime.WithAdjuster
interface,
including this one. For example, LocalDate
implements the adjuster interface.
As such, this code will compile and run:
dateTime.with(date);
This instance is immutable and unaffected by this method call.
with
in interface DateTime
adjuster
- the adjuster to use, not nullOffsetDateTime
based on this date-time with the adjustment made, not nullDateTimeException
- if the adjustment cannot be madepublic OffsetDateTime with(DateTimeField field, long newValue)
This method returns a new date-time based on this date-time with a new value for the specified field. This can be used to change any field, for example to set the year, month of day-of-month. The offset is not part of the calculation and will be unchanged in the result.
In some cases, changing the specified field can cause the resulting date-time to become invalid, such as changing the month from January to February would make the day-of-month 31 invalid. In cases like this, the field is responsible for resolving the date. Typically it will choose the previous valid date, which would be the last valid day of February in this example.
This instance is immutable and unaffected by this method call.
with
in interface DateTime
with
in interface DateTimeAccessor
field
- the field to set in the returned date-time, not nullnewValue
- the new value of the field in the returned date-time, not nullOffsetDateTime
based on this date-time with the specified field set, not nullDateTimeException
- if the value is invalidpublic OffsetDateTime withYear(int year)
OffsetDateTime
with the year altered.
The offset does not affect the calculation and will be the same in the result.
If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.
This instance is immutable and unaffected by this method call.
year
- the year to set in the returned date, from MIN_YEAR to MAX_YEAROffsetDateTime
based on this date-time with the requested year, not nullDateTimeException
- if the year value is invalidpublic OffsetDateTime withMonth(int month)
OffsetDateTime
with the month-of-year altered.
The offset does not affect the calculation and will be the same in the result.
If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.
This instance is immutable and unaffected by this method call.
month
- the month-of-year to set in the returned date, from 1 (January) to 12 (December)OffsetDateTime
based on this date-time with the requested month, not nullDateTimeException
- if the month-of-year value is invalidpublic OffsetDateTime withDayOfMonth(int dayOfMonth)
OffsetDateTime
with the day-of-month altered.
If the resulting OffsetDateTime
is invalid, an exception is thrown.
The offset does not affect the calculation and will be the same in the result.
This instance is immutable and unaffected by this method call.
dayOfMonth
- the day-of-month to set in the returned date, from 1 to 28-31OffsetDateTime
based on this date-time with the requested day, not nullDateTimeException
- if the day-of-month value is invalidDateTimeException
- if the day-of-month is invalid for the month-yearpublic OffsetDateTime withDayOfYear(int dayOfYear)
OffsetDateTime
with the day-of-year altered.
If the resulting OffsetDateTime
is invalid, an exception is thrown.
This instance is immutable and unaffected by this method call.
dayOfYear
- the day-of-year to set in the returned date, from 1 to 365-366OffsetDateTime
based on this date with the requested day, not nullDateTimeException
- if the day-of-year value is invalidDateTimeException
- if the day-of-year is invalid for the yearpublic OffsetDateTime withDate(int year, Month month, int dayOfMonth)
OffsetDateTime
with the date values altered.
This method will return a new instance with the same time fields, but altered date fields.
This instance is immutable and unaffected by this method call.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31OffsetDateTime
based on this date-time with the requested date, not nullDateTimeException
- if any field value is invalidDateTimeException
- if the day-of-month is invalid for the month-yearpublic OffsetDateTime withDate(int year, int month, int dayOfMonth)
OffsetDateTime
with the date values altered.
This method will return a new instance with the same time fields, but altered date fields.
This instance is immutable and unaffected by this method call.
year
- the year to represent, from MIN_VALUE + 1 to MAX_VALUEmonth
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31OffsetDateTime
based on this date-time with the requested date, not nullDateTimeException
- if any field value is invalidDateTimeException
- if the day-of-month is invalid for the month-yearpublic OffsetDateTime withHour(int hour)
OffsetDateTime
with the hour-of-day value altered.
This instance is immutable and unaffected by this method call.
hour
- the hour-of-day to represent, from 0 to 23OffsetDateTime
based on this date-time with the requested hour, not nullDateTimeException
- if the hour value is invalidpublic OffsetDateTime withMinute(int minute)
OffsetDateTime
with the minute-of-hour value altered.
This instance is immutable and unaffected by this method call.
minute
- the minute-of-hour to represent, from 0 to 59OffsetDateTime
based on this date-time with the requested minute, not nullDateTimeException
- if the minute value is invalidpublic OffsetDateTime withSecond(int second)
OffsetDateTime
with the second-of-minute value altered.
This instance is immutable and unaffected by this method call.
second
- the second-of-minute to represent, from 0 to 59OffsetDateTime
based on this date-time with the requested second, not nullDateTimeException
- if the second value is invalidpublic OffsetDateTime withNano(int nanoOfSecond)
OffsetDateTime
with the nano-of-second value altered.
This instance is immutable and unaffected by this method call.
nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999OffsetDateTime
based on this date-time with the requested nanosecond, not nullDateTimeException
- if the nanos value is invalidpublic OffsetDateTime withTime(int hour, int minute)
OffsetDateTime
with the time values altered.
This method will return a new instance with the same date fields,
but altered time fields.
This is a shorthand for withTime(int,int,int,int)
and sets
the second and nanosecond fields to zero.
This instance is immutable and unaffected by this method call.
hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59OffsetDateTime
based on this date-time with the requested time, not nullDateTimeException
- if any field value is invalidpublic OffsetDateTime withTime(int hour, int minute, int second)
OffsetDateTime
with the time values altered.
This method will return a new instance with the same date fields,
but altered time fields.
This is a shorthand for withTime(int,int,int,int)
and sets
the nanosecond fields to zero.
This instance is immutable and unaffected by this method call.
hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59OffsetDateTime
based on this date-time with the requested time, not nullDateTimeException
- if any field value is invalidpublic OffsetDateTime withTime(int hour, int minute, int second, int nanoOfSecond)
This instance is immutable and unaffected by this method call.
hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999OffsetDateTime
based on this date-time with the requested time, not nullDateTimeException
- if any field value is invalidpublic OffsetDateTime plus(DateTime.PlusAdjuster adjuster)
This method returns a new date-time based on this time with the specified period added.
The adjuster is typically Period
but may be any other type implementing
the DateTime.PlusAdjuster
interface.
The calculation is delegated to the specified adjuster, which typically calls
back to plus(long, PeriodUnit)
.
The offset is not part of the calculation and will be unchanged in the result.
This instance is immutable and unaffected by this method call.
plus
in interface DateTime
adjuster
- the adjuster to use, not nullOffsetDateTime
based on this date-time with the addition made, not nullDateTimeException
- if the addition cannot be madeArithmeticException
- if numeric overflow occurspublic OffsetDateTime plus(long periodAmount, PeriodUnit unit)
This method returns a new date-time based on this date-time with the specified period added. This can be used to add any period that is defined by a unit, for example to add years, months or days. The unit is responsible for the details of the calculation, including the resolution of any edge cases in the calculation. The offset is not part of the calculation and will be unchanged in the result.
This instance is immutable and unaffected by this method call.
plus
in interface DateTime
periodAmount
- the amount of the unit to add to the returned date-time, not nullunit
- the unit of the period to add, not nullOffsetDateTime
based on this date-time with the specified period added, not nullDateTimeException
- if the unit cannot be added to this typepublic OffsetDateTime plusYears(long years)
OffsetDateTime
with the specified period in years added.
This method adds the specified amount to the years field in three steps:
For example, 2008-02-29 (leap year) plus one year would result in the invalid date 2009-02-29 (standard year). Instead of returning an invalid result, the last valid day of the month, 2009-02-28, is selected instead.
This instance is immutable and unaffected by this method call.
years
- the years to add, may be negativeOffsetDateTime
based on this date-time with the years added, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime plusMonths(long months)
OffsetDateTime
with the specified period in months added.
This method adds the specified amount to the months field in three steps:
For example, 2007-03-31 plus one month would result in the invalid date 2007-04-31. Instead of returning an invalid result, the last valid day of the month, 2007-04-30, is selected instead.
This instance is immutable and unaffected by this method call.
months
- the months to add, may be negativeOffsetDateTime
based on this date-time with the months added, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime plusWeeks(long weeks)
This method adds the specified amount in weeks to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 plus one week would result in the 2009-01-07.
This instance is immutable and unaffected by this method call.
weeks
- the weeks to add, may be negativeOffsetDateTime
based on this date-time with the weeks added, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime plusDays(long days)
This method adds the specified amount to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 plus one day would result in the 2009-01-01.
This instance is immutable and unaffected by this method call.
days
- the days to add, may be negativeOffsetDateTime
based on this date-time with the days added, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime plusHours(long hours)
OffsetDateTime
with the specified period in hours added.
This instance is immutable and unaffected by this method call.
hours
- the hours to add, may be negativeOffsetDateTime
based on this date-time with the hours added, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime plusMinutes(long minutes)
OffsetDateTime
with the specified period in minutes added.
This instance is immutable and unaffected by this method call.
minutes
- the minutes to add, may be negativeOffsetDateTime
based on this date-time with the minutes added, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime plusSeconds(long seconds)
OffsetDateTime
with the specified period in seconds added.
This instance is immutable and unaffected by this method call.
seconds
- the seconds to add, may be negativeOffsetDateTime
based on this date-time with the seconds added, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime plusNanos(long nanos)
OffsetDateTime
with the specified period in nanoseconds added.
This instance is immutable and unaffected by this method call.
nanos
- the nanos to add, may be negativeOffsetDateTime
based on this date-time with the nanoseconds added, not nullDateTimeException
- if the unit cannot be added to this typepublic OffsetDateTime minus(DateTime.MinusAdjuster adjuster)
This method returns a new date-time based on this time with the specified period subtracted.
The adjuster is typically Period
but may be any other type implementing
the DateTime.MinusAdjuster
interface.
The calculation is delegated to the specified adjuster, which typically calls
back to minus(long, PeriodUnit)
.
The offset is not part of the calculation and will be unchanged in the result.
This instance is immutable and unaffected by this method call.
minus
in interface DateTime
adjuster
- the adjuster to use, not nullOffsetDateTime
based on this date-time with the subtraction made, not nullDateTimeException
- if the subtraction cannot be madeArithmeticException
- if numeric overflow occurspublic OffsetDateTime minus(long periodAmount, PeriodUnit unit)
This method returns a new date-time based on this date-time with the specified period subtracted. This can be used to subtract any period that is defined by a unit, for example to subtract years, months or days. The unit is responsible for the details of the calculation, including the resolution of any edge cases in the calculation. The offset is not part of the calculation and will be unchanged in the result.
This instance is immutable and unaffected by this method call.
public OffsetDateTime minusYears(long years)
OffsetDateTime
with the specified period in years subtracted.
This method subtracts the specified amount from the years field in three steps:
For example, 2008-02-29 (leap year) minus one year would result in the invalid date 2009-02-29 (standard year). Instead of returning an invalid result, the last valid day of the month, 2009-02-28, is selected instead.
This instance is immutable and unaffected by this method call.
years
- the years to subtract, may be negativeOffsetDateTime
based on this date-time with the years subtracted, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime minusMonths(long months)
OffsetDateTime
with the specified period in months subtracted.
This method subtracts the specified amount from the months field in three steps:
For example, 2007-03-31 minus one month would result in the invalid date 2007-04-31. Instead of returning an invalid result, the last valid day of the month, 2007-04-30, is selected instead.
This instance is immutable and unaffected by this method call.
months
- the months to subtract, may be negativeOffsetDateTime
based on this date-time with the months subtracted, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime minusWeeks(long weeks)
OffsetDateTime
with the specified period in weeks subtracted.
This method subtracts the specified amount in weeks from the days field decrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 minus one week would result in the 2009-01-07.
This instance is immutable and unaffected by this method call.
weeks
- the weeks to subtract, may be negativeOffsetDateTime
based on this date-time with the weeks subtracted, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime minusDays(long days)
OffsetDateTime
with the specified period in days subtracted.
This method subtracts the specified amount from the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 minus one day would result in the 2009-01-01.
This instance is immutable and unaffected by this method call.
days
- the days to subtract, may be negativeOffsetDateTime
based on this date-time with the days subtracted, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime minusHours(long hours)
OffsetDateTime
with the specified period in hours subtracted.
This instance is immutable and unaffected by this method call.
hours
- the hours to subtract, may be negativeOffsetDateTime
based on this date-time with the hours subtracted, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime minusMinutes(long minutes)
OffsetDateTime
with the specified period in minutes subtracted.
This instance is immutable and unaffected by this method call.
minutes
- the minutes to subtract, may be negativeOffsetDateTime
based on this date-time with the minutes subtracted, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime minusSeconds(long seconds)
OffsetDateTime
with the specified period in seconds subtracted.
This instance is immutable and unaffected by this method call.
seconds
- the seconds to subtract, may be negativeOffsetDateTime
based on this date-time with the seconds subtracted, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime minusNanos(long nanos)
OffsetDateTime
with the specified period in nanoseconds subtracted.
This instance is immutable and unaffected by this method call.
nanos
- the nanos to subtract, may be negativeOffsetDateTime
based on this date-time with the nanoseconds subtracted, not nullDateTimeException
- if the result exceeds the supported date rangepublic OffsetDateTime resolveOffset(ZoneId zone)
The resolution will return an OffsetDateTime
based on this one
with the offset resolved to be valid for the time-zone.
The offset selected is the offset that is valid at the instant that this
date-time represents.
This method can be used to manage time-zones without using ZonedDateTime
.
Simply create an OffsetDateTime
from an instant and resolve the offset
using this method to be accurate. After every calculation, the date-time must
be re-resolved to ensure that the offset is always correct for the zone.
This instance is immutable and unaffected by this method call.
zone
- the time-zone to use to resolve the offset, not nullOffsetDateTime
based on this date-time with the correct offset for the zone, not nullArithmeticException
- if numeric overflow occurspublic ZonedDateTime atZoneSameInstant(ZoneId zone)
This conversion will ignore the visible local date-time and use the underlying instant instead. This avoids any problems with local time-line gaps or overlaps. The result might have different values for fields such as hour, minute an even day.
To attempt to retain the values of the fields, use atZoneSimilarLocal(ZoneId)
.
This instance is immutable and unaffected by this method call.
zone
- the time-zone to use, not nullpublic ZonedDateTime atZoneSimilarLocal(ZoneId zone)
Time-zone rules, such as daylight savings, mean that not every time on the
local time-line exists. If the local date-time is in a gap or overlap according to
the rules then a resolver is used to determine the resultant local time and offset.
This method uses the retain-offset
resolver.
This selects the date-time immediately after a gap and retains the offset in
overlaps where possible, selecting the earlier offset if not possible.
Finer control over gaps and overlaps is available in two ways.
If you simply want to use the later offset at overlaps then call
ZonedDateTime.withLaterOffsetAtOverlap()
immediately after this method.
Alternately, pass a specific resolver to atZoneSimilarLocal(ZoneId, ZoneResolver)
.
To create a zoned date-time at the same instant irrespective of the local time-line,
use atZoneSameInstant(ZoneId)
.
This instance is immutable and unaffected by this method call.
zone
- the time-zone to use, not nullpublic ZonedDateTime atZoneSimilarLocal(ZoneId zone, ZoneResolver resolver)
Time-zone rules, such as daylight savings, mean that not every time on the local time-line exists. If the local date-time is in a gap or overlap according to the rules then the resolver is used to determine the resultant local time and offset.
To create a zoned date-time at the same instant irrespective of the local time-line,
use atZoneSameInstant(ZoneId)
.
This instance is immutable and unaffected by this method call.
zone
- the time-zone to use, not nullresolver
- the zone resolver to use for gaps and overlaps, not nullDateTimeException
- if the date-time cannot be resolvedpublic <R> R extract(Class<R> type)
This method exists to fulfill the DateTimeAccessor
interface.
This implementation returns the following types:
extract
in interface DateTimeAccessor
R
- the type to extracttype
- the type to extract, null returns nullpublic DateTime doAdjustment(DateTime calendrical)
DateTime.WithAdjuster
This method is not intended to be called by application code directly.
Instead, the DateTime.with(WithAdjuster)
method should be used:
Implementations must use the methods on DateTime
to make the adjustment.
The returned object must have the same observable type as this object.
The input object will be mutated if it is mutable, or a new object returned if immutable.
This interface can be used by calendar systems other than ISO. Implementations may choose to document compatibility with other calendar systems, or validate for it by querying the calendar system from the input object.
doAdjustment
in interface DateTime.WithAdjuster
calendrical
- the date-time object to adjust, not nullpublic long periodUntil(DateTime endDateTime, PeriodUnit unit)
DateTime
This is used to calculate the period between two date-times.
This method operates in association with PeriodUnit.between(R, R)
.
That method returns an object which can be used directly in addition/subtraction
whereas this method returns the amount directly:
long period = start.periodUntil(end, MONTHS); // this method long period = MONTHS.between(start, end).getAmount(); // same as above dateTime.plus(MONTHS.between(start, end)); // directly add
periodUntil
in interface DateTime
endDateTime
- the end date-time, of the same type as this object, not nullunit
- the unit to measure the period in, not nullpublic Instant toInstant()
Instant
.public LocalDate toLocalDate()
LocalDate
.public LocalTime toLocalTime()
LocalTime
.public LocalDateTime toLocalDateTime()
LocalDateTime
.public OffsetDate toOffsetDate()
OffsetDate
.public OffsetTime toOffsetTime()
OffsetTime
.public long toEpochSecond()
Instants on the time-line after the epoch are positive, earlier are negative.
public int compareTo(OffsetDateTime other)
OffsetDateTime
to another date-time.
The comparison is based on the instant then local date-time.
This ordering is consistent with equals()
.
For example, the following is the comparator order:
2008-12-03T10:30+01:00
2008-12-03T11:00+01:00
2008-12-03T12:00+02:00
2008-12-03T11:30+01:00
2008-12-03T12:00+01:00
2008-12-03T12:30+01:00
equals()
.compareTo
in interface Comparable<OffsetDateTime>
other
- the other date-time to compare to, not nullpublic boolean isAfter(OffsetDateTime other)
OffsetDateTime
is after that of the specified date-time.
This method differs from the comparison in compareTo(javax.time.OffsetDateTime)
and equals(java.lang.Object)
in that it
only compares the instant of the date-time. This is equivalent to using
dateTime1.toInstant().isAfter(dateTime2.toInstant());
.
other
- the other date-time to compare to, not nullpublic boolean isBefore(OffsetDateTime other)
OffsetDateTime
is before that of the specified date-time.
This method differs from the comparison in compareTo(javax.time.OffsetDateTime)
in that it
only compares the instant of the date-time. This is equivalent to using
dateTime1.toInstant().isBefore(dateTime2.toInstant());
.
other
- the other date-time to compare to, not nullpublic boolean equalInstant(OffsetDateTime other)
OffsetDateTime
is equal to that of the specified date-time.
This method differs from the comparison in compareTo(javax.time.OffsetDateTime)
and equals(java.lang.Object)
in that it only compares the instant of the date-time. This is equivalent to using
dateTime1.toInstant().equals(dateTime2.toInstant());
.
other
- the other date-time to compare to, not nullpublic boolean equals(Object obj)
The comparison is based on the local date-time and the offset.
To compare for the same instant on the time-line, use equalInstant(javax.time.OffsetDateTime)
.
Only objects of type OffsetDateTime
are compared, other types return false.
public int hashCode()
public String toString()
String
, such as 2007-12-03T10:15:30+01:00
.
The output will be one of the following ISO-8601 formats:
yyyy-MM-dd'T'HH:mmXXXXX
yyyy-MM-dd'T'HH:mm:ssXXXXX
yyyy-MM-dd'T'HH:mm:ssfnnnXXXXX
yyyy-MM-dd'T'HH:mm:ssfnnnnnnXXXXX
yyyy-MM-dd'T'HH:mm:ssfnnnnnnnnnXXXXX
public String toString(CalendricalFormatter formatter)
String
using the formatter.formatter
- the formatter to use, not nullUnsupportedOperationException
- if the formatter cannot printDateTimeException
- if an error occurs during printing