Package com.amalgamasimulation.core.intervals

Interface IntervalLike

All Superinterfaces:
Comparable<IntervalLike>
All Known Implementing Classes:
BookingSlot, Gap, Interval, IntervalSet, Slot, TimeInterval
public interface IntervalLike extends Comparable<IntervalLike>
Interface implemented by Interval and IntervalSet classes. Any instances of this type have common properties of a number interval or a set of number intervals, such as:
  • minimal bound, which can be retrieved by min() method,
  • maximal bound, which can be retrieved by max() method,
  • length, i.e. the length of an interval, or the sum of all interval lengths in the case of an interval set. Can be retrieved by length() method
Empty interval or interval set is a special instance that represents non-existent interval or absence thereof, e.g. the result of intersecting of two disjoint intervals. isEmpty() method checks whether the instance is empty.

An interval can represent a single point, i.e. its min()==max(). Such interval is called a zero-length interval, isZeroLength() method checks whether current IntervalLike instance is of such type. Zero-length interval is not the same as empty interval, however the length of an empty interval is also zero by definition. Zero-length interval set contains one or more zero-length intervals.

Another specific case is the universe interval, which contains all possible number intervals. There is only one such intervals, namely [-∞, +∞]. isUniverse() method checks whether this IntervalLike instance is a universe interval or interval set.

The natural ordering for IntervalLike instances is defined in the following way:

  • First, the instances are ordered by min() in ascending order
  • Then, the instances are ordered by max() in ascending order
  • Finally, the instances are ordered by length() also in ascending order
