Class OffsetDateTime
- java.lang.Object
-
- javax.time.calendar.OffsetDateTime
-
- All Implemented Interfaces:
Serializable
,Comparable<OffsetDateTime>
,Calendrical
,CalendricalMatcher
,DateAdjuster
,DateProvider
,DateTimeProvider
,TimeAdjuster
,TimeProvider
,InstantProvider
public final class OffsetDateTime extends Object implements Calendrical, InstantProvider, DateTimeProvider, CalendricalMatcher, DateAdjuster, TimeAdjuster, Comparable<OffsetDateTime>, Serializable
A date-time with a zone offset from UTC in the ISO-8601 calendar system, such as2007-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. Thus, for example, the value "2nd October 2007 at 13:45.30.123456789 +02:00" can be stored in anOffsetDateTime
.OffsetDateTime is immutable and thread-safe.
- Author:
- Michael Nascimento Santos, Stephen Colebourne
- See Also:
- Serialized Form
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description LocalDate
adjustDate(LocalDate date)
Adjusts a date to have the value of the date part of this object.LocalTime
adjustTime(LocalTime time)
Adjusts a time to have the value of the time part of this object.ZonedDateTime
atZoneSameInstant(TimeZone zone)
Returns a zoned date-time formed from the instant represented by this date-time and the specified time-zone.ZonedDateTime
atZoneSimilarLocal(TimeZone zone)
Returns a zoned date-time formed from this date-time and the specified time-zone.ZonedDateTime
atZoneSimilarLocal(TimeZone 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 thisOffsetDateTime
to another date-time.boolean
equalInstant(OffsetDateTime other)
Checks if the instant of thisOffsetDateTime
is equal to that of the specified date-time.boolean
equals(Object other)
Checks if thisOffsetDateTime
is equal to the specified date-time.<T> T
get(CalendricalRule<T> rule)
Gets the value of the specified calendrical rule.ISOChronology
getChronology()
Gets the chronology that this date-time uses, which is the ISO calendar system.int
getDayOfMonth()
Gets the day-of-month field.DayOfWeek
getDayOfWeek()
Gets the day-of-week field, which is an enumDayOfWeek
.int
getDayOfYear()
Gets the day-of-year field.int
getHourOfDay()
Gets the hour-of-day field.int
getMinuteOfHour()
Gets the minute-of-hour field.MonthOfYear
getMonthOfYear()
Gets the month-of-year field, which is an enumMonthOfYear
.int
getNanoOfSecond()
Gets the nano-of-second field.ZoneOffset
getOffset()
Gets the zone offset.int
getSecondOfMinute()
Gets the second-of-minute field.int
getYear()
Gets the year field.int
hashCode()
A hash code for thisOffsetDateTime
.boolean
isAfter(OffsetDateTime other)
Checks if the instant of thisOffsetDateTime
is after that of the specified date-time.boolean
isBefore(OffsetDateTime other)
Checks if the instant of thisOffsetDateTime
is before that of the specified date-time.boolean
isLeapYear()
Checks if the year is a leap year, according to the ISO proleptic calendar system rules.boolean
matches(CalendricalMatcher matcher)
Checks whether thisOffsetDateTime
matches the specified matcher.boolean
matchesCalendrical(Calendrical calendrical)
Checks if the date-time extracted from the calendrical matches this.OffsetDateTime
minus(PeriodProvider periodProvider)
Returns a copy of thisOffsetDateTime
with the specified period subtracted.OffsetDateTime
minus(Duration duration)
Returns a copy of thisOffsetDateTime
with the specified duration subtracted.OffsetDateTime
minusDays(long days)
Returns a copy of thisOffsetDateTime
with the specified period in days subtracted.OffsetDateTime
minusHours(long hours)
Returns a copy of thisOffsetDateTime
with the specified period in hours subtracted.OffsetDateTime
minusMinutes(long minutes)
Returns a copy of thisOffsetDateTime
with the specified period in minutes subtracted.OffsetDateTime
minusMonths(long months)
Returns a copy of thisOffsetDateTime
with the specified period in months subtracted.OffsetDateTime
minusMonths(long months, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the specified period in months subtracted.OffsetDateTime
minusNanos(long nanos)
Returns a copy of thisOffsetDateTime
with the specified period in nanoseconds subtracted.OffsetDateTime
minusSeconds(long seconds)
Returns a copy of thisOffsetDateTime
with the specified period in seconds subtracted.OffsetDateTime
minusWeeks(long weeks)
Returns a copy of thisOffsetDateTime
with the specified period in weeks subtracted.OffsetDateTime
minusYears(long years)
Returns a copy of thisOffsetDateTime
with the specified period in years subtracted.OffsetDateTime
minusYears(long years, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
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 monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour, minute, second and nanosecond.static OffsetDateTime
of(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour, minute and second, setting the nanosecond to zero.static OffsetDateTime
of(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour and minute, setting the second and nanosecond to zero.static OffsetDateTime
of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour, minute, second and nanosecond.static OffsetDateTime
of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour, minute and second, setting the nanosecond to zero.static OffsetDateTime
of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour and minute, setting the second and nanosecond to zero.static OffsetDateTime
of(DateProvider dateProvider, OffsetTime offsetTime)
Obtains an instance ofOffsetDateTime
from aDateProvider
andOffsetTime
.static OffsetDateTime
of(DateProvider dateProvider, TimeProvider timeProvider, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from a date, time and zone offset.static OffsetDateTime
of(DateTimeProvider dateTimeProvider, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from a date-time provider.static OffsetDateTime
ofEpochSeconds(long epochSeconds, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
using seconds from the epoch of 1970-01-01T00:00:00Z.static OffsetDateTime
ofInstant(InstantProvider instantProvider, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from anInstantProvider
.static OffsetDateTime
ofMidnight(int year, int monthOfYear, int dayOfMonth, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month and day with the time set to midnight at the start of day.static OffsetDateTime
ofMidnight(int year, MonthOfYear monthOfYear, int dayOfMonth, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month and day with the time set to midnight at the start of day.static OffsetDateTime
ofMidnight(DateProvider dateProvider, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from a date with the time set to midnight at the start of day.static OffsetDateTime
parse(String text)
Obtains an instance ofOffsetDateTime
from a text string such as2007-12-03T10:15:30+01:00
.static OffsetDateTime
parse(String text, DateTimeFormatter formatter)
Obtains an instance ofOffsetDateTime
from a text string using a specific formatter.OffsetDateTime
plus(PeriodProvider periodProvider)
Returns a copy of thisOffsetDateTime
with the specified period added.OffsetDateTime
plus(Duration duration)
Returns a copy of thisOffsetDateTime
with the specified duration 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 thisOffsetDateTime
with the specified period in hours added.OffsetDateTime
plusMinutes(long minutes)
Returns a copy of thisOffsetDateTime
with the specified period in minutes added.OffsetDateTime
plusMonths(long months)
Returns a copy of thisOffsetDateTime
with the specified period in months added.OffsetDateTime
plusMonths(long months, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the specified period in months added.OffsetDateTime
plusNanos(long nanos)
Returns a copy of thisOffsetDateTime
with the specified period in nanoseconds added.OffsetDateTime
plusSeconds(long seconds)
Returns a copy of thisOffsetDateTime
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 thisOffsetDateTime
with the specified period in years added.OffsetDateTime
plusYears(long years, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the specified period in years added.static CalendricalRule<OffsetDateTime>
rule()
Gets the rule forOffsetDateTime
.long
toEpochSeconds()
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 anInstant
.LocalDate
toLocalDate()
Converts this date-time to aLocalDate
.LocalDateTime
toLocalDateTime()
Converts this date-time to aLocalDateTime
.LocalTime
toLocalTime()
Converts this date-time to aLocalTime
.OffsetDate
toOffsetDate()
Converts this date-time to anOffsetDate
.OffsetTime
toOffsetTime()
Converts this date-time to anOffsetTime
.String
toString()
Outputs this date-time as aString
, such as2007-12-03T10:15:30+01:00
.String
toString(DateTimeFormatter formatter)
Outputs this date-time as aString
using the formatter.OffsetDateTime
with(DateAdjuster adjuster)
Returns a copy of this OffsetDateTime with the date altered using the adjuster.OffsetDateTime
with(MonthOfYear monthOfYear)
Returns a copy of thisOffsetDateTime
with the month-of-year altered.OffsetDateTime
with(MonthOfYear monthOfYear, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the month-of-year altered.OffsetDateTime
with(TimeAdjuster adjuster)
Returns a copy of this OffsetDateTime with the time altered using the adjuster.OffsetDateTime
withDate(int year, int monthOfYear, int dayOfMonth)
Returns a copy of thisOffsetDateTime
with the date values altered.OffsetDateTime
withDate(int year, MonthOfYear monthOfYear, int dayOfMonth)
Returns a copy of thisOffsetDateTime
with the date values altered.OffsetDateTime
withDateTime(DateTimeProvider dateTimeProvider)
Returns a copy of thisOffsetDateTime
with the time altered and the offset retained.OffsetDateTime
withDayOfMonth(int dayOfMonth)
Returns a copy of thisOffsetDateTime
with the day-of-month altered.OffsetDateTime
withDayOfMonth(int dayOfMonth, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the day-of-month altered.OffsetDateTime
withDayOfYear(int dayOfYear)
Returns a copy of thisOffsetDateTime
with the day-of-year altered.OffsetDateTime
withHourOfDay(int hourOfDay)
Returns a copy of thisOffsetDateTime
with the hour-of-day value altered.OffsetDateTime
withMinuteOfHour(int minuteOfHour)
Returns a copy of thisOffsetDateTime
with the minute-of-hour value altered.OffsetDateTime
withMonthOfYear(int monthOfYear)
Returns a copy of thisOffsetDateTime
with the month-of-year altered.OffsetDateTime
withMonthOfYear(int monthOfYear, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the month-of-year altered.OffsetDateTime
withNanoOfSecond(int nanoOfSecond)
Returns a copy of thisOffsetDateTime
with the nano-of-second value altered.OffsetDateTime
withOffsetSameInstant(ZoneOffset offset)
Returns a copy of thisOffsetDateTime
with the specified offset ensuring that the result is at the same instant.OffsetDateTime
withOffsetSameLocal(ZoneOffset offset)
Returns a copy of thisOffsetDateTime
with the specified offset ensuring that the result has the same local date-time.OffsetDateTime
withSecondOfMinute(int secondOfMinute)
Returns a copy of thisOffsetDateTime
with the second-of-minute value altered.OffsetDateTime
withTime(int hourOfDay, int minuteOfHour)
Returns a copy of thisOffsetDateTime
with the time values altered.OffsetDateTime
withTime(int hourOfDay, int minuteOfHour, int secondOfMinute)
Returns a copy of thisOffsetDateTime
with the time values altered.OffsetDateTime
withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond)
Returns a copy of this OffsetDateTime with the time values altered.OffsetDateTime
withYear(int year)
Returns a copy of thisOffsetDateTime
with the year altered.OffsetDateTime
withYear(int year, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the year altered.
-
-
-
Method Detail
-
now
public static OffsetDateTime now()
Obtains the current date-time from the system clock in the default time-zone.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.
- Returns:
- the current date-time using the system clock, never null
-
now
public static OffsetDateTime now(Clock clock)
Obtains the current date-time from the specified 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
.- Parameters:
clock
- the clock to use, not null- Returns:
- the current date-time, never null
-
ofMidnight
public static OffsetDateTime ofMidnight(int year, MonthOfYear monthOfYear, int dayOfMonth, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month and day with the time set to midnight at the start of day.The time fields will be set to zero by this factory method.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31offset
- the zone offset, not null- Returns:
- the offset date-time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
ofMidnight
public static OffsetDateTime ofMidnight(int year, int monthOfYear, int dayOfMonth, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month and day with the time set to midnight at the start of day.The time fields will be set to zero by this factory method.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31offset
- the zone offset, not null- Returns:
- the offset date-time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
ofMidnight
public static OffsetDateTime ofMidnight(DateProvider dateProvider, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from a date with the time set to midnight at the start of day.The time fields will be set to zero by this factory method.
- Parameters:
dateProvider
- the date provider to use, not nulloffset
- the zone offset, not null- Returns:
- the offset date-time, never null
-
of
public static OffsetDateTime of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour and minute, setting the second and nanosecond to zero.The second and nanosecond fields will be set to zero by this factory method.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59offset
- the zone offset, not null- Returns:
- the offset date-time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
of
public static OffsetDateTime of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour, minute and second, setting the nanosecond to zero.The day must be valid for the year and month or an exception will be thrown.
The nanosecond field will be set to zero by this factory method.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59secondOfMinute
- the second-of-minute to represent, from 0 to 59offset
- the zone offset, not null- Returns:
- the offset date-time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
of
public static OffsetDateTime of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour, minute, second and nanosecond.The day must be valid for the year and month or an exception will be thrown.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59secondOfMinute
- 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 null- Returns:
- the offset date-time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
of
public static OffsetDateTime of(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour and minute, setting the second and nanosecond to zero.The day must be valid for the year and month or an exception will be thrown.
The second and nanosecond fields will be set to zero by this factory method.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59offset
- the zone offset, not null- Returns:
- the offset date-time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
of
public static OffsetDateTime of(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour, minute and second, setting the nanosecond to zero.The day must be valid for the year and month or an exception will be thrown.
The nanosecond field will be set to zero by this factory method.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59secondOfMinute
- the second-of-minute to represent, from 0 to 59offset
- the zone offset, not null- Returns:
- the offset date-time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
of
public static OffsetDateTime of(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from year, month, day, hour, minute, second and nanosecond.The day must be valid for the year and month or an exception will be thrown.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59secondOfMinute
- 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 null- Returns:
- the offset date-time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
of
public static OffsetDateTime of(DateProvider dateProvider, TimeProvider timeProvider, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from a date, time and zone offset.- Parameters:
dateProvider
- the date provider to use, not nulltimeProvider
- the time provider to use, not nulloffset
- the zone offset, not null- Returns:
- the offset date-time, never null
-
of
public static OffsetDateTime of(DateTimeProvider dateTimeProvider, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from a date-time provider.- Parameters:
dateTimeProvider
- the date-time provider to use, not nulloffset
- the zone offset, not null- Returns:
- the offset date-time, never null
-
of
public static OffsetDateTime of(DateProvider dateProvider, OffsetTime offsetTime)
Obtains an instance ofOffsetDateTime
from aDateProvider
andOffsetTime
.- Parameters:
dateProvider
- the date provider to use, not nulloffsetTime
- the offset time to use, not null- Returns:
- the offset date-time, never null
-
ofInstant
public static OffsetDateTime ofInstant(InstantProvider instantProvider, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
from anInstantProvider
.- Parameters:
instantProvider
- the instant to convert, not nulloffset
- the zone offset, not null- Returns:
- the offset date-time, never null
- Throws:
CalendarConversionException
- if the instant exceeds the supported date range
-
ofEpochSeconds
public static OffsetDateTime ofEpochSeconds(long epochSeconds, ZoneOffset offset)
Obtains an instance ofOffsetDateTime
using seconds from the epoch of 1970-01-01T00:00:00Z.The nanosecond field is set to zero.
- Parameters:
epochSeconds
- the number of seconds from the epoch of 1970-01-01T00:00:00Z- Returns:
- the offset date-time, never null
- Throws:
CalendricalException
- if the result exceeds the supported range
-
parse
public static OffsetDateTime parse(String text)
Obtains an instance ofOffsetDateTime
from a text string such as2007-12-03T10:15:30+01:00
.The following formats are accepted in ASCII:
{Year}-{MonthOfYear}-{DayOfMonth}T{Hour}:{Minute}{OffsetID}
{Year}-{MonthOfYear}-{DayOfMonth}T{Hour}:{Minute}:{Second}{OffsetID}
{Year}-{MonthOfYear}-{DayOfMonth}T{Hour}:{Minute}:{Second}.{NanosecondFraction}{OffsetID}
The year has between 4 and 10 digits with values from MIN_YEAR to MAX_YEAR. If there are more than 4 digits then the year must be prefixed with the plus symbol. Negative years are allowed, but not negative zero.
The month-of-year has 2 digits with values from 1 to 12.
The day-of-month has 2 digits with values from 1 to 31 appropriate to the month.
The hour has 2 digits with values from 0 to 23. The minute has 2 digits with values from 0 to 59. The second has 2 digits with values from 0 to 59. The nanosecond fraction has from 1 to 9 digits with values from 0 to 999,999,999.
The offset ID is the normalized form as defined in
ZoneOffset
.- Parameters:
text
- the text to parse such as '2007-12-03T10:15:30+01:00', not null- Returns:
- the parsed offset date-time, never null
- Throws:
CalendricalException
- if the text cannot be parsed
-
parse
public static OffsetDateTime parse(String text, DateTimeFormatter formatter)
Obtains an instance ofOffsetDateTime
from a text string using a specific formatter.The text is parsed using the formatter, returning a date-time.
- Parameters:
text
- the text to parse, not nullformatter
- the formatter to use, not null- Returns:
- the parsed offset date-time, never null
- Throws:
UnsupportedOperationException
- if the formatter cannot parseCalendricalException
- if the text cannot be parsed
-
getChronology
public ISOChronology getChronology()
Gets the chronology that this date-time uses, which is the ISO calendar system.- Returns:
- the ISO chronology, never null
-
get
public <T> T get(CalendricalRule<T> rule)
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 date-time 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
-
withDateTime
public OffsetDateTime withDateTime(DateTimeProvider dateTimeProvider)
Returns a copy of thisOffsetDateTime
with the time altered and the offset retained.This method returns an object with the same
ZoneOffset
and the specifiedLocalDateTime
. No calculation is needed or performed.- Parameters:
dateTimeProvider
- the local date-time to change to, not null- Returns:
- an
OffsetDateTime
based on this time with the requested time, never null
-
getOffset
public ZoneOffset getOffset()
Gets the zone offset.- Returns:
- the zone offset, never null
-
withOffsetSameLocal
public OffsetDateTime withOffsetSameLocal(ZoneOffset offset)
Returns a copy of thisOffsetDateTime
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 specifiedZoneOffset
. No calculation is needed or performed. For example, if this time represents2007-12-03T10:30+02:00
and the offset specified is+03:00
, then this method will return2007-12-03T10:30+03:00
.To take into account the difference between the offsets, and adjust the time fields, use
withOffsetSameInstant(javax.time.calendar.ZoneOffset)
.This instance is immutable and unaffected by this method call.
- Parameters:
offset
- the zone offset to change to, not null- Returns:
- an
OffsetDateTime
based on this date-time with the requested offset, never null
-
withOffsetSameInstant
public OffsetDateTime withOffsetSameInstant(ZoneOffset offset)
Returns a copy of thisOffsetDateTime
with the specified offset ensuring that the result is at the same instant.This method returns an object with the the specified
ZoneOffset
and aLocalDateTime
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 represents2007-12-03T10:30+02:00
and the offset specified is+03:00
, then this method will return2007-12-03T11:30+03:00
.To change the offset without adjusting the local time use
withOffsetSameLocal(javax.time.calendar.ZoneOffset)
.This instance is immutable and unaffected by this method call.
- Parameters:
offset
- the zone offset to change to, not null- Returns:
- an
OffsetDateTime
based on this date-time with the requested offset, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
getYear
public int getYear()
Gets the year field.This method returns the primitive
int
value for the year. Additional information about the year can be obtained by creating aYear
.- Returns:
- the year, from MIN_YEAR to MAX_YEAR
-
getMonthOfYear
public MonthOfYear getMonthOfYear()
Gets the month-of-year field, which is an enumMonthOfYear
.This method returns the enum
MonthOfYear
for the month. This avoids confusion as to whatint
values mean. If you need access to the primitiveint
value then the enum provides theint value
.Additional information can be obtained from the
MonthOfYear
. This includes month lengths, textual names and access to the quarter-of-year and month-of-quarter values.- Returns:
- the month-of-year, never null
-
getDayOfMonth
public int getDayOfMonth()
Gets the day-of-month field.This method returns the primitive
int
value for the day-of-month.- Returns:
- the day-of-month, from 1 to 31
-
getDayOfYear
public int getDayOfYear()
Gets the day-of-year field.This method returns the primitive
int
value for the day-of-year.- Returns:
- the day-of-year, from 1 to 365, or 366 in a leap year
-
getDayOfWeek
public DayOfWeek getDayOfWeek()
Gets the day-of-week field, which is an enumDayOfWeek
.This method returns the enum
DayOfWeek
for the day-of-week. This avoids confusion as to whatint
values mean. If you need access to the primitiveint
value then the enum provides theint value
.Additional information can be obtained from the
DayOfWeek
. This includes textual names of the values.- Returns:
- the day-of-week, never null
-
getHourOfDay
public int getHourOfDay()
Gets the hour-of-day field.- Returns:
- the hour-of-day, from 0 to 23
-
getMinuteOfHour
public int getMinuteOfHour()
Gets the minute-of-hour field.- Returns:
- the minute-of-hour, from 0 to 59
-
getSecondOfMinute
public int getSecondOfMinute()
Gets the second-of-minute field.- Returns:
- the second-of-minute, from 0 to 59
-
getNanoOfSecond
public int getNanoOfSecond()
Gets the nano-of-second field.- Returns:
- the nano-of-second, from 0 to 999,999,999
-
isLeapYear
public boolean isLeapYear()
Checks if the year is a leap year, according to the ISO proleptic calendar system rules.This method applies the current rules for leap years across the whole time-line. In general, a year is a leap year if it is divisible by four without remainder. However, years divisible by 100, are not leap years, with the exception of years divisible by 400 which are.
For example, 1904 is a leap year it is divisible by 4. 1900 was not a leap year as it is divisible by 100, however 2000 was a leap year as it is divisible by 400.
The calculation is proleptic - applying the same rules into the far future and far past. This is historically inaccurate, but is correct for the ISO8601 standard.
- Returns:
- true if the year is leap, false otherwise
-
with
public OffsetDateTime with(DateAdjuster adjuster)
Returns a copy of this OffsetDateTime with the date altered using the adjuster.Adjusters can be used to alter the date in various ways. A simple adjuster might simply set the one of the fields, such as the year field. A more complex adjuster might set the date to the last day of the month.
The offset and time do not affect the calculation and will be the same in the result.
This instance is immutable and unaffected by this method call.
- Parameters:
adjuster
- the adjuster to use, not null- Returns:
- an
OffsetDateTime
based on this date-time with the date adjusted, never null - Throws:
NullPointerException
- if the adjuster returned null
-
with
public OffsetDateTime with(TimeAdjuster adjuster)
Returns a copy of this OffsetDateTime with the time altered using the adjuster.Adjusters can be used to alter the time in various ways. A simple adjuster might simply set the one of the fields, such as the hour field. A more complex adjuster might set the time to end of the working day.
The offset and date do not affect the calculation and will be the same in the result.
This instance is immutable and unaffected by this method call.
- Parameters:
adjuster
- the adjuster to use, not null- Returns:
- an
OffsetDateTime
based on this date-time with the time adjusted, never null - Throws:
IllegalArgumentException
- if the adjuster returned null
-
withYear
public OffsetDateTime withYear(int year)
Returns a copy of thisOffsetDateTime
with the year altered. If the resultingOffsetDateTime
is invalid, it will be resolved usingDateResolvers.previousValid()
. The offset does not affect the calculation and will be the same in the result.This method does the same as
withYear(year, DateResolvers.previousValid())
.This instance is immutable and unaffected by this method call.
- Parameters:
year
- the year to set in the returned date, from MIN_YEAR to MAX_YEAR- Returns:
- an
OffsetDateTime
based on this date-time with the requested year, never null - Throws:
IllegalCalendarFieldValueException
- if the year value is invalid
-
withYear
public OffsetDateTime withYear(int year, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the year altered. If the resultingOffsetDateTime
is invalid, it will be resolved usingdateResolver
. 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.
- Parameters:
year
- the year to set in the returned date, from MIN_YEAR to MAX_YEARdateResolver
- the DateResolver to be used if the resulting date would be invalid- Returns:
- an
OffsetDateTime
based on this date-time with the requested year, never null - Throws:
IllegalCalendarFieldValueException
- if the year value is invalid
-
withMonthOfYear
public OffsetDateTime withMonthOfYear(int monthOfYear)
Returns a copy of thisOffsetDateTime
with the month-of-year altered. If the resultingOffsetDateTime
is invalid, it will be resolved usingDateResolvers.previousValid()
. The offset does not affect the calculation and will be the same in the result.This method does the same as
withMonthOfYear(monthOfYear, DateResolvers.previousValid())
.This instance is immutable and unaffected by this method call.
- Parameters:
monthOfYear
- the month-of-year to set in the returned date, from 1 (January) to 12 (December)- Returns:
- an
OffsetDateTime
based on this date-time with the requested month, never null - Throws:
IllegalCalendarFieldValueException
- if the month-of-year value is invalid
-
withMonthOfYear
public OffsetDateTime withMonthOfYear(int monthOfYear, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the month-of-year altered. If the resultingOffsetDateTime
is invalid, it will be resolved usingdateResolver
. 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.
- Parameters:
monthOfYear
- the month-of-year to set in the returned date, from 1 (January) to 12 (December)dateResolver
- the DateResolver to be used if the resulting date would be invalid- Returns:
- an
OffsetDateTime
based on this date-time with the requested month, never null - Throws:
IllegalCalendarFieldValueException
- if the month-of-year value is invalid
-
with
public OffsetDateTime with(MonthOfYear monthOfYear)
Returns a copy of thisOffsetDateTime
with the month-of-year altered. If the resultingOffsetDateTime
is invalid, it will be resolved usingDateResolvers.previousValid()
. The offset does not affect the calculation and will be the same in the result.This method does the same as
with(monthOfYear, DateResolvers.previousValid())
.This instance is immutable and unaffected by this method call.
- Parameters:
monthOfYear
- the month-of-year to set in the returned date, not null- Returns:
- an
OffsetDateTime
based on this date-time with the requested month, never null
-
with
public OffsetDateTime with(MonthOfYear monthOfYear, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the month-of-year altered. If the resultingOffsetDateTime
is invalid, it will be resolved usingdateResolver
. 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.
- Parameters:
monthOfYear
- the month-of-year to set in the returned date, not nulldateResolver
- the DateResolver to be used if the resulting date would be invalid- Returns:
- an
OffsetDateTime
based on this date-time with the requested month, never null
-
withDayOfMonth
public OffsetDateTime withDayOfMonth(int dayOfMonth)
Returns a copy of thisOffsetDateTime
with the day-of-month altered. If the resultingOffsetDateTime
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.
- Parameters:
dayOfMonth
- the day-of-month to set in the returned date, from 1 to 28-31- Returns:
- an
OffsetDateTime
based on this date-time with the requested day, never null - Throws:
IllegalCalendarFieldValueException
- if the day-of-month value is invalidInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
withDayOfMonth
public OffsetDateTime withDayOfMonth(int dayOfMonth, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the day-of-month altered. If the resultingOffsetDateTime
is invalid, it will be resolved usingdateResolver
. 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.
- Parameters:
dayOfMonth
- the day-of-month to set in the returned date, from 1 to 31dateResolver
- the DateResolver to be used if the resulting date would be invalid- Returns:
- an
OffsetDateTime
based on this date-time with the requested day, never null - Throws:
IllegalCalendarFieldValueException
- if the day-of-month value is invalid
-
withDayOfYear
public OffsetDateTime withDayOfYear(int dayOfYear)
Returns a copy of thisOffsetDateTime
with the day-of-year altered. If the resultingOffsetDateTime
is invalid, an exception is thrown.This instance is immutable and unaffected by this method call.
- Parameters:
dayOfYear
- the day-of-year to set in the returned date, from 1 to 365-366- Returns:
- an
OffsetDateTime
based on this date with the requested day, never null - Throws:
IllegalCalendarFieldValueException
- if the day-of-year value is invalidInvalidCalendarFieldException
- if the day-of-year is invalid for the year
-
withDate
public OffsetDateTime withDate(int year, MonthOfYear monthOfYear, int dayOfMonth)
Returns a copy of thisOffsetDateTime
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.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31- Returns:
- an
OffsetDateTime
based on this date-time with the requested date, never null - Throws:
IllegalCalendarFieldValueException
- if any field value is invalidInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
withDate
public OffsetDateTime withDate(int year, int monthOfYear, int dayOfMonth)
Returns a copy of thisOffsetDateTime
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.
- Parameters:
year
- the year to represent, from MIN_VALUE + 1 to MAX_VALUEmonthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31- Returns:
- an
OffsetDateTime
based on this date-time with the requested date, never null - Throws:
IllegalCalendarFieldValueException
- if any field value is invalidInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
withHourOfDay
public OffsetDateTime withHourOfDay(int hourOfDay)
Returns a copy of thisOffsetDateTime
with the hour-of-day value altered.This instance is immutable and unaffected by this method call.
- Parameters:
hourOfDay
- the hour-of-day to represent, from 0 to 23- Returns:
- an
OffsetDateTime
based on this date-time with the requested hour, never null - Throws:
IllegalCalendarFieldValueException
- if the hour value is invalid
-
withMinuteOfHour
public OffsetDateTime withMinuteOfHour(int minuteOfHour)
Returns a copy of thisOffsetDateTime
with the minute-of-hour value altered.This instance is immutable and unaffected by this method call.
- Parameters:
minuteOfHour
- the minute-of-hour to represent, from 0 to 59- Returns:
- an
OffsetDateTime
based on this date-time with the requested minute, never null - Throws:
IllegalCalendarFieldValueException
- if the minute value is invalid
-
withSecondOfMinute
public OffsetDateTime withSecondOfMinute(int secondOfMinute)
Returns a copy of thisOffsetDateTime
with the second-of-minute value altered.This instance is immutable and unaffected by this method call.
- Parameters:
secondOfMinute
- the second-of-minute to represent, from 0 to 59- Returns:
- an
OffsetDateTime
based on this date-time with the requested second, never null - Throws:
IllegalCalendarFieldValueException
- if the second value is invalid
-
withNanoOfSecond
public OffsetDateTime withNanoOfSecond(int nanoOfSecond)
Returns a copy of thisOffsetDateTime
with the nano-of-second value altered.This instance is immutable and unaffected by this method call.
- Parameters:
nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999- Returns:
- an
OffsetDateTime
based on this date-time with the requested nanosecond, never null - Throws:
IllegalCalendarFieldValueException
- if the nanos value is invalid
-
withTime
public OffsetDateTime withTime(int hourOfDay, int minuteOfHour)
Returns a copy of thisOffsetDateTime
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.
- Parameters:
hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59- Returns:
- an
OffsetDateTime
based on this date-time with the requested time, never null - Throws:
IllegalCalendarFieldValueException
- if any field value is invalid
-
withTime
public OffsetDateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute)
Returns a copy of thisOffsetDateTime
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.
- Parameters:
hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59secondOfMinute
- the second-of-minute to represent, from 0 to 59- Returns:
- an
OffsetDateTime
based on this date-time with the requested time, never null - Throws:
IllegalCalendarFieldValueException
- if any field value is invalid
-
withTime
public OffsetDateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond)
Returns a copy of this OffsetDateTime with the time values altered.This instance is immutable and unaffected by this method call.
- Parameters:
hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59secondOfMinute
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999- Returns:
- an
OffsetDateTime
based on this date-time with the requested time, never null - Throws:
IllegalCalendarFieldValueException
- if any field value is invalid
-
plus
public OffsetDateTime plus(PeriodProvider periodProvider)
Returns a copy of thisOffsetDateTime
with the specified period added.This adds the specified period to this date-time, returning a new date-time.
The detailed rules for the addition have some complexity due to variable length months. See
LocalDateTime.plus(PeriodProvider)
for details.This instance is immutable and unaffected by this method call.
- Parameters:
periodProvider
- the period to add, not null- Returns:
- an
OffsetDateTime
based on this date-time with the period added, never null - Throws:
CalendricalException
- if the specified period cannot be converted to aPeriod
CalendricalException
- if the result exceeds the supported date range
-
plus
public OffsetDateTime plus(Duration duration)
Returns a copy of thisOffsetDateTime
with the specified duration added.This adds the specified duration to this date-time, returning a new date-time.
The calculation is equivalent to using
plusSeconds(long)
andplusNanos(long)
on the two parts of the duration.This instance is immutable and unaffected by this method call.
- Parameters:
duration
- the duration to add, not null- Returns:
- an
OffsetDateTime
based on this date-time with the duration added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusYears
public OffsetDateTime plusYears(long years)
Returns a copy of thisOffsetDateTime
with the specified period in years added.This method adds the specified amount to the years field in three steps:
- Add the input years to the year field
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
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 method does the same as
plusYears(years, DateResolvers.previousValid())
.This instance is immutable and unaffected by this method call.
- Parameters:
years
- the years to add, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the years added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
plusYears(long, javax.time.calendar.DateResolver)
-
plusYears
public OffsetDateTime plusYears(long years, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the specified period in years added.This method adds the specified amount to the years field in three steps:
- Add the input years to the year field
- Check if the resulting date would be invalid
- Adjust the date using
dateResolver
if necessary
This instance is immutable and unaffected by this method call.
- Parameters:
years
- the years to add, may be negativedateResolver
- the DateResolver to be used if the resulting date would be invalid- Returns:
- an
OffsetDateTime
based on this date-time with the years added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusMonths
public OffsetDateTime plusMonths(long months)
Returns a copy of thisOffsetDateTime
with the specified period in months added.This method adds the specified amount to the months field in three steps:
- Add the input months to the month-of-year field
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
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 method does the same as
plusMonths(months, DateResolvers.previousValid())
.This instance is immutable and unaffected by this method call.
- Parameters:
months
- the months to add, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the months added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
plusMonths(long, javax.time.calendar.DateResolver)
-
plusMonths
public OffsetDateTime plusMonths(long months, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the specified period in months added.This method adds the specified amount to the months field in three steps:
- Add the input months to the month-of-year field
- Check if the resulting date would be invalid
- Adjust the date using
dateResolver
if necessary
This instance is immutable and unaffected by this method call.
- Parameters:
months
- the months to add, may be negativedateResolver
- the DateResolver to be used if the resulting date would be invalid- Returns:
- an
OffsetDateTime
based on this date-time with the months added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusWeeks
public OffsetDateTime plusWeeks(long weeks)
Returns a copy of this OffsetDateTime with the specified period in weeks added.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.
- Parameters:
weeks
- the weeks to add, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the weeks added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusDays
public OffsetDateTime plusDays(long days)
Returns a copy of this OffsetDateTime with the specified period in days added.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.
- Parameters:
days
- the days to add, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the days added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusHours
public OffsetDateTime plusHours(long hours)
Returns a copy of thisOffsetDateTime
with the specified period in hours added.This instance is immutable and unaffected by this method call.
- Parameters:
hours
- the hours to add, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the hours added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusMinutes
public OffsetDateTime plusMinutes(long minutes)
Returns a copy of thisOffsetDateTime
with the specified period in minutes added.This instance is immutable and unaffected by this method call.
- Parameters:
minutes
- the minutes to add, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the minutes added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusSeconds
public OffsetDateTime plusSeconds(long seconds)
Returns a copy of thisOffsetDateTime
with the specified period in seconds added.This instance is immutable and unaffected by this method call.
- Parameters:
seconds
- the seconds to add, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the seconds added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusNanos
public OffsetDateTime plusNanos(long nanos)
Returns a copy of thisOffsetDateTime
with the specified period in nanoseconds added.This instance is immutable and unaffected by this method call.
- Parameters:
nanos
- the nanos to add, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the nanoseconds added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minus
public OffsetDateTime minus(PeriodProvider periodProvider)
Returns a copy of thisOffsetDateTime
with the specified period subtracted.This subtracts the specified period from this date-time, returning a new date-time.
The detailed rules for the subtraction have some complexity due to variable length months. See
LocalDateTime.minus(PeriodProvider)
for details.This instance is immutable and unaffected by this method call.
- Parameters:
periodProvider
- the period to subtract, not null- Returns:
- an
OffsetDateTime
based on this date-time with the period subtracted, never null - Throws:
CalendricalException
- if the specified period cannot be converted to aPeriod
CalendricalException
- if the result exceeds the supported date range
-
minus
public OffsetDateTime minus(Duration duration)
Returns a copy of thisOffsetDateTime
with the specified duration subtracted.This subtracts the specified duration from this date-time, returning a new date-time.
The calculation is equivalent to using
minusSeconds(long)
andminusNanos(long)
on the two parts of the duration.This instance is immutable and unaffected by this method call.
- Parameters:
duration
- the duration to subtract, not null- Returns:
- an
OffsetDateTime
based on this date-time with the duration subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusYears
public OffsetDateTime minusYears(long years)
Returns a copy of thisOffsetDateTime
with the specified period in years subtracted.This method subtracts the specified amount from the years field in three steps:
- Subtract the input years to the year field
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
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 method does the same as
minusYears(years, DateResolvers.previousValid())
.This instance is immutable and unaffected by this method call.
- Parameters:
years
- the years to subtract, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the years subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
minusYears(long, javax.time.calendar.DateResolver)
-
minusYears
public OffsetDateTime minusYears(long years, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the specified period in years subtracted.This method subtracts the specified amount from the years field in three steps:
- Subtract the input years to the year field
- Check if the resulting date would be invalid
- Adjust the date using
dateResolver
if necessary
This instance is immutable and unaffected by this method call.
- Parameters:
years
- the years to subtract, may be negativedateResolver
- the DateResolver to be used if the resulting date would be invalid- Returns:
- an
OffsetDateTime
based on this date-time with the years subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusMonths
public OffsetDateTime minusMonths(long months)
Returns a copy of thisOffsetDateTime
with the specified period in months subtracted.This method subtracts the specified amount from the months field in three steps:
- Subtract the input months to the month-of-year field
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
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 method does the same as
minusMonts(months, DateResolvers.previousValid())
.This instance is immutable and unaffected by this method call.
- Parameters:
months
- the months to subtract, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the months subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
minusMonths(long, javax.time.calendar.DateResolver)
-
minusMonths
public OffsetDateTime minusMonths(long months, DateResolver dateResolver)
Returns a copy of thisOffsetDateTime
with the specified period in months subtracted.This method subtracts the specified amount from the months field in three steps:
- Subtract the input months to the month-of-year field
- Check if the resulting date would be invalid
- Adjust the date using
dateResolver
if necessary
This instance is immutable and unaffected by this method call.
- Parameters:
months
- the months to subtract, may be negativedateResolver
- the DateResolver to be used if the resulting date would be invalid- Returns:
- an
OffsetDateTime
based on this date-time with the months subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusWeeks
public OffsetDateTime minusWeeks(long weeks)
Returns a copy of thisOffsetDateTime
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.
- Parameters:
weeks
- the weeks to subtract, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the weeks subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusDays
public OffsetDateTime minusDays(long days)
Returns a copy of thisOffsetDateTime
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.
- Parameters:
days
- the days to subtract, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the days subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusHours
public OffsetDateTime minusHours(long hours)
Returns a copy of thisOffsetDateTime
with the specified period in hours subtracted.This instance is immutable and unaffected by this method call.
- Parameters:
hours
- the hours to subtract, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the hours subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusMinutes
public OffsetDateTime minusMinutes(long minutes)
Returns a copy of thisOffsetDateTime
with the specified period in minutes subtracted.This instance is immutable and unaffected by this method call.
- Parameters:
minutes
- the minutes to subtract, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the minutes subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusSeconds
public OffsetDateTime minusSeconds(long seconds)
Returns a copy of thisOffsetDateTime
with the specified period in seconds subtracted.This instance is immutable and unaffected by this method call.
- Parameters:
seconds
- the seconds to subtract, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the seconds subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusNanos
public OffsetDateTime minusNanos(long nanos)
Returns a copy of thisOffsetDateTime
with the specified period in nanoseconds subtracted.This instance is immutable and unaffected by this method call.
- Parameters:
nanos
- the nanos to subtract, may be negative- Returns:
- an
OffsetDateTime
based on this date-time with the nanoseconds subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
matches
public boolean matches(CalendricalMatcher matcher)
Checks whether thisOffsetDateTime
matches the specified matcher.Matchers can be used to query the date-time. A simple matcher might simply compare one of the fields, such as the year field. A more complex matcher might check if the date is the last day of the month.
- Parameters:
matcher
- the matcher to use, not null- Returns:
- true if this date-time matches the matcher, false otherwise
-
matchesCalendrical
public boolean matchesCalendrical(Calendrical calendrical)
Checks if the date-time extracted from the calendrical matches this.This method implements the
CalendricalMatcher
interface. It is intended that applications usematches(javax.time.calendar.CalendricalMatcher)
rather than this method.- Specified by:
matchesCalendrical
in interfaceCalendricalMatcher
- Parameters:
calendrical
- the calendrical to match, not null- Returns:
- true if the calendrical matches, false otherwise
-
adjustDate
public LocalDate adjustDate(LocalDate date)
Adjusts a date to have the value of the date part of this object.This method implements the
DateAdjuster
interface. It is intended that applications usewith(DateAdjuster)
rather than this method.- Specified by:
adjustDate
in interfaceDateAdjuster
- Parameters:
date
- the date to be adjusted, not null- Returns:
- the adjusted date, never null
-
adjustTime
public LocalTime adjustTime(LocalTime time)
Adjusts a time to have the value of the time part of this object.This method implements the
TimeAdjuster
interface. It is intended that applications usewith(TimeAdjuster)
rather than this method.- Specified by:
adjustTime
in interfaceTimeAdjuster
- Parameters:
time
- the time to be adjusted, not null- Returns:
- the adjusted time, never null
-
atZoneSameInstant
public ZonedDateTime atZoneSameInstant(TimeZone zone)
Returns a zoned date-time formed from the instant represented by this date-time and the specified time-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(TimeZone)
.This instance is immutable and unaffected by this method call.
- Parameters:
zone
- the time-zone to use, not null- Returns:
- the zoned date-time formed from this date-time, never null
-
atZoneSimilarLocal
public ZonedDateTime atZoneSimilarLocal(TimeZone zone)
Returns a zoned date-time formed from this date-time and the specified time-zone.Time-zone rules, such as daylight savings, mean that not every time on the local time-line exists. As a result, this method can only convert the date-time to the same time if the time-zone rules permit it. If not then a similar time is returned.
This method uses the
post transition
rules to determine what to do when a gap or overlap occurs. These rules select the date-time immediately after a gap and the later offset in overlaps.Finer control over gaps and overlaps is available in two ways. If you simply want to use the earlier offset at overlaps then call
ZonedDateTime.withEarlierOffsetAtOverlap()
immediately after this method. Alternately, pass a specific resolver toatZoneSimilarLocal(TimeZone, ZoneResolver)
.To create a zoned date-time at the same instant irrespective of the local time-line, use
atZoneSameInstant(TimeZone)
.This instance is immutable and unaffected by this method call.
- Parameters:
zone
- the time-zone to use, not null- Returns:
- the zoned date-time formed from this date and the earliest valid time for the zone, never null
-
atZoneSimilarLocal
public ZonedDateTime atZoneSimilarLocal(TimeZone 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.Time-zone rules, such as daylight savings, mean that not every time on the local time-line exists. As a result, this method can only convert the date-time to the same time if the time-zone rules permit it. If not then a similar time is returned.
This method uses the specified resolver to determine what to do when a gap or overlap occurs.
To create a zoned date-time at the same instant irrespective of the local time-line, use
atZoneSameInstant(TimeZone)
.This instance is immutable and unaffected by this method call.
- Parameters:
zone
- the time-zone to use, not nullresolver
- the zone resolver to use for gaps and overlaps, not null- Returns:
- the zoned date-time formed from this date and the earliest valid time for the zone, never null
- Throws:
CalendricalException
- if the date-time cannot be resolved
-
toInstant
public Instant toInstant()
Converts this date-time to anInstant
.- Specified by:
toInstant
in interfaceInstantProvider
- Returns:
- an Instant representing the same instant, never null
-
toLocalDate
public LocalDate toLocalDate()
Converts this date-time to aLocalDate
.- Specified by:
toLocalDate
in interfaceDateProvider
- Returns:
- a LocalDate representing the date fields of this date-time, never null
-
toLocalTime
public LocalTime toLocalTime()
Converts this date-time to aLocalTime
.- Specified by:
toLocalTime
in interfaceTimeProvider
- Returns:
- a LocalTime representing the time fields of this date-time, never null
-
toLocalDateTime
public LocalDateTime toLocalDateTime()
Converts this date-time to aLocalDateTime
.- Specified by:
toLocalDateTime
in interfaceDateTimeProvider
- Returns:
- a LocalDateTime representing the fields of this date-time, never null
-
toOffsetDate
public OffsetDate toOffsetDate()
Converts this date-time to anOffsetDate
.- Returns:
- an OffsetDate representing the date and offset, never null
-
toOffsetTime
public OffsetTime toOffsetTime()
Converts this date-time to anOffsetTime
.- Returns:
- an OffsetTime representing the time and offset, never null
-
toEpochSeconds
public long toEpochSeconds()
Converts this date-time to the number of seconds from the epoch of 1970-01-01T00:00:00Z.Instants on the time-line after the epoch are positive, earlier are negative.
- Returns:
- the number of seconds from the epoch of 1970-01-01T00:00:00Z
-
compareTo
public int compareTo(OffsetDateTime other)
Compares thisOffsetDateTime
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()
.- Specified by:
compareTo
in interfaceComparable<OffsetDateTime>
- Parameters:
other
- the other date-time to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
-
isAfter
public boolean isAfter(OffsetDateTime other)
Checks if the instant of thisOffsetDateTime
is after that of the specified date-time.This method differs from the comparison in
compareTo(javax.time.calendar.OffsetDateTime)
andequals(java.lang.Object)
in that it only compares the instant of the date-time. This is equivalent to usingdateTime1.toInstant().isAfter(dateTime2.toInstant());
.- Parameters:
other
- the other date-time to compare to, not null- Returns:
- true if this is after the instant of the specified date-time
-
isBefore
public boolean isBefore(OffsetDateTime other)
Checks if the instant of thisOffsetDateTime
is before that of the specified date-time.This method differs from the comparison in
compareTo(javax.time.calendar.OffsetDateTime)
in that it only compares the instant of the date-time. This is equivalent to usingdateTime1.toInstant().isBefore(dateTime2.toInstant());
.- Parameters:
other
- the other date-time to compare to, not null- Returns:
- true if this is before the instant of the specified date-time
-
equalInstant
public boolean equalInstant(OffsetDateTime other)
Checks if the instant of thisOffsetDateTime
is equal to that of the specified date-time.This method differs from the comparison in
compareTo(javax.time.calendar.OffsetDateTime)
andequals(java.lang.Object)
in that it only compares the instant of the date-time. This is equivalent to usingdateTime1.toInstant().equals(dateTime2.toInstant());
.- Parameters:
other
- the other date-time to compare to, not null- Returns:
- true if the instant equals the instant of the specified date-time
-
equals
public boolean equals(Object other)
Checks if thisOffsetDateTime
is equal to the specified date-time.This method returns true if the state of the two objects are equal. The state consists of the local date-time and the offset.
To compare for the same instant on the time-line, use
equalInstant(javax.time.calendar.OffsetDateTime)
.
-
hashCode
public int hashCode()
A hash code for thisOffsetDateTime
.
-
toString
public String toString()
Outputs this date-time as aString
, such as2007-12-03T10:15:30+01:00
.The output will be one of the following formats:
yyyy-MM-dd'T'HH:mmZZZZ
yyyy-MM-dd'T'HH:mm:ssZZZZ
yyyy-MM-dd'T'HH:mm:ssfnnnZZZZ
yyyy-MM-dd'T'HH:mm:ssfnnnnnnZZZZ
yyyy-MM-dd'T'HH:mm:ssfnnnnnnnnnZZZZ
-
toString
public String toString(DateTimeFormatter formatter)
Outputs this date-time as aString
using the formatter.- Parameters:
formatter
- the formatter to use, not null- Returns:
- the formatted date-time string, never null
- Throws:
UnsupportedOperationException
- if the formatter cannot printCalendricalPrintException
- if an error occurs during printing
-
rule
public static CalendricalRule<OffsetDateTime> rule()
Gets the rule forOffsetDateTime
.- Returns:
- the rule for the date-time, never null
-
-