java.io.Serializable
public final class LocalDateRange
extends java.lang.Object
implements java.io.Serializable
A LocalDateRange
represents a range of dates, from a start date to an end date.
Instances can be constructed from either a half-open or a closed range of dates.
Internally, the class stores the start and end dates, with the start inclusive and the end exclusive.
The end date is always greater than or equal to the start date.
The constants LocalDate.MIN
and LocalDate.MAX
can be used
to indicate an unbounded far-past or far-future. Note that there is no difference
between a half-open and a closed range when the end is LocalDate.MAX
.
Empty ranges are allowed.
No range can end at LocalDate.MIN
or LocalDate.MIN.plusDays(1)
.
No range can start at LocalDate.MAX
or LocalDate.MAX.minusDays(1)
.
No empty range can exist at LocalDate.MIN
or LocalDate.MAX
.
Date ranges are not comparable. To compare the length of two ranges, it is generally recommended to compare the number of days they contain.
This class must be treated as a value type. Do not synchronize, rely on the identity hash code or use the distinction between equals() and ==.
Modifier and Type | Field | Description |
---|---|---|
static LocalDateRange |
ALL |
A range over the whole time-line.
|
Modifier and Type | Method | Description |
---|---|---|
boolean |
abuts(LocalDateRange other) |
Checks if this range abuts the specified range.
|
boolean |
contains(java.time.LocalDate date) |
Checks if this range contains the specified date.
|
boolean |
encloses(LocalDateRange other) |
Checks if this range encloses the specified range.
|
boolean |
equals(java.lang.Object obj) |
Checks if this range is equal to another range.
|
java.time.LocalDate |
getEnd() |
Gets the end date of this range, exclusive.
|
java.time.LocalDate |
getEndInclusive() |
Gets the end date of this range, inclusive.
|
java.time.LocalDate |
getStart() |
Gets the start date of this range, inclusive.
|
int |
hashCode() |
A hash code for this range.
|
LocalDateRange |
intersection(LocalDateRange other) |
Calculates the range that is the intersection of this range and the specified range.
|
boolean |
isAfter(java.time.LocalDate date) |
Checks if this range is after the specified date.
|
boolean |
isAfter(LocalDateRange other) |
Checks if this range is after the specified range.
|
boolean |
isBefore(java.time.LocalDate date) |
Checks if this range is before the specified date.
|
boolean |
isBefore(LocalDateRange range) |
Checks if this range is before the specified range.
|
boolean |
isConnected(LocalDateRange other) |
Checks if this range is connected to the specified range.
|
boolean |
isEmpty() |
Checks if the range is empty.
|
boolean |
isUnboundedEnd() |
Checks if the end of the range is unbounded.
|
boolean |
isUnboundedStart() |
Checks if the start of the range is unbounded.
|
int |
lengthInDays() |
Obtains the length of this range in days.
|
static LocalDateRange |
of(java.time.LocalDate startInclusive,
java.time.LocalDate endExclusive) |
Obtains a half-open range of dates, including the start and excluding the end.
|
static LocalDateRange |
of(java.time.LocalDate startInclusive,
java.time.Period period) |
Obtains an instance of
LocalDateRange from the start and a period. |
static LocalDateRange |
ofClosed(java.time.LocalDate startInclusive,
java.time.LocalDate endInclusive) |
Obtains a closed range of dates, including the start and end.
|
static LocalDateRange |
ofEmpty(java.time.LocalDate date) |
Obtains an empty date range located at the specified date.
|
static LocalDateRange |
ofUnbounded() |
Obtains a range that is unbounded at the start and end.
|
static LocalDateRange |
ofUnboundedEnd(java.time.LocalDate startInclusive) |
Obtains a range from and including the specified start date.
|
static LocalDateRange |
ofUnboundedStart(java.time.LocalDate endExclusive) |
Obtains a range up to, but not including, the specified end date.
|
boolean |
overlaps(LocalDateRange other) |
Checks if this range overlaps the specified range.
|
static LocalDateRange |
parse(java.lang.CharSequence text) |
Obtains an instance of
LocalDateRange from a text string such as
2007-12-03/2007-12-04 , where the end date is exclusive. |
LocalDateRange |
span(LocalDateRange other) |
Calculates the smallest range that encloses this range and the specified range.
|
java.util.stream.Stream<java.time.LocalDate> |
stream() |
Streams the set of dates included in the range.
|
java.time.Period |
toPeriod() |
Obtains the length of this range as a period.
|
java.lang.String |
toString() |
Outputs this range as a
String , such as 2007-12-03/2007-12-04 . |
LocalDateRange |
union(LocalDateRange other) |
Calculates the range that is the union of this range and the specified range.
|
LocalDateRange |
withEnd(java.time.temporal.TemporalAdjuster adjuster) |
Returns a copy of this range with the end date adjusted.
|
LocalDateRange |
withStart(java.time.temporal.TemporalAdjuster adjuster) |
Returns a copy of this range with the start date adjusted.
|
public static final LocalDateRange ALL
public static LocalDateRange of(java.time.LocalDate startInclusive, java.time.LocalDate endExclusive)
The range includes the start date and excludes the end date, unless the end is LocalDate.MAX
.
The end date must be equal to or after the start date.
This definition permits an empty range located at a specific date.
The constants LocalDate.MIN
and LocalDate.MAX
can be used
to indicate an unbounded far-past or far-future.
The start inclusive date must not be LocalDate.MAX
or LocalDate.MAX.minusDays(1)
.
The end inclusive date must not be LocalDate.MIN
or LocalDate.MIN.plusDays(1)
.
No empty range can exist at LocalDate.MIN
or LocalDate.MAX
.
startInclusive
- the inclusive start date, not nullendExclusive
- the exclusive end date, not nulljava.time.DateTimeException
- if the end is before the start,
or the start date is LocalDate.MAX
or LocalDate.MAX.minusDays(1)
,
or the end date is LocalDate.MIN
or LocalDate.MIN.plusDays(1)
public static LocalDateRange ofClosed(java.time.LocalDate startInclusive, java.time.LocalDate endInclusive)
The range includes the start date and the end date. The end date must be equal to or after the start date.
The constants LocalDate.MIN
and LocalDate.MAX
can be used
to indicate an unbounded far-past or far-future. In addition, an end date of
LocalDate.MAX.minusDays(1)
will also create an unbounded far-future range.
The start inclusive date must not be LocalDate.MAX
or LocalDate.MAX.minusDays(1)
.
The end inclusive date must not be LocalDate.MIN
.
startInclusive
- the inclusive start date, not nullendInclusive
- the inclusive end date, not nulljava.time.DateTimeException
- if the end is before the start,
or the start date is LocalDate.MAX
or LocalDate.MAX.minusDays(1)
,
or the end date is LocalDate.MIN
public static LocalDateRange of(java.time.LocalDate startInclusive, java.time.Period period)
LocalDateRange
from the start and a period.
The end date is calculated as the start plus the duration. The period must not be negative.
The constant LocalDate.MIN
can be used to indicate an unbounded far-past.
The period must not be zero or one day when the start date is LocalDate.MIN
.
startInclusive
- the inclusive start date, not nullperiod
- the period from the start to the end, not nulljava.time.DateTimeException
- if the end is before the start,
or if the period addition cannot be madejava.lang.ArithmeticException
- if numeric overflow occurs when adding the periodpublic static LocalDateRange ofEmpty(java.time.LocalDate date)
The empty range has zero length and contains no other dates or ranges.
An empty range cannot be located at LocalDate.MIN
, LocalDate.MIN.plusDays(1)
,
LocalDate.MAX
or LocalDate.MAX.minusDays(1)
.
date
- the date where the empty range is located, not nulljava.time.DateTimeException
- if the date is LocalDate.MIN
, LocalDate.MIN.plusDays(1)
,
LocalDate.MAX
or LocalDate.MAX.minusDays(1)
public static LocalDateRange ofUnbounded()
public static LocalDateRange ofUnboundedStart(java.time.LocalDate endExclusive)
The range includes all dates from the unbounded start, denoted by LocalDate.MIN
, to the end date.
The end date is exclusive and cannot be LocalDate.MIN
or LocalDate.MIN.plusDays(1)
.
endExclusive
- the exclusive end date, LocalDate.MAX
treated as unbounded, not nulljava.time.DateTimeException
- if the end date is LocalDate.MIN
or LocalDate.MIN.plusDays(1)
public static LocalDateRange ofUnboundedEnd(java.time.LocalDate startInclusive)
The range includes all dates from the start date to the unbounded end, denoted by LocalDate.MAX
.
The start date is inclusive and cannot be LocalDate.MAX
or LocalDate.MAX.minusDays(1)
.
startInclusive
- the inclusive start date, LocalDate.MIN
treated as unbounded, not nulljava.time.DateTimeException
- if the start date is LocalDate.MAX
or LocalDate.MAX.minusDays(1)
public static LocalDateRange parse(java.lang.CharSequence text)
LocalDateRange
from a text string such as
2007-12-03/2007-12-04
, where the end date is exclusive.
The string must consist of one of the following three formats:
LocalDate
, followed by a forward slash,
followed by a representation of a LocalDate
LocalDate
, followed by a forward slash,
followed by a representation of a Period
Period
, followed by a forward slash,
followed by a representation of an LocalDate
text
- the text to parse, not nulljava.time.format.DateTimeParseException
- if the text cannot be parsedpublic java.time.LocalDate getStart()
This will return LocalDate#MIN
if the range is unbounded at the start.
In this case, the range includes all dates into the far-past.
This never returns LocalDate.MAX
or LocalDate.MAX.minusDays(1)
.
public java.time.LocalDate getEnd()
This will return LocalDate.MAX
if the range is unbounded at the end.
In this case, the range includes all dates into the far-future.
This never returns LocalDate.MIN
or LocalDate.MIN.plusDays(1)
.
public java.time.LocalDate getEndInclusive()
This will return LocalDate.MAX
if the range is unbounded at the end.
In this case, the range includes all dates into the far-future.
This returns the date before the end date.
This never returns LocalDate.MIN
.
public boolean isEmpty()
An empty range occurs when the start date equals the end date.
An empty range is never unbounded.
public boolean isUnboundedStart()
An unbounded range is never empty.
public boolean isUnboundedEnd()
An unbounded range is never empty.
public LocalDateRange withStart(java.time.temporal.TemporalAdjuster adjuster)
This returns a new instance with the start date altered.
Since LocalDate
implements TemporalAdjuster
any
local date can simply be passed in.
For example, to adjust the start to one week earlier:
range = range.withStart(date -> date.minus(1, ChronoUnit.WEEKS));
adjuster
- the adjuster to use, not nulljava.time.DateTimeException
- if the new start date is after the current end datepublic LocalDateRange withEnd(java.time.temporal.TemporalAdjuster adjuster)
This returns a new instance with the exclusive end date altered.
Since LocalDate
implements TemporalAdjuster
any
local date can simply be passed in.
For example, to adjust the end to one week later:
range = range.withEnd(date -> date.plus(1, ChronoUnit.WEEKS));
adjuster
- the adjuster to use, not nulljava.time.DateTimeException
- if the new end date is before the current start datepublic boolean contains(java.time.LocalDate date)
This checks if the specified date is within the bounds of this range.
If this range is empty then this method always returns false.
Else if this range has an unbounded start then contains(LocalDate#MIN)
returns true.
Else if this range has an unbounded end then contains(LocalDate#MAX)
returns true.
date
- the date to check for, not nullpublic boolean encloses(LocalDateRange other)
This checks if the bounds of the specified range are within the bounds of this range. An empty range encloses itself.
other
- the other range to check for, not nullpublic boolean abuts(LocalDateRange other)
The result is true if the end of this range is the start of the other, or vice versa. An empty range does not abut itself.
other
- the other range, not nullpublic boolean isConnected(LocalDateRange other)
The result is true if the two ranges have an enclosed range in common, even if that range is empty. An empty range is connected to itself.
This is equivalent to (overlaps(other) || abuts(other))
.
other
- the other range, not nullpublic boolean overlaps(LocalDateRange other)
The result is true if the the two ranges share some part of the time-line. An empty range overlaps itself.
This is equivalent to (isConnected(other) && !abuts(other))
.
other
- the time range to compare to, null means a zero length range nowpublic LocalDateRange intersection(LocalDateRange other)
This finds the intersection of two ranges. This throws an exception if the two ranges are not connected.
other
- the other range to check for, not nulljava.time.DateTimeException
- if the ranges do not connectpublic LocalDateRange union(LocalDateRange other)
This finds the union of two ranges. This throws an exception if the two ranges are not connected.
other
- the other range to check for, not nulljava.time.DateTimeException
- if the ranges do not connectpublic LocalDateRange span(LocalDateRange other)
The result of this method will enclose this range and the specified range.
other
- the other range to check for, not nullpublic java.util.stream.Stream<java.time.LocalDate> stream()
This returns a stream consisting of each date in the range. The stream is ordered.
public boolean isAfter(java.time.LocalDate date)
The result is true if every date in this range is after the specified date. An empty range behaves as though it is a date for comparison purposes.
date
- the other date to compare to, not nullpublic boolean isBefore(java.time.LocalDate date)
The result is true if every date in this range is before the specified date. An empty range behaves as though it is a date for comparison purposes.
date
- the other date to compare to, not nullpublic boolean isAfter(LocalDateRange other)
The result is true if every date in this range is after every date in the specified range. An empty range behaves as though it is a date for comparison purposes.
other
- the other range to compare to, not nullpublic boolean isBefore(LocalDateRange range)
The result is true if every date in this range is before every date in the specified range. An empty range behaves as though it is a date for comparison purposes.
range
- the other range to compare to, not nullpublic int lengthInDays()
This returns the number of days between the start and end dates.
If the range is too large, the length will be Integer.MAX_VALUE
.
Unbounded ranges return Integer.MAX_VALUE
.
public java.time.Period toPeriod()
This returns the Period
between the start and end dates.
Unbounded ranges throw ArithmeticException
.
java.lang.ArithmeticException
- if the calculation exceeds the capacity of Period
,
or the range is unboundedpublic boolean equals(java.lang.Object obj)
Compares this LocalDateRange
with another ensuring that the two dates are the same.
Only objects of type LocalDateRange
are compared, other types return false.
equals
in class java.lang.Object
obj
- the object to check, null returns falsepublic int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
String
, such as 2007-12-03/2007-12-04
.
The output will be the ISO-8601 format formed by combining the
toString()
methods of the two dates, separated by a forward slash.
toString
in class java.lang.Object
Copyright © 2010–2018 ThreeTen.org. All rights reserved.