Class Interval

  • All Implemented Interfaces:
    java.io.Serializable

    public final class Interval
    extends java.lang.Object
    implements java.io.Serializable
    An immutable interval of time between two instants.

    An interval represents the time on the time-line between two Instants. The class stores the start and end instants, with the start inclusive and the end exclusive. The end instant is always greater than or equal to the start instant.

    The Duration of an interval can be obtained, but is a separate concept. An interval is connected to the time-line, whereas a duration is not.

    Intervals are not comparable. To compare the length of two intervals, it is generally recommended to compare their durations.

    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 Interval ALL
      An interval over the whole time-line.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean abuts​(Interval other)
      Checks if this interval abuts the specified interval.
      boolean contains​(java.time.Instant instant)
      Checks if this interval contains the specified instant.
      boolean encloses​(Interval other)
      Checks if this interval encloses the specified interval.
      boolean equals​(java.lang.Object obj)
      Checks if this interval is equal to another interval.
      java.time.Instant getEnd()
      Gets the end of this time interval, exclusive.
      java.time.Instant getStart()
      Gets the start of this time interval, inclusive.
      int hashCode()
      A hash code for this interval.
      Interval intersection​(Interval other)
      Calculates the interval that is the intersection of this interval and the specified interval.
      boolean isAfter​(java.time.Instant instant)
      Checks if this interval is after the specified instant.
      boolean isAfter​(Interval interval)
      Checks if this interval is after the specified interval.
      boolean isBefore​(java.time.Instant instant)
      Checks if this interval is before the specified instant.
      boolean isBefore​(Interval interval)
      Checks if this interval is before the specified interval.
      boolean isConnected​(Interval other)
      Checks if this interval is connected to the specified interval.
      boolean isEmpty()
      Checks if the range is empty.
      boolean isUnboundedEnd()
      Checks if the end of the interval is unbounded.
      boolean isUnboundedStart()
      Checks if the start of the interval is unbounded.
      static Interval of​(java.time.Instant startInclusive, java.time.Duration duration)
      Obtains an instance of Interval from the start and a duration.
      static Interval of​(java.time.Instant startInclusive, java.time.Instant endExclusive)
      Obtains an instance of Interval from the start and end instant.
      boolean overlaps​(Interval other)
      Checks if this interval overlaps the specified interval.
      static Interval parse​(java.lang.CharSequence text)
      Obtains an instance of Interval from a text string such as 2007-12-03T10:15:30Z/2007-12-04T10:15:30Z, where the end instant is exclusive.
      Interval span​(Interval other)
      Calculates the smallest interval that encloses this interval and the specified interval.
      java.time.Duration toDuration()
      Obtains the duration of this interval.
      java.lang.String toString()
      Outputs this interval as a String, such as 2007-12-03T10:15:30/2007-12-04T10:15:30.
      Interval union​(Interval other)
      Calculates the interval that is the union of this interval and the specified interval.
      Interval withEnd​(java.time.Instant end)
      Returns a copy of this range with the specified end instant.
      Interval withStart​(java.time.Instant start)
      Returns a copy of this range with the specified start instant.
      • Methods inherited from class java.lang.Object

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

      • ALL

        public static final Interval ALL
        An interval over the whole time-line.
    • Method Detail

      • of

        public static Interval of​(java.time.Instant startInclusive,
                                  java.time.Instant endExclusive)
        Obtains an instance of Interval from the start and end instant.

        The end instant must not be before the start instant.

        Parameters:
        startInclusive - the start instant, inclusive, MIN_DATE treated as unbounded, not null
        endExclusive - the end instant, exclusive, MAX_DATE treated as unbounded, not null
        Returns:
        the half-open interval, not null
        Throws:
        java.time.DateTimeException - if the end is before the start
      • of

        public static Interval of​(java.time.Instant startInclusive,
                                  java.time.Duration duration)
        Obtains an instance of Interval from the start and a duration.

        The end instant is calculated as the start plus the duration. The duration must not be negative.

        Parameters:
        startInclusive - the start instant, inclusive, not null
        duration - the duration from the start to the end, not null
        Returns:
        the interval, not null
        Throws:
        java.time.DateTimeException - if the end is before the start, or if the duration addition cannot be made
        java.lang.ArithmeticException - if numeric overflow occurs when adding the duration
      • parse

        public static Interval parse​(java.lang.CharSequence text)
        Obtains an instance of Interval from a text string such as 2007-12-03T10:15:30Z/2007-12-04T10:15:30Z, where the end instant is exclusive.

        The string must consist of one of the following four formats:

        • a representations of an OffsetDateTime, followed by a forward slash, followed by a representation of a OffsetDateTime
        • a representations of an OffsetDateTime, followed by a forward slash, followed by a representation of a LocalDateTime, where the end offset is implied.
        • a representation of an OffsetDateTime, followed by a forward slash, followed by a representation of a PeriodDuration
        • a representation of a PeriodDuration, followed by a forward slash, followed by a representation of an OffsetDateTime

        ISO-8601 supports a very wide range of possible inputs, many of which are not supported here. For example, basic format, week-based dates, ordinal dates and date-style period formats are not supported.

        Parameters:
        text - the text to parse, not null
        Returns:
        the parsed interval, not null
        Throws:
        java.time.format.DateTimeParseException - if the text cannot be parsed
      • getStart

        public java.time.Instant getStart()
        Gets the start of this time interval, inclusive.

        This will return Instant.MIN if the range is unbounded at the start. In this case, the range includes all dates into the far-past.

        Returns:
        the start of the time interval
      • getEnd

        public java.time.Instant getEnd()
        Gets the end of this time interval, exclusive.

        This will return Instant.MAX if the range is unbounded at the end. In this case, the range includes all dates into the far-future.

        Returns:
        the end of the time interval, exclusive
      • isEmpty

        public boolean isEmpty()
        Checks if the range is empty.

        An empty range occurs when the start date equals the inclusive end date.

        Returns:
        true if the range is empty
      • isUnboundedStart

        public boolean isUnboundedStart()
        Checks if the start of the interval is unbounded.
        Returns:
        true if start is unbounded
      • isUnboundedEnd

        public boolean isUnboundedEnd()
        Checks if the end of the interval is unbounded.
        Returns:
        true if end is unbounded
      • withStart

        public Interval withStart​(java.time.Instant start)
        Returns a copy of this range with the specified start instant.
        Parameters:
        start - the start instant for the new interval, not null
        Returns:
        an interval with the end from this interval and the specified start
        Throws:
        java.time.DateTimeException - if the resulting interval has end before start
      • withEnd

        public Interval withEnd​(java.time.Instant end)
        Returns a copy of this range with the specified end instant.
        Parameters:
        end - the end instant for the new interval, not null
        Returns:
        an interval with the start from this interval and the specified end
        Throws:
        java.time.DateTimeException - if the resulting interval has end before start
      • contains

        public boolean contains​(java.time.Instant instant)
        Checks if this interval contains the specified instant.

        This checks if the specified instant is within the bounds of this interval. If this range has an unbounded start then contains(Instant#MIN) returns true. If this range has an unbounded end then contains(Instant#MAX) returns true. If this range is empty then this method always returns false.

        Parameters:
        instant - the instant, not null
        Returns:
        true if this interval contains the instant
      • encloses

        public boolean encloses​(Interval other)
        Checks if this interval encloses the specified interval.

        This checks if the bounds of the specified interval are within the bounds of this interval. An empty interval encloses itself.

        Parameters:
        other - the other interval, not null
        Returns:
        true if this interval contains the other interval
      • abuts

        public boolean abuts​(Interval other)
        Checks if this interval abuts the specified interval.

        The result is true if the end of this interval is the start of the other, or vice versa. An empty interval does not abut itself.

        Parameters:
        other - the other interval, not null
        Returns:
        true if this interval abuts the other interval
      • isConnected

        public boolean isConnected​(Interval other)
        Checks if this interval is connected to the specified interval.

        The result is true if the two intervals have an enclosed interval in common, even if that interval is empty. An empty interval is connected to itself.

        This is equivalent to (overlaps(other) || abuts(other)).

        Parameters:
        other - the other interval, not null
        Returns:
        true if this interval is connected to the other interval
      • overlaps

        public boolean overlaps​(Interval other)
        Checks if this interval overlaps the specified interval.

        The result is true if the the two intervals share some part of the time-line. An empty interval overlaps itself.

        This is equivalent to (isConnected(other) && !abuts(other)).

        Parameters:
        other - the time interval to compare to, null means a zero length interval now
        Returns:
        true if the time intervals overlap
      • intersection

        public Interval intersection​(Interval other)
        Calculates the interval that is the intersection of this interval and the specified interval.

        This finds the intersection of two intervals. This throws an exception if the two intervals are not connected.

        Parameters:
        other - the other interval to check for, not null
        Returns:
        the interval that is the intersection of the two intervals
        Throws:
        java.time.DateTimeException - if the intervals do not connect
      • union

        public Interval union​(Interval other)
        Calculates the interval that is the union of this interval and the specified interval.

        This finds the union of two intervals. This throws an exception if the two intervals are not connected.

        Parameters:
        other - the other interval to check for, not null
        Returns:
        the interval that is the union of the two intervals
        Throws:
        java.time.DateTimeException - if the intervals do not connect
      • span

        public Interval span​(Interval other)
        Calculates the smallest interval that encloses this interval and the specified interval.

        The result of this method will enclose this interval and the specified interval.

        Parameters:
        other - the other interval to check for, not null
        Returns:
        the interval that spans the two intervals
      • isAfter

        public boolean isAfter​(java.time.Instant instant)
        Checks if this interval is after the specified instant.

        The result is true if this instant starts after the specified instant. An empty interval behaves as though it is an instant for comparison purposes.

        Parameters:
        instant - the other instant to compare to, not null
        Returns:
        true if the start of this interval is after the specified instant
      • isBefore

        public boolean isBefore​(java.time.Instant instant)
        Checks if this interval is before the specified instant.

        The result is true if this instant ends before the specified instant. Since intervals do not include their end points, this will return true if the instant equals the end of the interval. An empty interval behaves as though it is an instant for comparison purposes.

        Parameters:
        instant - the other instant to compare to, not null
        Returns:
        true if the start of this interval is before the specified instant
      • isAfter

        public boolean isAfter​(Interval interval)
        Checks if this interval is after the specified interval.

        The result is true if this instant starts after the end of the specified interval. Since intervals do not include their end points, this will return true if the instant equals the end of the interval. An empty interval behaves as though it is an instant for comparison purposes.

        Parameters:
        interval - the other interval to compare to, not null
        Returns:
        true if this instant is after the specified instant
      • isBefore

        public boolean isBefore​(Interval interval)
        Checks if this interval is before the specified interval.

        The result is true if this instant ends before the start of the specified interval. Since intervals do not include their end points, this will return true if the two intervals abut. An empty interval behaves as though it is an instant for comparison purposes.

        Parameters:
        interval - the other interval to compare to, not null
        Returns:
        true if this instant is before the specified instant
      • toDuration

        public java.time.Duration toDuration()
        Obtains the duration of this interval.

        An Interval is associated with two specific instants on the time-line. A Duration is simply an amount of time, separate from the time-line.

        Returns:
        the duration of the time interval
        Throws:
        java.lang.ArithmeticException - if the calculation exceeds the capacity of Duration
      • equals

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

        Compares this Interval with another ensuring that the two instants are the same. Only objects of type Interval 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 interval
      • hashCode

        public int hashCode()
        A hash code for this interval.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a suitable hash code
      • toString

        public java.lang.String toString()
        Outputs this interval as a String, such as 2007-12-03T10:15:30/2007-12-04T10:15:30.

        The output will be the ISO-8601 format formed by combining the toString() methods of the two instants, separated by a forward slash.

        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation of this instant, not null