Package com.amalgamasimulation.core.intervals

Class IntervalSet

java.lang.Object
com.amalgamasimulation.core.intervals.IntervalSet
All Implemented Interfaces:
IntervalLike, Comparable<IntervalLike>, Iterable<Interval>
public class IntervalSet extends Object implements IntervalLike, Iterable<Interval>
Class representing a sorted set of zero, one or several pairwise-disjoint (that is, non-intersecting) number intervals. These intervals are represented with instances of Interval class.

The intervals are always sorted by their natural order described in IntervalLike interface documentation.

Note that any IntervalSet instance is always normalized, i.e. it always contains a set of pairwise disjoint intervals even at creation time the intervals used to create an IntervalSet instance were not disjoint.

The simple example of using an IntervalSet to represent a working day consisting of two 4-hour shifts: 

 var morningShift = Interval.of(8, 12);
 var afternoonShift = Interval.of(13, 17);
 IntervalSet workingDay = morningShift.union(afternoonShift);
 // Output: {[8.0, 12.0], [13.0, 17.0]}
 System.out.println("Working day: " + workingDay);
Author:
Andrey Malykhanov

  • Field Details

    • EMPTY

      public static final IntervalSet EMPTY
      Empty interval set, i.e. one containing no intervals and representing, for example, a result of intersection of disjoint intervals

    • UNIVERSE

      public static final IntervalSet UNIVERSE
      Universe interval set, i.e. interval set that contains exactly one Interval.UNIVERSE interval.

  • Constructor Details

    • IntervalSet

      public IntervalSet(Interval interval)
      Creates a new instance of IntervalSet containing a single specified interval.
      Parameters:
      interval - single specified interval

    • IntervalSet

      public IntervalSet(List<? extends Interval> intervals)
      Creates a new instance of IntervalSet containing intervals in the specified list. Performs normalization if necessary.
      Parameters:
      intervals - specified list of intervals

  • Method Details

    • of

      public static IntervalSet of(Interval... intervals)
      Creates and returns a new instance of IntervalSet that contains the specified intervals. Performs normalization if necessary.
      Parameters:
      intervals - specified intervals of the newly created interval set
      Returns:
      a new instance of IntervalSet

    • of

      public static IntervalSet of(double min, double max)
      Creates and returns a new instance of IntervalSet containing a single interval with the specified min and max bounds.
      Parameters:
      min - minimal bound of the only interval of the newly created interval set
      max - maximal bound of the only interval of the newly created interval set
      Returns:
      a new instance of IntervalSet

    • of

      public static IntervalSet of(IntervalLike intervalLike)
      Converts the specified instance of IntervalLike to an instance of IntervalSet according to the following rules:
      • if the specified instance of IntervalLike is an instance of IntervalSet, just returns the reference to this instance, without creating any new instances
      • 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
      Parameters:
      intervalLike - specified instance of IntervalLike
      Returns:
      either existing or new instance of IntervalSet

    • ofSlots

      public static IntervalSet ofSlots(Sequence<? extends Slot> sequence)

    • ofGaps

      public static IntervalSet ofGaps(Sequence<? extends Slot> sequence)

    • union

      public IntervalSet union(IntervalLike other)
      Description copied from interface: IntervalLike
      Returns a new instance of IntervalSet that represents a union of this instance and the specified other one.
      Specified by:
      union in interface IntervalLike
      Parameters:
      other - specified other IntervalLike instance
      Returns:
      new instance of IntervalSet that represents a union of this instance and the specified other one.

    • exclusion

      public IntervalSet exclusion(IntervalLike other)
      Description copied from interface: IntervalLike
      Returns a new instance of IntervalSet that represents an exclusion of the specified instance from this one.
      Specified by:
      exclusion in interface IntervalLike
      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

    • hasNonZeroIntersectionWith

      public boolean hasNonZeroIntersectionWith(IntervalLike other)
      Description copied from interface: IntervalLike
      Checks whether this IntervalLike instance has a non-zero length intersection with the specified other one.

      Calling this method instead of IntervalLike.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.

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

    • intersection

      public IntervalSet intersection(IntervalLike other)
      Description copied from interface: IntervalLike
      Returns a new instance of IntervalSet that represents an intersection of this instance and the specified other one.
      Specified by:
      intersection in interface IntervalLike
      Parameters:
      other - specified other IntervalLike instance
      Returns:
      new instance of IntervalSet that represents an intersection of this instance and the specified other one

    • contains

      public boolean contains(IntervalLike other)
      Description copied from interface: IntervalLike
      Checks whether this IntervalLike instance contains (i.e., fully covers) the specified other one.
      Specified by:
      contains in interface IntervalLike
      Parameters:
      other - specified other IntervalLike instance
      Returns:
      true if this IntervalLike instance contains (i.e., fully covers) the specified other one, false otherwise

    • withoutZeroIntervals

      public IntervalSet withoutZeroIntervals()
      Returns a new instance of IntervalSet that is computed from this instance by removing all zero-length intervals.
      Returns:
      new instance of IntervalSet that is computed from this instance by removing all zero-length intervals

    • withIntervalsMatching

      public IntervalSet withIntervalsMatching(Predicate<Interval> predicate)
      Returns a new IntervalSet instance containing only those intervals that match the specified predicate condition. This method does not modify the current instance.
      Parameters:
      predicate - A Predicate<Interval> that defines the condition each interval must satisfy to be included in the resultant IntervalSet
      Returns:
      A new IntervalSet instance containing only the intervals that match the predicate condition

    • withoutIntervalsMatching

      public IntervalSet withoutIntervalsMatching(Predicate<Interval> predicate)
      Returns a new IntervalSet instance excluding the intervals that match the specified predicate condition. This method does not modify the current instance.
      Parameters:
      predicate - A Predicate<Interval> that defines the condition each interval must satisfy to be excluded from the resultant IntervalSet
      Returns:
      A new IntervalSet instance containing only the intervals that do not satisfy the predicate condition

    • firstInterval

      public Optional<Interval> firstInterval()
      Returns an Optional containing the first (leftmost) interval of this set, or Optional.empty() if this set is empty.
      Returns:
      Optional containing the first (leftmost) interval if it exists

    • lastInterval

      public Optional<Interval> lastInterval()
      Returns an Optional containing the last (rightmost) interval of this set, or Optional.empty() if this set is empty.
      Returns:
      Optional containing the last (rightmost) interval if it exists

    • intervals

      public List<Interval> intervals()
      Returns an unmodifiable list of intervals contained in this interval set.
      Returns:
      unmodifiable list of intervals

    • min

      public double min()
      Description copied from interface: IntervalLike
      Returns the minimal (left) bound of interval or interval set, or Double.NaN if this instance is empty.
      Specified by:
      min in interface IntervalLike
      Returns:
      left bound of interval or interval set, can be infinite or Double.NaN

    • max

      public double max()
      Description copied from interface: IntervalLike
      Returns the maximal (right) bound of interval or interval set, or Double.NaN if this instance is empty.
      Specified by:
      max in interface IntervalLike
      Returns:
      right bound of interval or interval set, can be infinite or Double.NaN

    • length

      public double length()
      Description copied from interface: IntervalLike
      Returns the length of this IntervalLike instance, more specifically:
      Specified by:
      length in interface IntervalLike
      Returns:
      length of this IntervalLike instance, zero or a positive number, or a Dobule.POSITIVE_INFINITY

    • size

      public int size()
      Description copied from interface: IntervalLike
      Returns the number of intervals for interval set, or 1 for interval. If this instance is empty (IntervalLike.isEmpty() == true), returns 0.
      Specified by:
      size in interface IntervalLike
      Returns:
      number of intervals for interval set, or 1 for interval, or 0

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: IntervalLike
      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());
      Specified by:
      isEmpty in interface IntervalLike
      Returns:
      true if this instance is an empty interval or interval set, false otherwise
      See Also:

    • isUniverse

      public boolean isUniverse()
      Description copied from interface: IntervalLike
      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.
      Specified by:
      isUniverse in interface IntervalLike
      Returns:
      true if this instance is a universe interval or interval set, false otherwise

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • iterator

      public ListIterator<Interval> iterator()
      Specified by:
      iterator in interface Iterable<Interval>

    • toCodeString

      public String toCodeString()
      Description copied from interface: IntervalLike
      Returns a Java code that creates an IntervalLike equal to this one. Can be used, for example, for unit testing and debugging.
      Specified by:
      toCodeString in interface IntervalLike
      Returns:
      string representing a Java code that creates an IntervalLike equal to this one

    • leftSubset

      public IntervalSet leftSubset(double maxLength)
      Description copied from interface: IntervalLike
      Returns a new instance of IntervalSet that is a subset of this IntervalLike instance taken from its IntervalLike.min() boundary, with the cumulative length not exceeding the specified maximum length. If IntervalLike.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.

      Specified by:
      leftSubset in interface IntervalLike
      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

      public IntervalSet rightSubset(double maxLength)
      Description copied from interface: IntervalLike
      Returns a new instance of IntervalSet that is a subset of this IntervalLike instance taken from its IntervalLike.max() boundary, with the cumulative length not exceeding the specified maximum length. If IntervalLike.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.

      Specified by:
      rightSubset in interface IntervalLike
      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

    • isZeroLength

      public boolean isZeroLength()
      Description copied from interface: IntervalLike
      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 IntervalLike.isEmpty() method for details on the difference between empty and zero-length intervals and interval sets.
      Specified by:
      isZeroLength in interface IntervalLike
      Returns:
      true if this IntervalLike instance has zero length, false otherwise
      See Also:

    • equalsWithinEpsilon

      public boolean equalsWithinEpsilon(IntervalLike other)
      Description copied from interface: IntervalLike
      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.
      Specified by:
      equalsWithinEpsilon in interface IntervalLike
      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

      public boolean equalsWithinEpsilon(IntervalLike other, EpsilonComparator comparator)
      Description copied from interface: IntervalLike
      Checks whether this IntervalLike instance is equal to the specified other one with respect to the epsilon specified in the EpsilonComparator instance.
      Specified by:
      equalsWithinEpsilon in interface IntervalLike
      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