LocalDate (ThreeTen date and time API)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.time.calendar
Class LocalDate

java.lang.Object
  javax.time.calendar.LocalDate

All Implemented Interfaces:: java.io.Serializable, java.lang.Comparable<LocalDate>, Calendrical, CalendricalMatcher, DateAdjuster

public final class LocalDate
extends java.lang.Object
implements Calendrical, CalendricalMatcher, DateAdjuster, java.lang.Comparable<LocalDate>, java.io.Serializable
extends java.lang.Object
implements Calendrical, CalendricalMatcher, DateAdjuster, java.lang.Comparable<LocalDate>, java.io.Serializable

A date without a time-zone in the ISO-8601 calendar system, such as 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. 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.

Author:: Michael Nascimento Santos, Stephen Colebourne
See Also:: Serialized Form

Field Summary
`static LocalDate`	`MAX_DATE` Constant for the maximum date on the proleptic ISO calendar system, +999999999-12-31.
`static LocalDate`	`MIN_DATE` Constant for the minimum date on the proleptic ISO calendar system, -999999999-01-01.

Method Summary

LocalDate adjustDate(LocalDate date)
Adjusts a date to have the value of this date.

LocalDateTime atMidnight()
Returns a local date-time formed from this date at the time of midnight.

OffsetDate atOffset(ZoneOffset offset)
Returns an offset date formed from this time and the specified offset.

ZonedDateTime atStartOfDayInZone(ZoneId zone)
Returns a zoned date-time from this date at the earliest valid time according to the rules in the time-zone.

LocalDateTime atTime(int hourOfDay, int minuteOfHour)
Returns a local date-time formed from this date at the specified time.

LocalDateTime atTime(int hourOfDay, int minuteOfHour, int secondOfMinute)
Returns a local date-time formed from this date at the specified time.

LocalDateTime atTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond)
Returns a local date-time formed from this date at the specified time.

LocalDateTime atTime(LocalTime localTime)
Returns a local date-time formed from this date at the specified time.

OffsetDateTime atTime(OffsetTime offsetTime)
Returns a local date-time formed from this date at the specified offset time.

int compareTo(LocalDate other)
Compares this LocalDate to another date.

boolean equals(java.lang.Object obj)
Checks if this date is equal to another date.

static LocalDate from(Calendrical... calendricals)
Obtains an instance of LocalDate from a set of calendricals.





<T> T

get(CalendricalRule<T> ruleToDerive)
Gets the value of the specified calendrical rule.

int getDayOfMonth()
Gets the day-of-month field.

DayOfWeek getDayOfWeek()
Gets the day-of-week field, which is an enum DayOfWeek.

int getDayOfYear()
Gets the day-of-year field.

MonthOfYear getMonthOfYear()
Gets the month-of-year field, which is an enum MonthOfYear.

int getYear()
Gets the year field.

int hashCode()
A hash code for this date.

boolean isAfter(LocalDate other)
Checks if this LocalDate is after the specified date.

boolean isBefore(LocalDate other)
Checks if this LocalDate is before 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 this LocalDate matches the specified matcher.

boolean matchesCalendrical(Calendrical calendrical)
Checks if the date extracted from the calendrical matches this date.

LocalDate minus(PeriodProvider periodProvider)
Returns a copy of this LocalDate with the specified date period subtracted.

LocalDate minusDays(long days)
Returns a copy of this LocalDate with the specified number of days subtracted.

LocalDate minusMonths(long months)
Returns a copy of this LocalDate with the specified period in months subtracted.

LocalDate minusMonths(long months, DateResolver dateResolver)
Returns a copy of this LocalDate with the specified period in months subtracted.

LocalDate minusWeeks(long weeks)
Returns a copy of this LocalDate with the specified period in weeks subtracted.

LocalDate minusYears(long years)
Returns a copy of this LocalDate with the specified period in years subtracted.

LocalDate minusYears(long years, DateResolver dateResolver)
Returns a copy of this LocalDate 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 now(Clock clock)
Obtains the current date from the specified clock.

