Class OffsetDate
- java.lang.Object
-
- javax.time.calendar.OffsetDate
-
- All Implemented Interfaces:
Serializable
,Comparable<OffsetDate>
,Calendrical
,CalendricalMatcher
,DateAdjuster
,DateProvider
public final class OffsetDate extends Object implements Calendrical, DateProvider, CalendricalMatcher, DateAdjuster, Comparable<OffsetDate>, Serializable
A date with a zone offset from UTC in the ISO-8601 calendar system, such as2007-12-03+01:00
.OffsetDate
is an immutable calendrical that represents a date, often viewed as year-month-day-offset. This object can also access other date fields such as day-of-year, day-of-week and week-of-year.This class does not store or represent a time. Thus, for example, the value "2nd October 2007 +02:00" can be stored in a
OffsetDate
.OffsetDate 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.OffsetDateTime
atMidnight()
Returns an offset date-time formed from this date at the time of midnight.ZonedDateTime
atStartOfDayInZone(TimeZone zone)
Returns a zoned date-time from this date at the earliest valid time according to the rules in the time-zone ignoring the current offset.OffsetDateTime
atTime(int hourOfDay, int minuteOfHour)
Returns an offset date-time formed from this date at the specified time.OffsetDateTime
atTime(int hourOfDay, int minuteOfHour, int secondOfMinute)
Returns an offset date-time formed from this date at the specified time.OffsetDateTime
atTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond)
Returns an offset date-time formed from this date at the specified time.OffsetDateTime
atTime(LocalTime time)
Returns an offset date-time formed from this date at the specified time.OffsetDateTime
atTime(OffsetTime time)
Returns an offset date-time formed from this date at the specified time.int
compareTo(OffsetDate other)
Compares thisOffsetDate
to another date based on the UTC equivalent dates then local date.boolean
equalInstant(OffsetDate other)
Checks if the instant of midnight at the start of thisOffsetDate
equals midnight at the start of the specified date.boolean
equals(Object other)
Checks if thisOffsetDate
is equal to the specified date.<T> T
get(CalendricalRule<T> rule)
Gets the value of the specified calendrical rule.ISOChronology
getChronology()
Gets the chronology that this date 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.MonthOfYear
getMonthOfYear()
Gets the month-of-year field, which is an enumMonthOfYear
.ZoneOffset
getOffset()
Gets the zone offset.int
getYear()
Gets the year field.int
hashCode()
A hash code for thisOffsetDate
.boolean
isAfter(OffsetDate other)
Checks if the instant of midnight at the start of thisOffsetDate
is after midnight at the start of the specified date.boolean
isBefore(OffsetDate other)
Checks if the instant of midnight at the start of thisOffsetDate
is before midnight at the start of the specified date.boolean
isLeapYear()
Checks if the year is a leap year, according to the ISO proleptic calendar system rules.boolean
matches(CalendricalMatcher matcher)
Checks whether thisOffsetDate
matches the specified matcher.boolean
matchesCalendrical(Calendrical calendrical)
Checks if the date extracted from the calendrical matches this date.OffsetDate
minus(PeriodProvider periodProvider)
Returns a copy of thisOffsetDate
with the specified date period subtracted.OffsetDate
minusDays(long days)
Returns a copy of thisOffsetDate
with the specified number of days subtracted.OffsetDate
minusMonths(long months)
Returns a copy of thisOffsetDate
with the specified period in months subtracted.OffsetDate
minusMonths(long months, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the specified period in months subtracted.OffsetDate
minusWeeks(long weeks)
Returns a copy of thisOffsetDate
with the specified period in weeks subtracted.OffsetDate
minusYears(long years)
Returns a copy of thisOffsetDate
with the specified period in years subtracted.OffsetDate
minusYears(long years, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the specified period in years subtracted.static OffsetDate
now()
Obtains the current date from the system clock in the default time-zone.static OffsetDate
now(Clock clock)
Obtains the current date from the specified clock.static OffsetDate
of(int year, int monthOfYear, int dayOfMonth, ZoneOffset offset)
Obtains an instance ofOffsetDate
from a year, month and day.static OffsetDate
of(int year, MonthOfYear monthOfYear, int dayOfMonth, ZoneOffset offset)
Obtains an instance ofOffsetDate
from a year, month and day.static OffsetDate
of(DateProvider dateProvider, ZoneOffset offset)
Obtains an instance ofOffsetDate
from a date provider.static OffsetDate
ofInstant(InstantProvider instantProvider, ZoneOffset offset)
Obtains an instance ofOffsetDate
from anInstantProvider
.static OffsetDate
parse(String text)
Obtains an instance ofOffsetDate
from a text string such as2007-12-03+01:00
.static OffsetDate
parse(String text, DateTimeFormatter formatter)
Obtains an instance ofOffsetDate
from a text string using a specific formatter.OffsetDate
plus(PeriodProvider periodProvider)
Returns a copy of thisOffsetDate
with the specified date period added.OffsetDate
plusDays(long days)
Returns a copy of thisOffsetDate
with the specified period in days added.OffsetDate
plusMonths(long months)
Returns a copy of thisOffsetDate
with the specified period in months added.OffsetDate
plusMonths(long months, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the specified period in months added.OffsetDate
plusWeeks(long weeks)
Returns a copy of thisOffsetDate
with the specified period in weeks added.OffsetDate
plusYears(long years)
Returns a copy of thisOffsetDate
with the specified period in years added.OffsetDate
plusYears(long years, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the specified period in years added.static CalendricalRule<OffsetDate>
rule()
Gets the rule forOffsetDate
.Instant
toInstant()
Converts this date to anInstant
at midnight.LocalDate
toLocalDate()
Converts this date to aLocalDate
.String
toString()
Outputs this date as aString
, such as2007-12-03+01:00
.String
toString(DateTimeFormatter formatter)
Outputs this date as aString
using the formatter.OffsetDate
with(DateAdjuster adjuster)
Returns a copy of thisOffsetDate
with the date altered using the adjuster.OffsetDate
with(MonthOfYear monthOfYear)
Returns a copy of thisOffsetDate
with the month-of-year altered.OffsetDate
with(MonthOfYear monthOfYear, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the month-of-year altered.OffsetDate
withDate(DateProvider dateProvider)
Returns a copy of thisOffsetDate
with a different local date.OffsetDate
withDayOfMonth(int dayOfMonth)
Returns a copy of thisOffsetDate
with the day-of-month altered.OffsetDate
withDayOfMonth(int dayOfMonth, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the day-of-month altered.OffsetDate
withDayOfYear(int dayOfYear)
Returns a copy of thisOffsetDate
with the day-of-year altered.OffsetDate
withMonthOfYear(int monthOfYear)
Returns a copy of thisOffsetDate
with the month-of-year altered.OffsetDate
withMonthOfYear(int monthOfYear, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the month-of-year altered.OffsetDate
withOffset(ZoneOffset offset)
Returns a copy of thisOffsetDate
with the specified offset.OffsetDate
withYear(int year)
Returns a copy of thisOffsetDate
with the year altered.OffsetDate
withYear(int year, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the year altered.
-
-
-
Method Detail
-
now
public static OffsetDate now()
Obtains the current date 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. 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 using the system clock, never null
-
now
public static OffsetDate now(Clock clock)
Obtains the current date from the specified clock.This will query the specified clock to obtain the current date - today. 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, never null
-
of
public static OffsetDate of(int year, MonthOfYear monthOfYear, int dayOfMonth, ZoneOffset offset)
Obtains an instance ofOffsetDate
from a year, month and day.- 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, 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 OffsetDate of(int year, int monthOfYear, int dayOfMonth, ZoneOffset offset)
Obtains an instance ofOffsetDate
from a year, month and day.- 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, 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 OffsetDate of(DateProvider dateProvider, ZoneOffset offset)
Obtains an instance ofOffsetDate
from a date provider.- Parameters:
dateProvider
- the date provider to use, not nulloffset
- the zone offset, not null- Returns:
- the offset date, never null
-
ofInstant
public static OffsetDate ofInstant(InstantProvider instantProvider, ZoneOffset offset)
Obtains an instance ofOffsetDate
from anInstantProvider
.This conversion drops the time component of the instant effectively converting at midnight at the start of the day.
- Parameters:
instantProvider
- the instant to convert, not nulloffset
- the zone offset, not null- Returns:
- the offset date, never null
- Throws:
CalendarConversionException
- if the instant exceeds the supported date range
-
parse
public static OffsetDate parse(String text)
Obtains an instance ofOffsetDate
from a text string such as2007-12-03+01:00
.The following format is accepted in ASCII:
{Year}-{MonthOfYear}-{DayOfMonth}{OffsetID}
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 offset ID is the normalized form as defined in
ZoneOffset
.- Parameters:
text
- the text to parse such as '2007-12-03+01:00', not null- Returns:
- the parsed offset date, never null
- Throws:
CalendricalException
- if the text cannot be parsed
-
parse
public static OffsetDate parse(String text, DateTimeFormatter formatter)
Obtains an instance ofOffsetDate
from a text string using a specific formatter.The text is parsed using the formatter, returning a date.
- Parameters:
text
- the text to parse, not nullformatter
- the formatter to use, not null- Returns:
- the parsed offset date, 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 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 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
-
getOffset
public ZoneOffset getOffset()
Gets the zone offset.- Returns:
- the zone offset, never null
-
withOffset
public OffsetDate withOffset(ZoneOffset offset)
Returns a copy of thisOffsetDate
with the specified offset.This method returns an object with the same
LocalDate
and the specifiedZoneOffset
. No calculation is needed or performed. For example, if this time represents2007-12-03+02:00
and the offset specified is+03:00
, then this method will return2007-12-03+03:00
.This instance is immutable and unaffected by this method call.
- Parameters:
offset
- the zone offset to change to, not null- Returns:
- an
OffsetDate
based on this date with the requested offset, never null
-
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
-
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 OffsetDate with(DateAdjuster adjuster)
Returns a copy of thisOffsetDate
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 does 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
OffsetDate
based on this date adjusted as necessary, never null - Throws:
NullPointerException
- if the adjuster returned null
-
withDate
public OffsetDate withDate(DateProvider dateProvider)
Returns a copy of thisOffsetDate
with a different local date.This method changes the date stored to a different date. No calculation is performed. The result simply represents the same offset and the new date.
- Parameters:
dateProvider
- the local date to change to, not null- Returns:
- an
OffsetDate
based on this date with the requested date, never null
-
withYear
public OffsetDate withYear(int year)
Returns a copy of thisOffsetDate
with the year altered. If the resulting date 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
OffsetDate
based on this date with the requested year, never null - Throws:
IllegalCalendarFieldValueException
- if the year value is invalid
-
withYear
public OffsetDate withYear(int year, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the year altered. If the resulting date 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
OffsetDate
based on this date with the requested year, never null - Throws:
IllegalCalendarFieldValueException
- if the year value is invalid
-
withMonthOfYear
public OffsetDate withMonthOfYear(int monthOfYear)
Returns a copy of thisOffsetDate
with the month-of-year altered. If the resulting date 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
OffsetDate
based on this date with the requested month, never null - Throws:
IllegalCalendarFieldValueException
- if the month-of-year value is invalid
-
withMonthOfYear
public OffsetDate withMonthOfYear(int monthOfYear, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the month-of-year altered. If the resulting date 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
OffsetDate
based on this date with the requested month, never null - Throws:
IllegalCalendarFieldValueException
- if the month-of-year value is invalid
-
with
public OffsetDate with(MonthOfYear monthOfYear)
Returns a copy of thisOffsetDate
with the month-of-year altered. If the resulting date 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
OffsetDate
based on this date with the requested month, never null
-
with
public OffsetDate with(MonthOfYear monthOfYear, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the month-of-year altered. If the resulting date 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
OffsetDate
based on this date with the requested month, never null
-
withDayOfMonth
public OffsetDate withDayOfMonth(int dayOfMonth)
Returns a copy of thisOffsetDate
with the day-of-month altered. If the resulting date 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
OffsetDate
based on this date 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 OffsetDate withDayOfMonth(int dayOfMonth, DateResolver dateResolver)
Returns a copy of thisOffsetDate
with the day-of-month altered. If the resulting date 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
OffsetDate
based on this date with the requested day, never null - Throws:
IllegalCalendarFieldValueException
- if the day-of-month value is invalid
-
withDayOfYear
public OffsetDate withDayOfYear(int dayOfYear)
Returns a copy of thisOffsetDate
with the day-of-year altered. If the resulting date 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
OffsetDate
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
-
plus
public OffsetDate plus(PeriodProvider periodProvider)
Returns a copy of thisOffsetDate
with the specified date period added.This adds the specified period to this date, returning a new date. Before addition, the period is converted to a date-based
Period
usingPeriod.ofDateFields(PeriodProvider)
. That factory ignores any time-based ISO fields, thus adding a time-based period to this date will have no effect. If you want to take time fields into account, callPeriod.normalizedWith24HourDays()
on the input period.The detailed rules for the addition have some complexity due to variable length months. See
LocalDate.plus(PeriodProvider)
for details.This instance is immutable and unaffected by this method call.
- Parameters:
periodProvider
- the period to add, not null- Returns:
- an
OffsetDate
based on this date 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
-
plusYears
public OffsetDate plusYears(long years)
Returns a copy of thisOffsetDate
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
OffsetDate
based on this date with the years added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
#plusYears(int, javax.time.calendar.DateResolver)
-
plusYears
public OffsetDate plusYears(long years, DateResolver dateResolver)
Returns a copy of thisOffsetDate
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
OffsetDate
based on this date with the years added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusMonths
public OffsetDate plusMonths(long months)
Returns a copy of thisOffsetDate
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
OffsetDate
based on this date with the months added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
#plusMonths(int, javax.time.calendar.DateResolver)
-
plusMonths
public OffsetDate plusMonths(long months, DateResolver dateResolver)
Returns a copy of thisOffsetDate
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
OffsetDate
based on this date with the months added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusWeeks
public OffsetDate plusWeeks(long weeks)
Returns a copy of thisOffsetDate
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 2009-01-07.
This instance is immutable and unaffected by this method call.
- Parameters:
weeks
- the weeks to add, may be negative- Returns:
- an
OffsetDate
based on this date with the weeks added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusDays
public OffsetDate plusDays(long days)
Returns a copy of thisOffsetDate
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 2009-01-01.
This instance is immutable and unaffected by this method call.
- Parameters:
days
- the days to add, may be negative- Returns:
- an
OffsetDate
based on this date with the days added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minus
public OffsetDate minus(PeriodProvider periodProvider)
Returns a copy of thisOffsetDate
with the specified date period subtracted.This subtracts the specified period from this date, returning a new date. Before subtraction, the period is converted to a date-based
Period
usingPeriod.ofDateFields(PeriodProvider)
. That factory ignores any time-based ISO fields, thus subtracting a time-based period from this date will have no effect. If you want to take time fields into account, callPeriod.normalizedWith24HourDays()
on the input period.The detailed rules for the subtraction have some complexity due to variable length months. See
LocalDate.minus(PeriodProvider)
for details.This instance is immutable and unaffected by this method call.
- Parameters:
periodProvider
- the period to subtract, not null- Returns:
- an
OffsetDate
based on this date 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
-
minusYears
public OffsetDate minusYears(long years)
Returns a copy of thisOffsetDate
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 2007-02-29 (standard year). Instead of returning an invalid result, the last valid day of the month, 2007-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
OffsetDate
based on this date with the years subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
#minusYears(int, javax.time.calendar.DateResolver)
-
minusYears
public OffsetDate minusYears(long years, DateResolver dateResolver)
Returns a copy of thisOffsetDate
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
OffsetDate
based on this date with the years subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusMonths
public OffsetDate minusMonths(long months)
Returns a copy of thisOffsetDate
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-02-31. Instead of returning an invalid result, the last valid day of the month, 2007-02-28, is selected instead.
This method does the same as
minusMonths(months, DateResolvers.previousValid())
.This instance is immutable and unaffected by this method call.
- Parameters:
months
- the months to subtract, may be negative- Returns:
- an
OffsetDate
based on this date with the months subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
#minusMonths(int, javax.time.calendar.DateResolver)
-
minusMonths
public OffsetDate minusMonths(long months, DateResolver dateResolver)
Returns a copy of thisOffsetDate
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
OffsetDate
based on this date with the months subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusWeeks
public OffsetDate minusWeeks(long weeks)
Returns a copy of thisOffsetDate
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, 2009-01-07 minus one week would result in 2008-12-31.
This instance is immutable and unaffected by this method call.
- Parameters:
weeks
- the weeks to subtract, may be negative- Returns:
- an
OffsetDate
based on this date with the weeks subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusDays
public OffsetDate minusDays(long days)
Returns a copy of thisOffsetDate
with the specified number of days subtracted.This method subtracts the specified amount 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, 2009-01-01 minus one day would result in 2008-12-31.
This instance is immutable and unaffected by this method call.
- Parameters:
days
- the days to subtract, may be negative- Returns:
- an
OffsetDate
based on this date with the days subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
matches
public boolean matches(CalendricalMatcher matcher)
Checks whether thisOffsetDate
matches the specified matcher.Matchers can be used to query the date. 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 matches the matcher, false otherwise
-
matchesCalendrical
public boolean matchesCalendrical(Calendrical calendrical)
Checks if the date extracted from the calendrical matches this date.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
-
atTime
public OffsetDateTime atTime(OffsetTime time)
Returns an offset date-time formed from this date at the specified time.This merges the two objects -
this
and the specified time - to form an instance ofOffsetDateTime
. If the offset of the time differs from the offset of the date, then the result will have the offset of the date and the time will be adjusted to match.This instance is immutable and unaffected by this method call.
- Parameters:
time
- the time to use, not null- Returns:
- the offset date-time formed from this date and the specified time, never null
-
atTime
public OffsetDateTime atTime(LocalTime time)
Returns an offset date-time formed from this date at the specified time.This merges the two objects -
this
and the specified time - to form an instance ofOffsetDateTime
.This instance is immutable and unaffected by this method call.
- Parameters:
time
- the time to use, not null- Returns:
- the offset date-time formed from this date and the specified time, never null
-
atTime
public OffsetDateTime atTime(int hourOfDay, int minuteOfHour)
Returns an offset date-time formed from this date at the specified time.This merges the three values -
this
and the specified time - to form an instance ofOffsetDateTime
.This instance is immutable and unaffected by this method call.
- Parameters:
hourOfDay
- the hour-of-day to use, from 0 to 23minuteOfHour
- the minute-of-hour to use, from 0 to 59- Returns:
- the offset date-time formed from this date and the specified time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of range
-
atTime
public OffsetDateTime atTime(int hourOfDay, int minuteOfHour, int secondOfMinute)
Returns an offset date-time formed from this date at the specified time.This merges the four values -
this
and the specified time - to form an instance ofOffsetDateTime
.This instance is immutable and unaffected by this method call.
- Parameters:
hourOfDay
- the hour-of-day to use, from 0 to 23minuteOfHour
- the minute-of-hour to use, from 0 to 59secondOfMinute
- the second-of-minute to represent, from 0 to 59- Returns:
- the offset date-time formed from this date and the specified time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of range
-
atTime
public OffsetDateTime atTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond)
Returns an offset date-time formed from this date at the specified time.This merges the five values -
this
and the specified time - to form an instance ofOffsetDateTime
.This instance is immutable and unaffected by this method call.
- Parameters:
hourOfDay
- the hour-of-day to use, from 0 to 23minuteOfHour
- the minute-of-hour to use, 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:
- the offset date-time formed from this date and the specified time, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of range
-
atMidnight
public OffsetDateTime atMidnight()
Returns an offset date-time formed from this date at the time of midnight.This merges the two objects -
this
andLocalTime.MIDNIGHT
- to form an instance ofOffsetDateTime
.This instance is immutable and unaffected by this method call.
- Returns:
- the offset date-time formed from this date and the time of midnight, never null
-
atStartOfDayInZone
public ZonedDateTime atStartOfDayInZone(TimeZone zone)
Returns a zoned date-time from this date at the earliest valid time according to the rules in the time-zone ignoring the current offset.Time-zone rules, such as daylight savings, mean that not every time on the local time-line exists. When this method converts the date to a date-time it adjusts the time and offset as necessary to ensure that the time is as early as possible on the date, which is typically midnight. Internally this is achieved using the
zone resolver
.To convert to a specific time in a given time-zone call
atTime(LocalTime)
followed byOffsetDateTime.atZoneSimilarLocal(TimeZone)
. Note that the resolver used byatZoneSimilarLocal()
is different to that used here (it chooses the later offset in an overlap, whereas this method chooses the earlier offset).The offset from this date is ignored during the conversion. This ensures that the resultant date-time has the same date as this.
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
-
toInstant
public Instant toInstant()
Converts this date to anInstant
at midnight.This conversion treats the time component as midnight at the start of the day.
- Returns:
- an instant equivalent to midnight at the start of this day, never null
-
toLocalDate
public LocalDate toLocalDate()
Converts this date to aLocalDate
.- Specified by:
toLocalDate
in interfaceDateProvider
- Returns:
- a local date with the same date as this instance, never null
-
compareTo
public int compareTo(OffsetDate other)
Compares thisOffsetDate
to another date based on the UTC equivalent dates then local date.This ordering is consistent with
equals()
. For example, the following is the comparator order:- 2008-06-29-11:00
- 2008-06-29-12:00
- 2008-06-30+12:00
- 2008-06-29-13:00
equals()
.- Specified by:
compareTo
in interfaceComparable<OffsetDate>
- Parameters:
other
- the other date to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
-
isAfter
public boolean isAfter(OffsetDate other)
Checks if the instant of midnight at the start of thisOffsetDate
is after midnight at the start of the specified date.This method differs from the comparison in
compareTo(javax.time.calendar.OffsetDate)
in that it only compares the instant of the date. This is equivalent to usingdate1.toInstant().isAfter(date2.toInstant());
.- Parameters:
other
- the other date to compare to, not null- Returns:
- true if this is after the instant of the specified date
-
isBefore
public boolean isBefore(OffsetDate other)
Checks if the instant of midnight at the start of thisOffsetDate
is before midnight at the start of the specified date.This method differs from the comparison in
compareTo(javax.time.calendar.OffsetDate)
in that it only compares the instant of the date. This is equivalent to usingdate1.toInstant().isBefore(date2.toInstant());
.- Parameters:
other
- the other date to compare to, not null- Returns:
- true if this is before the instant of the specified date
-
equalInstant
public boolean equalInstant(OffsetDate other)
Checks if the instant of midnight at the start of thisOffsetDate
equals midnight at the start of the specified date.This method differs from the comparison in
compareTo(javax.time.calendar.OffsetDate)
andequals(java.lang.Object)
in that it only compares the instant of the date. This is equivalent to usingdate1.toInstant().equals(date2.toInstant());
.- Parameters:
other
- the other date to compare to, not null- Returns:
- true if the instant equals the instant of the specified date
-
equals
public boolean equals(Object other)
Checks if thisOffsetDate
is equal to the specified date.This method returns true if the state of the two objects are equal. The state consists of the local date and the offset.
To compare for the same instant on the time-line, use
equalInstant(javax.time.calendar.OffsetDate)
.
-
hashCode
public int hashCode()
A hash code for thisOffsetDate
.
-
toString
public String toString()
Outputs this date as aString
, such as2007-12-03+01:00
.The output will be in the format
yyyy-MM-ddZZZZ
.
-
toString
public String toString(DateTimeFormatter formatter)
Outputs this date as aString
using the formatter.- Parameters:
formatter
- the formatter to use, not null- Returns:
- the formatted date string, never null
- Throws:
UnsupportedOperationException
- if the formatter cannot printCalendricalPrintException
- if an error occurs during printing
-
rule
public static CalendricalRule<OffsetDate> rule()
Gets the rule forOffsetDate
.- Returns:
- the rule for the date, never null
-
-