Package org.threeten.extra

Class LocalDateRange

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

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:

  • Field Details

    • ALL

      public static final LocalDateRange ALL
      A range over the whole time-line.

  • Method Details

    • 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 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.

      Parameters:
      startInclusive - the inclusive start date, not null
      endExclusive - 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 is LocalDate.MAX or LocalDate.MAX.minusDays(1), or the end date is LocalDate.MIN or LocalDate.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 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.

      Parameters:
      startInclusive - the inclusive start date, not null
      endInclusive - the inclusive end date, not null
      Returns:
      the closed range
      Throws:
      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

    • of

      public static LocalDateRange of(LocalDate startInclusive, Period period)
      Obtains an instance of 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.

      Parameters:
      startInclusive - the inclusive start date, not null
      period - 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 made
      ArithmeticException - 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 or LocalDate.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 is LocalDate.MIN, LocalDate.MIN.plusDays(1), LocalDate.MAX or LocalDate.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 be LocalDate.MIN or LocalDate.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 is LocalDate.MIN or LocalDate.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 be LocalDate.MAX or LocalDate.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 is LocalDate.MAX or LocalDate.MAX.minusDays(1)

    • parse

      public static LocalDateRange parse(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.

      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 a LocalDate
      • a representation of an LocalDate, followed by a forward slash, followed by a representation of a Period
      • a representation of a Period, followed by a forward slash, followed by a representation of an LocalDate
      Parameters:
      text - the text to parse, not null
      Returns:
      the parsed range, not null
      Throws:
      DateTimeParseException - if the text cannot be parsed

    • 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 or LocalDate.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 or LocalDate.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 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));
      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 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));
      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 then contains(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
      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 return Integer.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 throw ArithmeticException.

      Returns:
      the period of the range
      Throws:
      ArithmeticException - if the calculation exceeds the capacity of Period, or the range is unbounded

    • equals

      public boolean equals(@Nullable 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 type LocalDateRange are compared, other types return false.

      Overrides:
      equals in class Object
      Parameters:
      obj - the object to check, null returns false
      Returns:
      true if this is equal to the other range

    • hashCode

      public int hashCode()
      A hash code for this range.
      Overrides:
      hashCode in class Object
      Returns:
      a suitable hash code

    • toString

      public String toString()
      Outputs this range as a 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.

      Overrides:
      toString in class Object
      Returns:
      a string representation of this date, not null