static LocalDate of(int year, int monthOfYear, int dayOfMonth)
Obtains an instance of LocalDate from a year, month and day.

static LocalDate of(int year, MonthOfYear monthOfYear, int dayOfMonth)
Obtains an instance of LocalDate from a year, month and day.

static LocalDate ofEpochDay(long epochDay)
Obtains an instance of LocalDate from the epoch day count.

static LocalDate ofModifiedJulianDay(long mjDay)
Obtains an instance of LocalDate from the Modified Julian Day (MJD).

static LocalDate parse(java.lang.CharSequence text)
Obtains an instance of LocalDate from a text string such as 2007-12-03.

static LocalDate parse(java.lang.CharSequence text, DateTimeFormatter formatter)
Obtains an instance of LocalDate from a text string using a specific formatter.

LocalDate plus(PeriodProvider periodProvider)
Returns a copy of this LocalDate with the specified date period added.

LocalDate plusDays(long days)
Returns a copy of this LocalDate with the specified number of days added.

LocalDate plusMonths(long months)
Returns a copy of this LocalDate with the specified period in months added.

LocalDate plusMonths(long months, DateResolver dateResolver)
Returns a copy of this LocalDate with the specified period in months added.

LocalDate plusWeeks(long weeks)
Returns a copy of this LocalDate with the specified period in weeks added.

LocalDate plusYears(long years)
Returns a copy of this LocalDate with the specified period in years added.

LocalDate plusYears(long years, DateResolver dateResolver)
Returns a copy of this LocalDate with the specified period in years added.

static CalendricalRule<LocalDate> rule()
Gets the rule for LocalDate.

long toEpochDay()
Converts this LocalDate to Epoch Days.

LocalDate toLocalDate()
Converts this date to a LocalDate, trivially returning this.

long toModifiedJulianDay()
Converts this LocalDate to Modified Julian Days (MJD).

java.lang.String toString()
Outputs this date as a String, such as 2007-12-03.

java.lang.String toString(DateTimeFormatter formatter)
Outputs this date as a String using the formatter.

LocalDate with(DateAdjuster adjuster)
Returns a copy of this LocalDate with the date altered using the adjuster.

LocalDate with(MonthOfYear monthOfYear)
Returns a copy of this LocalDate with the month-of-year altered.

LocalDate with(MonthOfYear monthOfYear, DateResolver dateResolver)
Returns a copy of this LocalDate with the month-of-year altered.

LocalDate withDayOfMonth(int dayOfMonth)
Returns a copy of this LocalDate with the day-of-month altered.

LocalDate withDayOfMonth(int dayOfMonth, DateResolver dateResolver)
Returns a copy of this LocalDate with the day-of-month altered.

LocalDate withDayOfYear(int dayOfYear)
Returns a copy of this LocalDate with the day-of-year altered.

LocalDate withMonthOfYear(int monthOfYear)
Returns a copy of this LocalDate with the month-of-year altered.

LocalDate withMonthOfYear(int monthOfYear, DateResolver dateResolver)
Returns a copy of this LocalDate with the month-of-year altered.

LocalDate withYear(int year)
Returns a copy of this LocalDate with the year altered.

LocalDate withYear(int year, DateResolver dateResolver)
Returns a copy of this LocalDate with the year altered.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

MIN_DATE

public static final LocalDate 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

public static final LocalDate 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.

Method Detail

rule

public static CalendricalRule<LocalDate> rule()

Gets the rule for LocalDate.

Returns:: the rule for the date, not null

now

public static LocalDate 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, not null

now

public static LocalDate now(Clock clock)

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, not null

of

public static LocalDate of(int year,
                           MonthOfYear monthOfYear,
                           int dayOfMonth)

Obtains an instance of LocalDate 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_YEAR; monthOfYear - the month-of-year to represent, not null; dayOfMonth - the day-of-month to represent, from 1 to 31
Returns:: the local date, not null
Throws:: IllegalCalendarFieldValueException - if the value of any field is out of range; InvalidCalendarFieldException - if the day-of-month is invalid for the month-year

of

