- java.lang.Object
-
- org.threeten.extra.LocalDateRange
-
- All Implemented Interfaces:
Serializable
public final class LocalDateRange extends Object implements Serializable
A range of local dates.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
andLocalDate.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 isLocalDate.MAX
. Empty ranges are allowed.No range can end at
LocalDate.MIN
orLocalDate.MIN.plusDays(1)
. No range can start atLocalDate.MAX
orLocalDate.MAX.minusDays(1)
. No empty range can exist atLocalDate.MIN
orLocalDate.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.
Implementation Requirements:
This class is immutable and thread-safe.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 ==.
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static LocalDateRange
ALL
A range over the whole time-line.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
abuts(LocalDateRange other)
Checks if this range abuts the specified range.boolean
contains(LocalDate date)
Checks if this range contains the specified date.boolean
encloses(LocalDateRange other)
Checks if this range encloses the specified range.boolean
equals(Object obj)
Checks if this range is equal to another range.LocalDate
getEnd()
Gets the end date of this range, exclusive.LocalDate
getEndInclusive()
Gets the end date of this range, inclusive.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(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(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(LocalDate startInclusive, LocalDate endExclusive)
Obtains a half-open range of dates, including the start and excluding the end.static LocalDateRange
of(LocalDate startInclusive, Period period)
Obtains an instance ofLocalDateRange
from the start and a period.static LocalDateRange
ofClosed(LocalDate startInclusive, LocalDate endInclusive)
Obtains a closed range of dates, including the start and end.static LocalDateRange
ofEmpty(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(LocalDate startInclusive)
Obtains a range from and including the specified start date.static LocalDateRange
ofUnboundedStart(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(CharSequence text)
Obtains an instance ofLocalDateRange
from a text string such as2007-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.Stream<LocalDate>
stream()
Streams the set of dates included in the range.Period
toPeriod()
Obtains the length of this range as a period.String
toString()
Outputs this range as aString
, such as2007-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(TemporalAdjuster adjuster)
Returns a copy of this range with the end date adjusted.LocalDateRange
withStart(TemporalAdjuster adjuster)
Returns a copy of this range with the start date adjusted.
-
-
-
Field Detail
-
ALL
public static final LocalDateRange ALL
A range over the whole time-line.
-
-
Method Detail
-
of
public static LocalDateRange of(LocalDate startInclusive, LocalDate endExclusive)
Obtains a half-open range of dates, including the start and excluding the end.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
andLocalDate.MAX
can be used to indicate an unbounded far-past or far-future.The start inclusive date must not be
LocalDate.MAX
orLocalDate.MAX.minusDays(1)
. The end inclusive date must not beLocalDate.MIN
orLocalDate.MIN.plusDays(1)
. No empty range can exist atLocalDate.MIN
orLocalDate.MAX
.- Parameters:
startInclusive
- the inclusive start date, not nullendExclusive
- the exclusive end date, not null- Returns:
- the half-open range, not null
- Throws:
DateTimeException
- if the end is before the start, or the start date isLocalDate.MAX
orLocalDate.MAX.minusDays(1)
, or the end date isLocalDate.MIN
orLocalDate.MIN.plusDays(1)
-
ofClosed
public static LocalDateRange ofClosed(LocalDate startInclusive, LocalDate endInclusive)
Obtains a closed range of dates, including the start and end.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
andLocalDate.MAX
can be used to indicate an unbounded far-past or far-future. In addition, an end date ofLocalDate.MAX.minusDays(1)
will also create an unbounded far-future range.The start inclusive date must not be
LocalDate.MAX
orLocalDate.MAX.minusDays(1)
. The end inclusive date must not beLocalDate.MIN
.- Parameters:
startInclusive
- the inclusive start date, not nullendInclusive
- the inclusive end date, not null- Returns:
- the closed range
- Throws:
DateTimeException
- if the end is before the start, or the start date isLocalDate.MAX
orLocalDate.MAX.minusDays(1)
, or the end date isLocalDate.MIN
-
of
public static LocalDateRange of(LocalDate startInclusive, Period period)
Obtains an instance ofLocalDateRange
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
.- Parameters:
startInclusive
- the inclusive start date, not nullperiod
- the period from the start to the end, not null- Returns:
- the range, not null
- Throws:
DateTimeException
- if the end is before the start, or if the period addition cannot be madeArithmeticException
- if numeric overflow occurs when adding the period
-
ofEmpty
public static LocalDateRange ofEmpty(LocalDate date)
Obtains an empty date range located at the specified 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
orLocalDate.MAX.minusDays(1)
.- Parameters:
date
- the date where the empty range is located, not null- Returns:
- the empty range, not null
- Throws:
DateTimeException
- if the date isLocalDate.MIN
,LocalDate.MIN.plusDays(1)
,LocalDate.MAX
orLocalDate.MAX.minusDays(1)
-
ofUnbounded
public static LocalDateRange ofUnbounded()
Obtains a range that is unbounded at the start and end.- Returns:
- the range, with an unbounded start and unbounded end
-
ofUnboundedStart
public static LocalDateRange ofUnboundedStart(LocalDate endExclusive)
Obtains a range up to, but not including, the specified end date.The range includes all dates from the unbounded start, denoted by
LocalDate.MIN
, to the end date. The end date is exclusive and cannot beLocalDate.MIN
orLocalDate.MIN.plusDays(1)
.- Parameters:
endExclusive
- the exclusive end date,LocalDate.MAX
treated as unbounded, not null- Returns:
- the range, with an unbounded start
- Throws:
DateTimeException
- if the end date isLocalDate.MIN
orLocalDate.MIN.plusDays(1)
-
ofUnboundedEnd
public static LocalDateRange ofUnboundedEnd(LocalDate startInclusive)
Obtains a range from and including the specified start date.The range includes all dates from the start date to the unbounded end, denoted by
LocalDate.MAX
. The start date is inclusive and cannot beLocalDate.MAX
orLocalDate.MAX.minusDays(1)
.- Parameters:
startInclusive
- the inclusive start date,LocalDate.MIN
treated as unbounded, not null- Returns:
- the range, with an unbounded end
- Throws:
DateTimeException
- if the start date isLocalDate.MAX
orLocalDate.MAX.minusDays(1)
-
parse
public static LocalDateRange parse(CharSequence text)
Obtains an instance ofLocalDateRange
from a text string such as2007-12-03/2007-12-04
, where the end date is exclusive.The string must consist of one of the following three formats:
- a representations of an
LocalDate
, followed by a forward slash, followed by a representation of aLocalDate
- a representation of an
LocalDate
, followed by a forward slash, followed by a representation of aPeriod
- a representation of a
Period
, followed by a forward slash, followed by a representation of anLocalDate
- Parameters:
text
- the text to parse, not null- Returns:
- the parsed range, not null
- Throws:
DateTimeParseException
- if the text cannot be parsed
- a representations of an
-
getStart
public LocalDate getStart()
Gets the start date of this range, inclusive.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
orLocalDate.MAX.minusDays(1)
.- Returns:
- the start date
-
getEnd
public LocalDate getEnd()
Gets the end date of this range, exclusive.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
orLocalDate.MIN.plusDays(1)
.- Returns:
- the end date, exclusive
-
getEndInclusive
public LocalDate getEndInclusive()
Gets the end date of this range, inclusive.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
.- Returns:
- the end date, inclusive
-
isEmpty
public boolean isEmpty()
Checks if the range is empty.An empty range occurs when the start date equals the end date.
An empty range is never unbounded.
- Returns:
- true if the range is empty
-
isUnboundedStart
public boolean isUnboundedStart()
Checks if the start of the range is unbounded.An unbounded range is never empty.
- Returns:
- true if start is unbounded
-
isUnboundedEnd
public boolean isUnboundedEnd()
Checks if the end of the range is unbounded.An unbounded range is never empty.
- Returns:
- true if end is unbounded
-
withStart
public LocalDateRange withStart(TemporalAdjuster adjuster)
Returns a copy of this range with the start date adjusted.This returns a new instance with the start date altered. Since
LocalDate
implementsTemporalAdjuster
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));
- Parameters:
adjuster
- the adjuster to use, not null- Returns:
- a copy of this range with the start date adjusted
- Throws:
DateTimeException
- if the new start date is after the current end date
-
withEnd
public LocalDateRange withEnd(TemporalAdjuster adjuster)
Returns a copy of this range with the end date adjusted.This returns a new instance with the exclusive end date altered. Since
LocalDate
implementsTemporalAdjuster
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));
- Parameters:
adjuster
- the adjuster to use, not null- Returns:
- a copy of this range with the end date adjusted
- Throws:
DateTimeException
- if the new end date is before the current start date
-
contains
public boolean contains(LocalDate date)
Checks if this range contains the specified 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 thencontains(LocalDate#MAX)
returns true.- Parameters:
date
- the date to check for, not null- Returns:
- true if this range contains the date
-
encloses
public boolean encloses(LocalDateRange other)
Checks if this range encloses the specified range.This checks if the bounds of the specified range are within the bounds of this range. An empty range encloses itself.
- Parameters:
other
- the other range to check for, not null- Returns:
- true if this range contains all dates in the other range
-
abuts
public boolean abuts(LocalDateRange other)
Checks if this range abuts the specified range.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.
- Parameters:
other
- the other range, not null- Returns:
- true if this range abuts the other range
-
isConnected
public boolean isConnected(LocalDateRange other)
Checks if this range is connected to the specified range.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))
.- Parameters:
other
- the other range, not null- Returns:
- true if this range is connected to the other range
-
overlaps
public boolean overlaps(LocalDateRange other)
Checks if this range overlaps the specified range.The result is true if the two ranges share some part of the time-line. An empty range overlaps itself.
This is equivalent to
(isConnected(other) && !abuts(other))
.- Parameters:
other
- the time range to compare to, null means a zero length range now- Returns:
- true if the time ranges overlap
-
intersection
public LocalDateRange intersection(LocalDateRange other)
Calculates the range that is the intersection of this range and the specified range.This finds the intersection of two ranges. This throws an exception if the two ranges are not connected.
- Parameters:
other
- the other range to check for, not null- Returns:
- the range that is the intersection of the two ranges
- Throws:
DateTimeException
- if the ranges do not connect
-
union
public LocalDateRange union(LocalDateRange other)
Calculates the range that is the union of this range and the specified range.This finds the union of two ranges. This throws an exception if the two ranges are not connected.
- Parameters:
other
- the other range to check for, not null- Returns:
- the range that is the union of the two ranges
- Throws:
DateTimeException
- if the ranges do not connect
-
span
public LocalDateRange span(LocalDateRange other)
Calculates the smallest range that encloses this range and the specified range.The result of this method will enclose this range and the specified range.
- Parameters:
other
- the other range to check for, not null- Returns:
- the range that spans the two ranges
-
stream
public Stream<LocalDate> stream()
Streams the set of dates included in the range.This returns a stream consisting of each date in the range. The stream is ordered.
- Returns:
- the stream of dates from the start to the end
-
isAfter
public boolean isAfter(LocalDate date)
Checks if this range is after the specified 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.
- Parameters:
date
- the other date to compare to, not null- Returns:
- true if the start of this range is after the specified date
-
isBefore
public boolean isBefore(LocalDate date)
Checks if this range is before the specified 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.
- Parameters:
date
- the other date to compare to, not null- Returns:
- true if the start of this range is before the specified date
-
isAfter
public boolean isAfter(LocalDateRange other)
Checks if this range is after the specified range.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.
- Parameters:
other
- the other range to compare to, not null- Returns:
- true if every date in this range is after every date in the other range
-
isBefore
public boolean isBefore(LocalDateRange range)
Checks if this range is before the specified 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.
- Parameters:
range
- the other range to compare to, not null- Returns:
- true if every date in this range is before every date in the other range
-
lengthInDays
public int lengthInDays()
Obtains the length of this range in days.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 returnInteger.MAX_VALUE
.- Returns:
- the length in days, Integer.MAX_VALUE if unbounded or too large
-
toPeriod
public Period toPeriod()
Obtains the length of this range as a period.This returns the
Period
between the start and end dates. Unbounded ranges throwArithmeticException
.- Returns:
- the period of the range
- Throws:
ArithmeticException
- if the calculation exceeds the capacity ofPeriod
, or the range is unbounded
-
equals
public boolean equals(Object obj)
Checks if this range is equal to another range.Compares this
LocalDateRange
with another ensuring that the two dates are the same. Only objects of typeLocalDateRange
are compared, other types return false.
-
hashCode
public int hashCode()
A hash code for this range.
-
toString
public String toString()
Outputs this range as aString
, such as2007-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.
-
-