Package com.amalgamasimulation.core.intervals

Class Interval

java.lang.Object
com.amalgamasimulation.core.intervals.Interval
All Implemented Interfaces:
IntervalLike, Comparable<IntervalLike>
Direct Known Subclasses:
TimeInterval
public class Interval extends Object implements IntervalLike
Class representing a number interval, i.e. a continuous set of numbers from minimum to maximum values, [min(), max()]. One or both of these values may be infinite although not with the same sign.

Intervals can have zero length, such intervals represent a single point. IntervalLike.isZeroLength() method checks if the interval has zero length

Empty interval represents a non-existent interval, such as a result of intersection of disjoint intervals. isEmpty() method can be used to check is an interval is empty.

Author:
Andrey Malykhanov

  • Field Details

    • min

      protected double min

    • max

      protected double max

    • UNIVERSE

      public static final Interval UNIVERSE
      Universe number interval, i.e. [-∞, +∞].

    • EMPTY

      public static final Interval EMPTY
      Empty number interval that represents a non-existent interval.

  • Constructor Details

    • Interval

      public Interval(double min, double max)
      Creates a new instance of Interval with the specified minimal and maximal bounds.

      If at least one of the bound is Double.NaN, then an empty interval is created. Also, if both bounds either equal to Double.POSITIVE_INFINITY, or Double.NEGATIVE_INFINITY, then an empty interval is created.

      If the difference between the specified bounds is less that the default epsilon, i.e., Compare.equalTo(min, max) == true, then a zero-length interval is created with max = min

      If maximal bound is less than minimal bound, an IllegalArgumentException is thrown.

      Parameters:
      min - minimal (left) bound of the interval being created
      max - maximal (right) bound of the interval being created

  • Method Details

    • of

      public static Interval of(double min, double max)
      Creates a new instance of Interval with the specified minimal and maximal bounds.
      Parameters:
      min - minimal (left) bound of the interval being created
      max - maximal (right) bound of the interval being created
      Returns:
      a new instance of Interval

    • of

      public static Interval of(double value)
      Creates a new instance of Interval which is zero-length and contains only the specified point.
      Parameters:
      value - value of the zero-length interval
      Returns:
      a new instance of Interval

    • shift

      public Interval shift(double shift)
      Creates a new instance of Interval which equals to this interval shifted by the specified value.
      Parameters:
      shift - shift, can be zero, positive or negative, cannot be Double.NaN or infinite
      Returns:
      new instance of Interval which equals to this interval shifted by the specified value

    • 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

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

    • 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

    • 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

    • 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

    • asIntervalSet

      public IntervalSet asIntervalSet()
      Description copied from interface: IntervalLike
      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
      Specified by:
      asIntervalSet in interface IntervalLike
      Returns:
      either existing or new instance of of IntervalSet

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

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

    • 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

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • 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