public static LocalDate of(int year,
                           int monthOfYear,
                           int dayOfMonth)

Obtains an instance of LocalDate 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_YEAR; monthOfYear - 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, not null
Throws:: IllegalCalendarFieldValueException - if the value of any field is out of range; InvalidCalendarFieldException - if the day-of-month is invalid for the month-year

ofEpochDay

public static LocalDate ofEpochDay(long epochDay)

Obtains an instance of LocalDate from the epoch day count.

The Epoch Day count is a simple incrementing count of days where day 0 is 1970-01-01. Negative numbers represent earlier days.

Parameters:: epochDay - the Epoch Day to convert, based on the epoch 1970-01-01
Returns:: the local date, not null
Throws:: IllegalCalendarFieldValueException - if the epoch days exceeds the supported date range

ofModifiedJulianDay

public static LocalDate ofModifiedJulianDay(long mjDay)

Obtains an instance of LocalDate 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. Negative numbers represent earlier days.

Parameters:: mjDay - the Modified Julian Day to convert, based on the epoch 1858-11-17
Returns:: the local date, not null
Throws:: IllegalCalendarFieldValueException - if the modified julian days value is outside the supported range

from

public static LocalDate from(Calendrical... calendricals)

Obtains an instance of LocalDate from a set of calendricals.

A calendrical represents some form of date and time information. This method combines the input calendricals into a date.

Parameters:: calendricals - the calendricals to create a date from, no nulls, not null
Returns:: the local date, not null
Throws:: CalendricalException - if unable to merge to a local date

parse

public static LocalDate parse(java.lang.CharSequence text)

Obtains an instance of LocalDate from a text string such as 2007-12-03.

The string must represent a valid date and is parsed using DateTimeFormatters.isoLocalDate(). Year, month and day-of-month are required. Years outside the range 0000 to 9999 must be prefixed by the plus or minus symbol.

Parameters:: text - the text to parse such as "2007-12-03", not null
Returns:: the parsed local date, not null
Throws:: CalendricalParseException - if the text cannot be parsed

parse

public static LocalDate parse(java.lang.CharSequence text,
                              DateTimeFormatter formatter)

Obtains an instance of LocalDate 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 null; formatter - the formatter to use, not null
Returns:: the parsed local date, not null
Throws:: java.lang.UnsupportedOperationException - if the formatter cannot parse; CalendricalParseException - if the text cannot be parsed

get

public <T> T get(CalendricalRule<T> ruleToDerive)

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 interface Calendrical

Parameters:: ruleToDerive - the rule to derive, 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 a Year.

Returns:: the year, from MIN_YEAR to MAX_YEAR

getMonthOfYear

public MonthOfYear getMonthOfYear()

Gets the month-of-year field, which is an enum MonthOfYear.

This method returns the enum MonthOfYear for the month. This avoids confusion as to what int values mean. If you need access to the primitive int value then the enum provides the int value.

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, not 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 enum DayOfWeek.

This method returns the enum DayOfWeek for the day-of-week. This avoids confusion as to what int values mean. If you need access to the primitive int value then the enum provides the int value.

Additional information can be obtained from the DayOfWeek. This includes textual names of the values.

Returns:: the day-of-week, not 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 ISO-8601 standard.

Returns:: true if the year is leap, false otherwise

with

public LocalDate with(DateAdjuster adjuster)

Returns a copy of this LocalDate with the date altered using the adjuster.

This adjusts the date according to the rules of the specified adjuster. A simple adjuster might simply set the one of the fields, such as the year field. A more complex adjuster might set the date 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, not null

withYear

public LocalDate withYear(int year)

Returns a copy of this LocalDate with the year altered. If the resulting date is invalid, it will be resolved using DateResolvers.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, not null
Throws:: IllegalCalendarFieldValueException - if the year value is invalid

withYear

public LocalDate withYear(int year,
                          DateResolver dateResolver)

Returns a copy of this LocalDate with the year altered. If the resulting date is invalid, it will be resolved using dateResolver.

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; dateResolver - the DateResolver to be used if the resulting date would be invalid
Returns:: a LocalDate based on this date with the requested year, not null
Throws:: IllegalCalendarFieldValueException - if the year value is invalid

