Class LocalDateRange

  • All Implemented Interfaces:
    java.io.Serializable

    public final class LocalDateRange
    extends java.lang.Object
    implements java.io.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:
    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​(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.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • ALL

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

      • of

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

        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:
        java.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)
      • ofClosed

        public static LocalDateRange ofClosed​(java.time.LocalDate startInclusive,
                                              java.time.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:
        java.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
      • of

        public static LocalDateRange of​(java.time.LocalDate startInclusive,
                                        java.time.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:
        java.time.DateTimeException - if the end is before the start, or if the period addition cannot be made
        java.lang.ArithmeticException - if numeric overflow occurs when adding the period
      • ofEmpty

        public static LocalDateRange ofEmpty​(java.time.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:
        java.time.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​(java.time.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:
        java.time.DateTimeException - if the end date is LocalDate.MIN or LocalDate.MIN.plusDays(1)
      • ofUnboundedEnd

        public static LocalDateRange ofUnboundedEnd​(java.time.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:
        java.time.DateTimeException - if the start date is LocalDate.MAX or LocalDate.MAX.minusDays(1)
      • parse

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

        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:
        java.time.format.DateTimeParseException - if the text cannot be parsed
      • getStart

        public java.time.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 java.time.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 java.time.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​(java.time.temporal.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:
        java.time.DateTimeException - if the new start date is after the current end date
      • withEnd

        public LocalDateRange withEnd​(java.time.temporal.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:
        java.time.DateTimeException - if the new end date is before the current start date
      • contains

        public boolean contains​(java.time.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 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:
        java.time.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:
        java.time.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 java.util.stream.Stream<java.time.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​(java.time.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​(java.time.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 java.time.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:
        java.lang.ArithmeticException - if the calculation exceeds the capacity of Period, or the range is unbounded
      • equals

        public boolean equals​(java.lang.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 java.lang.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 java.lang.Object
        Returns:
        a suitable hash code
      • toString

        public java.lang.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 java.lang.Object
        Returns:
        a string representation of this date, not null