Author:
Andrey Malykhanov

  • Method Details

    • min

      double min()
      Returns the minimal (left) bound of interval or interval set, or Double.NaN if this instance is empty.
      Returns:
      left bound of interval or interval set, can be infinite or Double.NaN

    • max

      double max()
      Returns the maximal (right) bound of interval or interval set, or Double.NaN if this instance is empty.
      Returns:
      right bound of interval or interval set, can be infinite or Double.NaN

    • isEmpty

      boolean isEmpty()
      Checks whether this instance is an empty interval or interval set, i.e. represents a non-existent set, such as a result of intersection of disjoint intervals.

      Empty intervals and interval sets should not be confused with zero-length ones. Zero-length intervals are still intervals with same min and max boundaries.

      For illustration of the difference between zero-length and empty instances, see the code below: 

       var morningShift = Interval.of(8, 12);
 var lunchtime = Interval.of(12, 13);
 var afternoonShift = Interval.of(13, 17);
 
 // The following expressions are true: 
 // morningShift and lunchtime intervals touch at point of 12,
 // so their intersection has zero length but is not empty:
 assert(morningShift.intersection(lunchtime).equals(IntervalSet.of(12, 12)));
 assert(morningShift.intersection(lunchtime).isZeroLength());
 assert(!morningShift.intersection(lunchtime).isEmpty());
         
 // morningShift and afternoonShift intervals do not intersect,
 // so their intersection is an empty interval. By definition,
 // empty intervals have zero length:
 assert(morningShift.intersection(afternoonShift).equals(IntervalSet.EMPTY));
 assert(morningShift.intersection(afternoonShift).isZeroLength());
 assert(morningShift.intersection(afternoonShift).isEmpty());
      Returns:
      true if this instance is an empty interval or interval set, false otherwise
      See Also:

    • isUniverse

      boolean isUniverse()
      Checks whether this instance is a universe interval or interval set, i.e. such that includes all possible intervals. A universe interval is the one of [-∞, +∞], a universe interval set is the one containing only one universe interval.
      Returns:
      true if this instance is a universe interval or interval set, false otherwise

    • size

      int size()
      Returns the number of intervals for interval set, or 1 for interval. If this instance is empty (isEmpty() == true), returns 0.
      Returns:
      number of intervals for interval set, or 1 for interval, or 0

    • union

      IntervalSet union(IntervalLike other)
      Returns a new instance of IntervalSet that represents a union of this instance and the specified other one.
      Parameters:
      other - specified other IntervalLike instance
      Returns:
      new instance of IntervalSet that represents a union of this instance and the specified other one.

    • exclusion

      IntervalSet exclusion(IntervalLike other)
      Returns a new instance of IntervalSet that represents an exclusion of the specified instance from this one.
      Parameters:
      other - specified other IntervalLike instance that is being excluded from this one
      Returns:
      new instance of IntervalSet that represents an exclusion of the specified instance from this one

    • intersection

      IntervalSet intersection(IntervalLike other)
      Returns a new instance of IntervalSet that represents an intersection of this instance and the specified other one.
      Parameters:
      other - specified other IntervalLike instance
      Returns:
      new instance of IntervalSet that represents an intersection of this instance and the specified other one

    • hasNonZeroIntersectionWith

      boolean hasNonZeroIntersectionWith(IntervalLike other)
      Checks whether this IntervalLike instance has a non-zero length intersection with the specified other one.

      Calling this method instead of intersection(IntervalLike) makes sense when it is only needed to check for the presence of non-zero intersection of two IntervalLike instances, as this is done faster than computing the intersection itself.

      Parameters:
      other - specified other IntervalLike instance
      Returns:
      true if this IntervalLike has a non-zero length intersection with the other one, false otherwise

    • contains

      boolean contains(IntervalLike other)
      Checks whether this IntervalLike instance contains (i.e., fully covers) the specified other one.
      Parameters:
      other - specified other IntervalLike instance
      Returns:
      true if this IntervalLike instance contains (i.e., fully covers) the specified other one, false otherwise

    • leftSubset

      IntervalSet leftSubset(double maxLength)
      Returns a new instance of IntervalSet that is a subset of this IntervalLike instance taken from its min() boundary, with the cumulative length not exceeding the specified maximum length. If min() boundary of this IntervalLike is Double.NEGATIVE_INFINITY, indicating an unbounded left boundary, an IllegalStateException is thrown

      If the specified length is >= the length of this IntervalLike, a copy of this instance is returned.

      Parameters:
      maxLength - the maximum cumulative length of intervals to include in the subset. Must be non-negative.
      Returns:
      An IntervalSet representing the leftmost subset of this IntervalLike instance with length not exceeding the specified limit

    • rightSubset

      IntervalSet rightSubset(double maxLength)
      Returns a new instance of IntervalSet that is a subset of this IntervalLike instance taken from its max() boundary, with the cumulative length not exceeding the specified maximum length. If max() boundary of this IntervalLike is Double.POSITIVE_INFINITY, indicating an unbounded right boundary, an IllegalStateException is thrown

      If the specified length is >= the length of this IntervalLike, a copy of this instance is returned.

      Parameters:
      maxLength - the maximum cumulative length of intervals to include in the subset. Must be non-negative.
      Returns:
      An IntervalSet representing the rightmost subset of this IntervalLike instance with length not exceeding the specified limit

    • contains

      default boolean contains(double value)
      Checks whether this IntervalLike instance contains (i.e., touches or covers) the specified value. The result of calling this method is equivalent to the result of the following code: 
       IntervalLike x = ...
 x.contains(Interval.of(value))
      Parameters:
      value - specified value
      Returns:
      true if this IntervalLike instance contains contains (i.e., touches or covers) the specified value, false otherwise

    • toCodeString

      String toCodeString()
      Returns a Java code that creates an IntervalLike equal to this one. Can be used, for example, for unit testing and debugging.
      Returns:
      string representing a Java code that creates an IntervalLike equal to this one

    • length

      default double length()
      Returns the length of this IntervalLike instance, more specifically:
      Returns:
      length of this IntervalLike instance, zero or a positive number, or a Dobule.POSITIVE_INFINITY

    • isFinite

      default boolean isFinite()
      Checks whether current IntervalLike instance is finite, i.e. has a finite length.

      An interval such that at least one of its boundaries is infinite, is infinite. An interval set containing at least one infinite interval, is infinite

      Returns:
      true if this IntervalLike instance is finite, false otherwise

    • isZeroLength

      default boolean isZeroLength()
      Checks whether current IntervalLike instance has zero length, i.e. consists only of zero-length intervals. Empty intervals and interval sets also have zero lengths. See the comment of isEmpty() method for details on the difference between empty and zero-length intervals and interval sets.
      Returns:
      true if this IntervalLike instance has zero length, false otherwise
      See Also:

    • complement

      default IntervalSet complement()
      Returns a new instance of an IntervalSet that is a complement to this one. The result of calling this method is equivalent to the result of the following code: 
       IntervalSet.UNIVERSE.exclusion(this)
      Returns:
      new instance of an IntervalSet that is a complement to this one

    • asIntervalSet

      default IntervalSet asIntervalSet()
      Converts this instance of IntervalLike to an instance of IntervalSet according to the following rules:
      • if the specified instance of IntervalLike is already an instance of IntervalSet, just returns the reference to this instance, without creating any new objects
      • otherwise, if the specified instance of IntervalLike is an instance of Interval, creates a new instance of IntervalSet with this single interval, and returns the reference to this newly created instance
      Returns:
      either existing or new instance of of IntervalSet

    • equalsWithinEpsilon

      boolean equalsWithinEpsilon(IntervalLike other)
      Checks whether this IntervalLike instance is equal to the specified other one with respect to the default epsilon. The default epsilon can be obtained by Compare.getEpsilon() method.
      Parameters:
      other - specified other IntervalLike instance
      Returns:
      true if this IntervalLike instance is equal to the specified other one with respect to the default epsilon, false otherwise

    • equalsWithinEpsilon

      boolean equalsWithinEpsilon(IntervalLike other, EpsilonComparator comparator)
      Checks whether this IntervalLike instance is equal to the specified other one with respect to the epsilon specified in the EpsilonComparator instance.
      Parameters:
      other - specified other IntervalLike instance
      comparator - an EpsilonComparator instance specifying the tolerance of comparison
      Returns:
      true if this IntervalLike instance is equal to the specified other one with respect to the specified epsilon, false otherwise

    • compareTo

      default int compareTo(IntervalLike other)
      Specified by:
      compareTo in interface Comparable<IntervalLike>