withMonthOfYear

public LocalDate withMonthOfYear(int monthOfYear)

Returns a copy of this LocalDate with the month-of-year altered. If the resulting date is invalid, it will be resolved using DateResolvers.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, not null
Throws:: IllegalCalendarFieldValueException - if the month-of-year value is invalid

withMonthOfYear

public LocalDate withMonthOfYear(int monthOfYear,
                                 DateResolver dateResolver)

Returns a copy of this LocalDate with the month-of-year altered. If the resulting date is invalid, it will be resolved using dateResolver.

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, not null
Throws:: IllegalCalendarFieldValueException - if the month-of-year value is invalid

with

public LocalDate with(MonthOfYear monthOfYear)

Returns a copy of this LocalDate with the month-of-year altered. If the resulting date is invalid, it will be resolved using DateResolvers.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, not null

with

public LocalDate with(MonthOfYear monthOfYear,
                      DateResolver dateResolver)

Returns a copy of this LocalDate with the month-of-year altered. If the resulting date is invalid, it will be resolved using dateResolver.

This instance is immutable and unaffected by this method call.

Parameters:: monthOfYear - the month-of-year to set in the returned date, not null; dateResolver - the DateResolver to be used if the resulting date would be invalid
Returns:: a LocalDate based on this date with the requested month, not null

withDayOfMonth

public LocalDate withDayOfMonth(int dayOfMonth)

Returns a copy of this LocalDate 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, not null
Throws:: IllegalCalendarFieldValueException - if the day-of-month value is invalid; InvalidCalendarFieldException - if the day-of-month is invalid for the month-year

withDayOfMonth

public LocalDate withDayOfMonth(int dayOfMonth,
                                DateResolver dateResolver)

Returns a copy of this LocalDate with the day-of-month altered. If the resulting date is invalid, it will be resolved using dateResolver.

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 31; dateResolver - the DateResolver to be used if the resulting date would be invalid
Returns:: a LocalDate based on this date with the requested day, not null
Throws:: IllegalCalendarFieldValueException - if the day-of-month value is invalid

withDayOfYear

public LocalDate withDayOfYear(int dayOfYear)

Returns a copy of this LocalDate 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, not null
Throws:: IllegalCalendarFieldValueException - if the day-of-year value is invalid; InvalidCalendarFieldException - if the day-of-year is invalid for the year

plus

public LocalDate plus(PeriodProvider periodProvider)

Returns a copy of this LocalDate 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 using Period.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, call Period.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 plus P1M-1M yields 2010-02-28 whereas plusMonths(1).plusDays(-1) gives 2010-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, not null
Throws:: CalendricalException - if the specified period cannot be converted to a Period; CalendricalException - if the result exceeds the supported date range

plusYears

public LocalDate plusYears(long years)

Returns a copy of this LocalDate 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, not null
Throws:: CalendricalException - if the result exceeds the supported date range
See Also:: plusYears(long, javax.time.calendar.DateResolver)

plusYears

public LocalDate plusYears(long years,
                           DateResolver dateResolver)

Returns a copy of this LocalDate 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 negative; dateResolver - the DateResolver to be used if the resulting date would be invalid
Returns:: a LocalDate based on this date with the years added, not null
Throws:: CalendricalException - if the result exceeds the supported date range

plusMonths

public LocalDate plusMonths(long months)

Returns a copy of this LocalDate 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, not null
Throws:: CalendricalException - if the result exceeds the supported date range
See Also:: plusMonths(long, javax.time.calendar.DateResolver)

plusMonths

public LocalDate plusMonths(long months,
                            DateResolver dateResolver)

Returns a copy of this LocalDate 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 negative; dateResolver - the DateResolver to be used if the resulting date would be invalid
Returns:: a LocalDate based on this date with the months added, not null
Throws:: CalendricalException - if the result exceeds the supported date range

plusWeeks

public LocalDate plusWeeks(long weeks)

Returns a copy of this LocalDate 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, not null
Throws:: CalendricalException - if the result exceeds the supported date range

