Class LocalDate
- All Implemented Interfaces:
Serializable
,Comparable<LocalDate>
,Calendrical
,CalendricalMatcher
,DateAdjuster
,DateProvider
2007-12-03
.
LocalDate
is an immutable calendrical that represents a date, often viewed
as year-month-day. 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 or time-zone.
Thus, for example, the value "2nd October 2007" can be stored in a LocalDate
.
The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system, in which todays's rules for leap years are applied for all time. For most applications written today, the ISO-8601 rules are entirely suitable.
However, any application that makes use of historical dates and requires them
to be accurate will find the ISO-8601 rules unsuitable. In this case, the
application code should use HistoricDate
and define an explicit
cutover date between the Julian and Gregorian calendar systems.
LocalDate is immutable and thread-safe.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static final class
Rule implementation. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final int
The day-of-month.static final LocalDate
Constant for the maximum date on the proleptic ISO calendar system, +999999999-12-31.static final LocalDate
Constant for the minimum date on the proleptic ISO calendar system, -999999999-01-01.private final MonthOfYear
The month-of-year, not null.private static final long
A serialization identifier for this class.private final int
The year. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
LocalDate
(int year, MonthOfYear monthOfYear, int dayOfMonth) Constructor, previously validated. -
Method Summary
Modifier and TypeMethodDescriptionadjustDate
(LocalDate date) Adjusts a date to have the value of this date.Returns a local date-time formed from this date at the time of midnight.atOffset
(ZoneOffset offset) Returns an offset date formed from this time and the specified offset.atStartOfDayInZone
(TimeZone zone) Returns a zoned date-time from this date at the earliest valid time according to the rules in the time-zone.atTime
(int hourOfDay, int minuteOfHour) Returns a local date-time formed from this date at the specified time.atTime
(int hourOfDay, int minuteOfHour, int secondOfMinute) Returns a local date-time formed from this date at the specified time.atTime
(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond) Returns a local date-time formed from this date at the specified time.Returns a local date-time formed from this date at the specified time.atTime
(OffsetTime offsetTime) Returns a local date-time formed from this date at the specified offset time.int
Compares thisLocalDate
to another date.private static LocalDate
create
(int year, MonthOfYear monthOfYear, int dayOfMonth) Creates a local date from the year, month and day fields.boolean
Checks if thisLocalDate
is equal to the specified date.<T> T
get
(CalendricalRule<T> rule) Gets the value of the specified calendrical rule.Gets the chronology that this date uses, which is the ISO calendar system.int
Gets the day-of-month field.Gets the day-of-week field, which is an enumDayOfWeek
.int
Gets the day-of-year field.Gets the month-of-year field, which is an enumMonthOfYear
.int
getYear()
Gets the year field.int
hashCode()
A hash code for thisLocalDate
.boolean
Checks if thisLocalDate
is after the specified date.boolean
Checks if thisLocalDate
is before the specified date.boolean
Checks if the year is a leap year, according to the ISO proleptic calendar system rules.boolean
matches
(CalendricalMatcher matcher) Checks whether thisLocalDate
matches the specified matcher.boolean
matchesCalendrical
(Calendrical calendrical) Checks if the date extracted from the calendrical matches this date.minus
(PeriodProvider periodProvider) Returns a copy of thisLocalDate
with the specified date period subtracted.minusDays
(long days) Returns a copy of thisLocalDate
with the specified number of days subtracted.minusMonths
(long months) Returns a copy of thisLocalDate
with the specified period in months subtracted.minusMonths
(long months, DateResolver dateResolver) Returns a copy of thisLocalDate
with the specified period in months subtracted.minusWeeks
(long weeks) Returns a copy of thisLocalDate
with the specified period in weeks subtracted.minusYears
(long years) Returns a copy of thisLocalDate
with the specified period in years subtracted.minusYears
(long years, DateResolver dateResolver) Returns a copy of thisLocalDate
with the specified period in years subtracted.static LocalDate
now()
Obtains the current date from the system clock in the default time-zone.static LocalDate
Obtains the current date from the specified clock.static LocalDate
of
(int year, int monthOfYear, int dayOfMonth) Obtains an instance ofLocalDate
from a year, month and day.static LocalDate
of
(int year, MonthOfYear monthOfYear, int dayOfMonth) Obtains an instance ofLocalDate
from a year, month and day.static LocalDate
of
(DateProvider dateProvider) Obtains an instance ofLocalDate
from a date provider.static LocalDate
ofEpochDays
(long epochDays) Obtains an instance ofLocalDate
from the epoch days count.static LocalDate
ofModifiedJulianDays
(long mjDays) Obtains an instance ofLocalDate
from the Modified Julian Day (MJD).(package private) static LocalDate
ofYearZeroDays
(long epochDays) Converts a year zero day count to a date.static LocalDate
Obtains an instance ofLocalDate
from a text string such as2007-12-03
.static LocalDate
parse
(String text, DateTimeFormatter formatter) Obtains an instance ofLocalDate
from a text string using a specific formatter.plus
(PeriodProvider periodProvider) Returns a copy of thisLocalDate
with the specified date period added.plusDays
(long days) Returns a copy of thisLocalDate
with the specified number of days added.plusMonths
(long months) Returns a copy of thisLocalDate
with the specified period in months added.plusMonths
(long months, DateResolver dateResolver) Returns a copy of thisLocalDate
with the specified period in months added.plusWeeks
(long weeks) Returns a copy of thisLocalDate
with the specified period in weeks added.plusYears
(long years) Returns a copy of thisLocalDate
with the specified period in years added.plusYears
(long years, DateResolver dateResolver) Returns a copy of thisLocalDate
with the specified period in years added.private LocalDate
resolveDate
(DateResolver dateResolver, int year, MonthOfYear month, int day) Resolves the date, handling incorrectly implemented resolvers.static CalendricalRule<LocalDate>
rule()
Gets the rule forLocalDate
.long
Converts thisLocalDate
to Epoch Days.Converts this date to aLocalDate
, trivially returningthis
.long
Converts thisLocalDate
to Modified Julian Days (MJD).toString()
Outputs this date as aString
, such as2007-12-03
.toString
(DateTimeFormatter formatter) Outputs this date as aString
using the formatter.(package private) long
Converts thisLocalDate
to year zero days.with
(DateAdjuster adjuster) Returns a copy of thisLocalDate
with the date altered using the adjuster.with
(MonthOfYear monthOfYear) Returns a copy of thisLocalDate
with the month-of-year altered.with
(MonthOfYear monthOfYear, DateResolver dateResolver) Returns a copy of thisLocalDate
with the month-of-year altered.withDayOfMonth
(int dayOfMonth) Returns a copy of thisLocalDate
with the day-of-month altered.withDayOfMonth
(int dayOfMonth, DateResolver dateResolver) Returns a copy of thisLocalDate
with the day-of-month altered.withDayOfYear
(int dayOfYear) Returns a copy of thisLocalDate
with the day-of-year altered.withMonthOfYear
(int monthOfYear) Returns a copy of thisLocalDate
with the month-of-year altered.withMonthOfYear
(int monthOfYear, DateResolver dateResolver) Returns a copy of thisLocalDate
with the month-of-year altered.withYear
(int year) Returns a copy of thisLocalDate
with the year altered.withYear
(int year, DateResolver dateResolver) Returns a copy of thisLocalDate
with the year altered.
-
Field Details
-
MIN_DATE
Constant for the minimum date on the proleptic ISO calendar system, -999999999-01-01. This could be used by an application as a "far past" date. -
MAX_DATE
Constant for the maximum date on the proleptic ISO calendar system, +999999999-12-31. This could be used by an application as a "far future" date. -
serialVersionUID
private static final long serialVersionUIDA serialization identifier for this class.- See Also:
-
year
private final int yearThe year. -
month
The month-of-year, not null. -
day
private final int dayThe day-of-month.
-
-
Constructor Details
-
LocalDate
Constructor, previously validated.- 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, valid for year-month, from 1 to 31
-
-
Method Details
-
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.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
Obtains the current date from the specified clock.This will query the specified clock to obtain the current date - today. 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
Obtains an instance ofLocalDate
from a year, month and day.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 31- Returns:
- the local 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
Obtains an instance ofLocalDate
from a year, month and day.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 31- Returns:
- the local 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
Obtains an instance ofLocalDate
from a date provider.The purpose of this method is to convert a
DateProvider
to aLocalDate
in the safest possible way. Specifically, the means checking whether the input parameter is null and whether the result of the provider is null.- Parameters:
dateProvider
- the date provider to use, not null- Returns:
- the local date, never null
- Throws:
NullPointerException
- if the provider is null or returns null
-
ofEpochDays
Obtains an instance ofLocalDate
from the epoch days count.The Epoch Day count is a simple incrementing count of days where day 0 is 1970-01-01.
- Parameters:
epochDays
- the Epoch Day to convert, based on the epoch 1970-01-01- Returns:
- the local date, never null
- Throws:
IllegalCalendarFieldValueException
- if the epoch days exceeds the supported date range
-
ofModifiedJulianDays
Obtains an instance ofLocalDate
from the Modified Julian Day (MJD).The Modified Julian Day count is a simple incrementing count of days where day 0 is 1858-11-17.
- Parameters:
mjDays
- the Modified Julian Day to convert, based on the epoch 1858-11-17- Returns:
- the local date, never null
- Throws:
IllegalCalendarFieldValueException
- if the modified julian days value is outside the supported range
-
ofYearZeroDays
Converts a year zero day count to a date.The year zero day count is a simple incrementing count of days where day 0 is 0000-01-01.
- Parameters:
epochDays
- the Epoch Day to convert, based on the epoch 0000-01-01- Returns:
- the local date, never null
- Throws:
IllegalCalendarFieldValueException
- if the epoch days exceeds the supported date range
-
parse
Obtains an instance ofLocalDate
from a text string such as2007-12-03
.The following format is accepted in ASCII:
{Year}-{MonthOfYear}-{DayOfMonth}
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.
- Parameters:
text
- the text to parse such as '2007-12-03', not null- Returns:
- the parsed local date, never null
- Throws:
CalendricalException
- if the text cannot be parsed
-
parse
Obtains an instance ofLocalDate
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 local date, never null
- Throws:
UnsupportedOperationException
- if the formatter cannot parseCalendricalException
- if the text cannot be parsed
-
create
Creates a local date from the year, month and day fields.- Parameters:
year
- the year to represent, validated from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, validated not nulldayOfMonth
- the day-of-month to represent, validated from 1 to 31- Returns:
- the local date, never null
- Throws:
InvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
getChronology
Gets the chronology that this date uses, which is the ISO calendar system.- Returns:
- the ISO chronology, never null
-
get
Gets the value of the specified calendrical rule.This method queries the value of the specified calendrical rule. If the value cannot be returned for the rule from this 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
-
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
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
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
-
resolveDate
Resolves the date, handling incorrectly implemented resolvers.- Parameters:
dateResolver
- the resolver, not nullyear
- the year, from MIN_YEAR to MAX_YEARmonth
- the month, not nullday
- the day-of-month, from 1 to 31- Returns:
- the resolved date, never null
- Throws:
NullPointerException
- if the resolver returned null
-
with
Returns a copy of thisLocalDate
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.
This instance is immutable and unaffected by this method call.
- Parameters:
adjuster
- the adjuster to use, not null- Returns:
- a
LocalDate
based on this date adjusted as necessary, never null - Throws:
NullPointerException
- if the adjuster returned null
-
withYear
Returns a copy of thisLocalDate
with the year altered. If the resulting date is invalid, it will be resolved usingDateResolvers.previousValid()
.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:
- a
LocalDate
based on this date with the requested year, never null - Throws:
IllegalCalendarFieldValueException
- if the year value is invalid
-
withYear
Returns a copy of thisLocalDate
with the year altered. If the resulting date is invalid, it will be resolved usingdateResolver
.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:
- a
LocalDate
based on this date with the requested year, never null - Throws:
IllegalCalendarFieldValueException
- if the year value is invalid
-
withMonthOfYear
Returns a copy of thisLocalDate
with the month-of-year altered. If the resulting date is invalid, it will be resolved usingDateResolvers.previousValid()
.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:
- a
LocalDate
based on this date with the requested month, never null - Throws:
IllegalCalendarFieldValueException
- if the month-of-year value is invalid
-
withMonthOfYear
Returns a copy of thisLocalDate
with the month-of-year altered. If the resulting date is invalid, it will be resolved usingdateResolver
.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:
- a
LocalDate
based on this date with the requested month, never null - Throws:
IllegalCalendarFieldValueException
- if the month-of-year value is invalid
-
with
Returns a copy of thisLocalDate
with the month-of-year altered. If the resulting date is invalid, it will be resolved usingDateResolvers.previousValid()
.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:
- a
LocalDate
based on this date with the requested month, never null
-
with
Returns a copy of thisLocalDate
with the month-of-year altered. If the resulting date is invalid, it will be resolved usingdateResolver
.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:
- a
LocalDate
based on this date with the requested month, never null
-
withDayOfMonth
Returns a copy of thisLocalDate
with the day-of-month altered. If the resulting date is invalid, an exception is thrown.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:
- a
LocalDate
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
Returns a copy of thisLocalDate
with the day-of-month altered. If the resulting date is invalid, it will be resolved usingdateResolver
.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:
- a
LocalDate
based on this date with the requested day, never null - Throws:
IllegalCalendarFieldValueException
- if the day-of-month value is invalid
-
withDayOfYear
Returns a copy of thisLocalDate
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:
- a
LocalDate
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
Returns a copy of thisLocalDate
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. The goal is to match the code for
plusYears().plusMonths().plusDays()
in most cases. The principle case of difference is best expressed by example:2010-01-31
plusP1M-1M
yields2010-02-28
whereasplusMonths(1).plusDays(-1)
gives2010-02-27
.The rules are expressed in five steps:
- Add the input years and months to calculate the resulting year-month
- Form an imaginary date from the year-month and the original day-of-month, a date that may be invalid, such as February 30th
- Add the input days to the imaginary date treating the first move to a later date from an invalid date as a move to the 1st of the next month
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
For example, this table shows what happens when for various inputs and periods:
2010-01-30 plus P1M2D = 2010-03-02 2010-01-30 plus P1M1D = 2010-03-01 2010-01-30 plus P1M = 2010-02-28 2010-01-30 plus P1M-1D = 2010-02-28 2010-01-30 plus P1M-2D = 2010-02-28 2010-01-30 plus P1M-3D = 2010-02-27
This instance is immutable and unaffected by this method call.
- Parameters:
periodProvider
- the period to add, not null- Returns:
- a
LocalDate
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
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the years added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
-
plusYears
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the years added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusMonths
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the months added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
-
plusMonths
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the months added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusWeeks
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the weeks added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
plusDays
Returns a copy of thisLocalDate
with the specified number of 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:
- a
LocalDate
based on this date with the days added, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minus
Returns a copy of thisLocalDate
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. The goal is to match the code for
minusYears().minusMonths().minusDays()
in most cases. The principle case of difference is best expressed by example:2010-03-31
minusP1M1M
yields2010-02-28
whereasminusMonths(1).minusDays(1)
gives2010-02-27
.The rules are expressed in five steps:
- Subtract the input years and months to calculate the resulting year-month
- Form an imaginary date from the year-month and the original day-of-month, a date that may be invalid, such as February 30th
- Subtract the input days from the imaginary date treating the first move to a later date from an invalid date as a move to the 1st of the next month
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
For example, this table shows what happens when for various inputs and periods:
2010-03-30 minus P1M3D = 2010-02-27 2010-03-30 minus P1M2D = 2010-02-28 2010-03-30 minus P1M1D = 2010-02-28 2010-03-30 minus P1M = 2010-02-28 2010-03-30 minus P1M-1D = 2010-03-01 2010-03-30 minus P1M-2D = 2010-03-02
This instance is immutable and unaffected by this method call.
- Parameters:
periodProvider
- the period to subtract, not null- Returns:
- a
LocalDate
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
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the years subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
-
minusYears
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the years subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusMonths
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the months subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range- See Also:
-
minusMonths
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the months subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusWeeks
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the weeks subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
minusDays
Returns a copy of thisLocalDate
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:
- a
LocalDate
based on this date with the days subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported date range
-
matches
Checks whether thisLocalDate
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
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
Adjusts a date to have the value of this date.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
Returns a local date-time formed from this date at the specified offset 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:
offsetTime
- the offset time to use, not null- Returns:
- the offset date-time formed from this date and the specified time, never null
-
atTime
Returns a local date-time formed from this date at the specified time.This merges the two objects -
this
and the specified time - to form an instance ofLocalDateTime
.This instance is immutable and unaffected by this method call.
- Parameters:
localTime
- the local time to use, not null- Returns:
- the local date-time formed from this date and the specified time, never null
-
atTime
Returns a local date-time formed from this date at the specified time.This merges the three values -
this
and the specified time - to form an instance ofLocalDateTime
.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 local 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
Returns a local date-time formed from this date at the specified time.This merges the four values -
this
and the specified time - to form an instance ofLocalDateTime
.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 local 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
Returns a local date-time formed from this date at the specified time.This merges the five values -
this
and the specified time - to form an instance ofLocalDateTime
.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 local 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
Returns a local date-time formed from this date at the time of midnight.This merges the two objects -
this
andLocalTime.MIDNIGHT
- to form an instance ofLocalDateTime
.This instance is immutable and unaffected by this method call.
- Returns:
- the local date-time formed from this date and the time of midnight, never null
-
atOffset
Returns an offset date formed from this time and the specified offset.This merges the two objects -
this
and the specified offset - to form an instance ofOffsetDate
.This instance is immutable and unaffected by this method call.
- Parameters:
offset
- the offset to use, not null- Returns:
- the offset date formed from this date and the specified offset, never null
-
atStartOfDayInZone
Returns a zoned date-time from this date at the earliest valid time according to the rules in the time-zone.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 byLocalDateTime.atZone(TimeZone)
. Note that the resolver used byatZone()
is different to that used here (it chooses the later offset in an overlap, whereas this method chooses the earlier offset).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
-
toLocalDate
Converts this date to aLocalDate
, trivially returningthis
.- Specified by:
toLocalDate
in interfaceDateProvider
- Returns:
this
, never null
-
toEpochDays
public long toEpochDays()Converts thisLocalDate
to Epoch Days.The Epoch Day count is a simple incrementing count of days where day 0 is 1970-01-01.
- Returns:
- the Modified Julian Day equivalent to this date
-
toModifiedJulianDays
public long toModifiedJulianDays()Converts thisLocalDate
to Modified Julian Days (MJD).The Modified Julian Day count is a simple incrementing count of days where day 0 is 1858-11-17.
- Returns:
- the Modified Julian Day equivalent to this date
-
toYearZeroDays
long toYearZeroDays()Converts thisLocalDate
to year zero days.The year zero day count is a simple incrementing count of days where day 0 is 0000-01-01.
- Returns:
- the year zero days count equal to this date
-
compareTo
Compares thisLocalDate
to another date.The comparison is based on the time-line position of the dates.
- Specified by:
compareTo
in interfaceComparable<LocalDate>
- Parameters:
other
- the other date to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
-
isAfter
Checks if thisLocalDate
is after the specified date.The comparison is based on the time-line position of the dates.
- Parameters:
other
- the other date to compare to, not null- Returns:
- true if this is after the specified date
-
isBefore
Checks if thisLocalDate
is before the specified date.The comparison is based on the time-line position of the dates.
- Parameters:
other
- the other date to compare to, not null- Returns:
- true if this is before the specified date
-
equals
Checks if thisLocalDate
is equal to the specified date.The comparison is based on the time-line position of the dates.
-
hashCode
public int hashCode()A hash code for thisLocalDate
. -
toString
Outputs this date as aString
, such as2007-12-03
.The output will be in the format
yyyy-MM-dd
. -
toString
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
Gets the rule forLocalDate
.- Returns:
- the rule for the date, never null
-