plusDays

public LocalDate plusDays(long days)

Returns a copy of this LocalDate 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, not null
Throws:: CalendricalException - if the result exceeds the supported date range

minus

public LocalDate minus(PeriodProvider periodProvider)

Returns a copy of this LocalDate 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 using Period.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, call Period.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 minus P1M1M yields 2010-02-28 whereas minusMonths(1).minusDays(1) gives 2010-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, not null
Throws:: CalendricalException - if the specified period cannot be converted to a Period; CalendricalException - if the result exceeds the supported date range

minusYears

public LocalDate minusYears(long years)

Returns a copy of this LocalDate 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, not null
Throws:: CalendricalException - if the result exceeds the supported date range
See Also:: minusYears(long, javax.time.calendar.DateResolver)

minusYears

public LocalDate minusYears(long years,
                            DateResolver dateResolver)

Returns a copy of this LocalDate 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 negative; dateResolver - the DateResolver to be used if the resulting date would be invalid
Returns:: a LocalDate based on this date with the years subtracted, not null
Throws:: CalendricalException - if the result exceeds the supported date range

minusMonths

public LocalDate minusMonths(long months)

Returns a copy of this LocalDate 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, not null
Throws:: CalendricalException - if the result exceeds the supported date range
See Also:: minusMonths(long, javax.time.calendar.DateResolver)

minusMonths

public LocalDate minusMonths(long months,
                             DateResolver dateResolver)

Returns a copy of this LocalDate 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 negative; dateResolver - the DateResolver to be used if the resulting date would be invalid
Returns:: a LocalDate based on this date with the months subtracted, not null
Throws:: CalendricalException - if the result exceeds the supported date range

minusWeeks

public LocalDate minusWeeks(long weeks)

Returns a copy of this LocalDate 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, not null
Throws:: CalendricalException - if the result exceeds the supported date range

minusDays

public LocalDate minusDays(long days)

Returns a copy of this LocalDate 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, not null
Throws:: CalendricalException - if the result exceeds the supported date range

matches

public boolean matches(CalendricalMatcher matcher)

Checks whether this LocalDate 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 use matches(javax.time.calendar.CalendricalMatcher) rather than this method.

Specified by:: matchesCalendrical in interface CalendricalMatcher

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 this date.

This method implements the DateAdjuster interface. It is intended that applications use with(DateAdjuster) rather than this method.

Specified by:: adjustDate in interface DateAdjuster

Parameters:: date - the date to be adjusted, not null
Returns:: the adjusted date, not null

atTime

public OffsetDateTime atTime(OffsetTime offsetTime)

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 of OffsetDateTime.

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, not null

atTime

public LocalDateTime atTime(LocalTime localTime)

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 of LocalDateTime.

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, not null

atTime

public LocalDateTime atTime(int hourOfDay,
                            int minuteOfHour)

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 of LocalDateTime.

This instance is immutable and unaffected by this method call.

Parameters:: hourOfDay - the hour-of-day to use, from 0 to 23; minuteOfHour - the minute-of-hour to use, from 0 to 59
Returns:: the local date-time formed from this date and the specified time, not null
Throws:: IllegalCalendarFieldValueException - if the value of any field is out of range

atTime

public LocalDateTime atTime(int hourOfDay,
                            int minuteOfHour,
                            int secondOfMinute)

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 of LocalDateTime.

This instance is immutable and unaffected by this method call.

Parameters:: hourOfDay - the hour-of-day to use, from 0 to 23; minuteOfHour - the minute-of-hour to use, from 0 to 59; secondOfMinute - the second-of-minute to represent, from 0 to 59
Returns:: the local date-time formed from this date and the specified time, not null
Throws:: IllegalCalendarFieldValueException - if the value of any field is out of range

atTime

public LocalDateTime atTime(int hourOfDay,
                            int minuteOfHour,
                            int secondOfMinute,
                            int nanoOfSecond)

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 of LocalDateTime.

This instance is immutable and unaffected by this method call.

Parameters:: hourOfDay - the hour-of-day to use, from 0 to 23; minuteOfHour - the minute-of-hour to use, from 0 to 59; secondOfMinute - the second-of-minute to represent, from 0 to 59; nanoOfSecond - 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, not null
Throws:: IllegalCalendarFieldValueException - if the value of any field is out of range

atMidnight

public LocalDateTime atMidnight()

Returns a local date-time formed from this date at the time of midnight.

This merges the two objects - this and LocalTime.MIDNIGHT - to form an instance of LocalDateTime.

This instance is immutable and unaffected by this method call.

Returns:: the local date-time formed from this date and the time of midnight, not null

atOffset

public OffsetDate atOffset(ZoneOffset offset)

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 of OffsetDate.

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, not null

atStartOfDayInZone

public ZonedDateTime atStartOfDayInZone(ZoneId zone)

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. If the local date is in a gap or overlap according to the rules then a resolver is used to determine the resultant local time and offset. This method uses the post-gap pre-overlap resolver. This selects the date-time immediately after a gap and the earlier offset in overlaps. This combination chooses the earliest valid local time on the date, typically midnight.

To convert to a specific time in a given time-zone call atTime(LocalTime) followed by LocalDateTime.atZone(ZoneId).

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, not null

toLocalDate

public LocalDate toLocalDate()

Converts this date to a LocalDate, trivially returning this.

Returns:: this, not null

toEpochDay

public long toEpochDay()

Converts this LocalDate to Epoch Days.

The Epoch Day count is a simple incrementing count of days where day 0 is 1970-01-01.

Returns:: the Epoch Day equivalent to this date

toModifiedJulianDay

public long toModifiedJulianDay()

Converts this LocalDate 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

compareTo

public int compareTo(LocalDate other)

Compares this LocalDate to another date.

The comparison is based on the time-line position of the dates.

Specified by:: compareTo in interface java.lang.Comparable<LocalDate>

Parameters:: other - the other date to compare to, not null
Returns:: the comparator value, negative if less, positive if greater

isAfter

public boolean isAfter(LocalDate other)

Checks if this LocalDate 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

public boolean isBefore(LocalDate other)

Checks if this LocalDate 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

public boolean equals(java.lang.Object obj)

Checks if this date is equal to another date.

The comparison is based on the time-line position of the dates.

Overrides:: equals in class java.lang.Object

Parameters:: obj - the object to check, null returns false
Returns:: true if this is equal to the other date

hashCode

public int hashCode()

A hash code for this date.

Overrides:: hashCode in class java.lang.Object

Returns:: a suitable hash code

toString

public java.lang.String toString()

Outputs this date as a String, such as 2007-12-03.

The output will be in the ISO-8601 format yyyy-MM-dd.

Overrides:: toString in class java.lang.Object

Returns:: a string representation of this date, not null

toString

public java.lang.String toString(DateTimeFormatter formatter)

Outputs this date as a String using the formatter.

Parameters:: formatter - the formatter to use, not null
Returns:: the formatted date string, not null
Throws:: java.lang.UnsupportedOperationException - if the formatter cannot print; CalendricalException - if an error occurs during printing

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.time.calendar Class LocalDate

MIN_DATE

MAX_DATE

rule

now

now

of

of

ofEpochDay

ofModifiedJulianDay

from

parse

parse

get

getYear

getMonthOfYear

getDayOfMonth

getDayOfYear

getDayOfWeek

isLeapYear

with

withYear

withYear

withMonthOfYear

withMonthOfYear

with

with

withDayOfMonth

withDayOfMonth

withDayOfYear

plus

plusYears

plusYears

plusMonths

plusMonths

plusWeeks

plusDays

minus

minusYears

minusYears

minusMonths

minusMonths

minusWeeks

minusDays

matches

matchesCalendrical

adjustDate

atTime

atTime

atTime

atTime

atTime

atMidnight

atOffset

atStartOfDayInZone

toLocalDate

toEpochDay

toModifiedJulianDay

compareTo

isAfter

isBefore

equals

hashCode

toString

toString

javax.time.calendar
Class LocalDate