Package io.permazen.util

Class Bounds<T>

java.lang.Object
io.permazen.util.Bounds<T>
Type Parameters:
T - Java type of range bounds
public class Bounds<T> extends Object
Utility class used by AbstractNavigableSet and AbstractNavigableMap to define the (optional) upper and lower bounds of a restricted range.

Instances are immutable.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Bounds()
    Convenience constructor to create an unbounded instance, i.e., having neither upper nor lower bounds.
    Bounds(T lowerBound, boolean lowerInclusive, T upperBound, boolean upperInclusive)
    Create two-sided bounds.
    Bounds(T bound, BoundType boundType, boolean upper)
    Create a one-sided bound.
    Bounds(T lowerBound, BoundType lowerBoundType, T upperBound, BoundType upperBoundType)
    Primary constructor.
    Bounds(T lowerBound, T upperBound)
    Create two-sided bounds with inclusive lower bound and exclusive upper bound.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Bounds<T>
    eq(T value)
    Create an instance with bounds that allow only the given value.
    boolean
    equals(Object obj)
     
    static <T> Bounds<T>
    ge(T lowerBound)
    Create an instance with an inclusive lower bound.
    T
    getLowerBound()
    Get the Java value corresponding to the lower bound restriction, if any.
    BoundType
    getLowerBoundType()
    Get the type of the lower bound that corresponds to getLowerBound().
    T
    getUpperBound()
    Get the Java value corresponding to the upper bound restriction, if any.
    BoundType
    getUpperBoundType()
    Get the type of the upper bound that corresponds to getUpperBound().
    static <T> Bounds<T>
    gt(T lowerBound)
    Create an instance with an exclusive lower bound.
    int
    hashCode()
     
    boolean
    hasLowerBound()
    Determine whether this instance has a lower bound.
    boolean
    hasUpperBound()
    Determine whether this instance has an upper bound.
    boolean
    isEmpty(Comparator<? super T> comparator)
    Determine if this instance is provably empty, i.e., no values can possibly be within the bounds.
    boolean
    isInverted(Comparator<? super T> comparator)
    Determine if this instance has bounds that are "inverted" with respect to the given Comparator.
    boolean
    isUnbounded()
    Determine whether this instance is unbounded, i.e., it has neither a lower nor an upper bound.
    boolean
    isWithinBounds(Comparator<? super T> comparator, Bounds<? extends T> other)
    Determine whether the given Bounds are within of the bounds of this instance.
    boolean
    isWithinBounds(Comparator<? super T> comparator, T value)
    Check whether the given value is within the bounds of this instance.
    boolean
    isWithinLowerBound(Comparator<? super T> comparator, T value)
    Check whether the given value is within the lower bound of this instance.
    boolean
    isWithinUpperBound(Comparator<? super T> comparator, T value)
    Check whether the given value is within the upper bound of this instance.
    static <T> Bounds<T>
    le(T upperBound)
    Create an instance with an inclusive upper bound.
    static <T> Bounds<T>
    lt(T upperBound)
    Create an instance with an exclusive upper bound.
    Bounds<T>
    reverse()
    Create an instance like this instance but with the upper and lower bounds reversed.
    String
    toString()
     
    Bounds<T>
    union(Comparator<? super T> comparator, Bounds<T> other)
    Consolidate the ranges of values implied by this instance and the given instance, if possible.
    Bounds<T>
    withLowerBound(T newLowerBound, BoundType newLowerBoundType)
    Create an instance like this instance but with a different lower bound.
    Bounds<T>
    withoutLowerBound()
    Create an instance like this instance but with the lower bound removed.
    Bounds<T>
    withoutUpperBound()
    Create an instance like this instance but with the upper bound removed.
    Bounds<T>
    withUpperBound(T newUpperBound, BoundType newUpperBoundType)
    Create an instance like this instance but with a different upper bound.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Bounds

      public Bounds()
      Convenience constructor to create an unbounded instance, i.e., having neither upper nor lower bounds.

    • Bounds

      public Bounds(T bound, BoundType boundType, boolean upper)
      Create a one-sided bound.
      Parameters:
      bound - bound restriction value; ignored if boundType is BoundType.NONE
      boundType - type of bound for bound, or BoundType.NONE if there is no lower bound
      upper - true to create an upper bound, false to create a lower bound
      Throws:
      IllegalArgumentException - if boundType is null

    • Bounds

      public Bounds(T lowerBound, T upperBound)
      Create two-sided bounds with inclusive lower bound and exclusive upper bound.
      Parameters:
      lowerBound - lower bound restriction value (inclusive)
      upperBound - upper bound restriction value (exclusive)

    • Bounds

      public Bounds(T lowerBound, boolean lowerInclusive, T upperBound, boolean upperInclusive)
      Create two-sided bounds.
      Parameters:
      lowerBound - lower bound restriction value (inclusive)
      lowerInclusive - true if lowerBound is inclusive, false if lowerBound is exclusive
      upperBound - upper bound restriction value (exclusive)
      upperInclusive - true if upperBound is inclusive, false if upperBound is exclusive

    • Bounds

      public Bounds(T lowerBound, BoundType lowerBoundType, T upperBound, BoundType upperBoundType)
      Primary constructor.
      Parameters:
      lowerBound - lower bound restriction value; ignored if lowerBoundType is BoundType.NONE
      lowerBoundType - type of bound for lowerBound, or BoundType.NONE if there is no lower bound
      upperBound - upper bound restriction value; ignored if upperBoundType is BoundType.NONE
      upperBoundType - type of bound for upperBound, or BoundType.NONE if there is no upper bound
      Throws:
      IllegalArgumentException - if lowerBoundType or upperBoundType is null

  • Method Details

    • hasLowerBound

      public boolean hasLowerBound()
      Determine whether this instance has a lower bound.
      Returns:
      false if this instance's lower bound type is BoundType.NONE, otherwise true

    • hasUpperBound

      public boolean hasUpperBound()
      Determine whether this instance has an upper bound.
      Returns:
      false if this instance's upper bound type is BoundType.NONE, otherwise true

    • isUnbounded

      public boolean isUnbounded()
      Determine whether this instance is unbounded, i.e., it has neither a lower nor an upper bound.
      Returns:
      true if this instance has neither bounds, otherwise false

    • getLowerBound

      public T getLowerBound()
      Get the Java value corresponding to the lower bound restriction, if any. Returns null when getLowerBoundType() returns BoundType.NONE.
      Returns:
      lower bound Java value, or null if there is no lower bound

    • getUpperBound

      public T getUpperBound()
      Get the Java value corresponding to the upper bound restriction, if any. Returns null when getUpperBoundType() returns BoundType.NONE.
      Returns:
      upper bound Java value, or null if there is no upper bound

    • getLowerBoundType

      public BoundType getLowerBoundType()
      Get the type of the lower bound that corresponds to getLowerBound().
      Returns:
      lower bound restriction type, never null

    • getUpperBoundType

      public BoundType getUpperBoundType()
      Get the type of the upper bound that corresponds to getUpperBound().
      Returns:
      upper bound restriction type, never null

    • reverse

      public Bounds<T> reverse()
      Create an instance like this instance but with the upper and lower bounds reversed. Obviously, the result is only sensible when a reversed Comparator is also used.
      Returns:
      reversal of this instance

    • withLowerBound

      public Bounds<T> withLowerBound(T newLowerBound, BoundType newLowerBoundType)
      Create an instance like this instance but with a different lower bound.
      Parameters:
      newLowerBound - new lower bound restriction value; ignored if newLowerBoundType is BoundType.NONE
      newLowerBoundType - type of bound for newLowerBound, or BoundType.NONE if there is no lower bound
      Returns:
      instance with new lower bound
      Throws:
      IllegalArgumentException - if newLowerBoundType is null

    • withUpperBound

      public Bounds<T> withUpperBound(T newUpperBound, BoundType newUpperBoundType)
      Create an instance like this instance but with a different upper bound.
      Parameters:
      newUpperBound - new upper bound restriction value; ignored if newUpperBoundType is BoundType.NONE
      newUpperBoundType - type of bound for newUpperBound, or BoundType.NONE if there is no upper bound
      Returns:
      instance with new upper bound
      Throws:
      IllegalArgumentException - if newUpperBoundType is null

    • withoutLowerBound

      public Bounds<T> withoutLowerBound()
      Create an instance like this instance but with the lower bound removed.
      Returns:
      new instance

    • withoutUpperBound

      public Bounds<T> withoutUpperBound()
      Create an instance like this instance but with the upper bound removed.
      Returns:
      new instance

    • isWithinLowerBound

      public boolean isWithinLowerBound(Comparator<? super T> comparator, T value)
      Check whether the given value is within the lower bound of this instance.
      Parameters:
      comparator - comparator used to compare values, or null for natural ordering
      value - value to check
      Returns:
      true if value is within bounds, false otherwise

    • isWithinUpperBound

      public boolean isWithinUpperBound(Comparator<? super T> comparator, T value)
      Check whether the given value is within the upper bound of this instance.
      Parameters:
      comparator - comparator used to compare values, or null for natural ordering
      value - value to check
      Returns:
      true if value is within bounds, false otherwise

    • isWithinBounds

      public boolean isWithinBounds(Comparator<? super T> comparator, T value)
      Check whether the given value is within the bounds of this instance.

      Equivalent to: 

       isWithinLowerBound(comparator, value) && isWithinUpperBound(comparator, value)
      Parameters:
      comparator - comparator used to compare values, or null for natural ordering
      value - value to check
      Returns:
      true if value is within bounds, false otherwise

    • isWithinBounds

      public boolean isWithinBounds(Comparator<? super T> comparator, Bounds<? extends T> other)
      Determine whether the given Bounds are within of the bounds of this instance.
      Parameters:
      comparator - comparator used to compare values, or null for natural ordering
      other - other bounds
      Returns:
      true if other is in range, false otherwise
      Throws:
      IllegalArgumentException - if other is null

    • union

      public Bounds<T> union(Comparator<? super T> comparator, Bounds<T> other)
      Consolidate the ranges of values implied by this instance and the given instance, if possible.

      If the value ranges implied by the two bounds are not overlapping or adjacent, then null is returned. Otherwise an instance is returned that corresponds to the union of the two implied value ranges.

      Some cases not handled, e.g., when one bound has an inclusive upper bound with value x and the other has an inclusive lower bound with value x + 1, because this method can't detect adjacent values.

      Parameters:
      comparator - comparator used to compare values, or null for natural ordering
      other - instance to attempt consolidation with this one
      Returns:
      consolidated bounds, or null if none is possible
      Throws:
      IllegalArgumentException - if other is null

    • isEmpty

      public boolean isEmpty(Comparator<? super T> comparator)
      Determine if this instance is provably empty, i.e., no values can possibly be within the bounds.
      Parameters:
      comparator - comparator used to compare values, or null for natural ordering
      Returns:
      true if this instance is backwards

    • isInverted

      public boolean isInverted(Comparator<? super T> comparator)
      Determine if this instance has bounds that are "inverted" with respect to the given Comparator.

      This instance is "inverted" if it has both lower and upper bounds and the lower bound's value is strictly greater than the upper bound's value. The bounds' types (i.e., whether BoundType.INCLUSIVE or BoundType.EXCLUSIVE) is not considered.

      An inverted instance is always empty, but the reverse is not necessarily true.

      Parameters:
      comparator - comparator used to compare values, or null for natural ordering
      Returns:
      true if this instance is backwards

    • eq

      public static <T> Bounds<T> eq(T value)
      Create an instance with bounds that allow only the given value.
      Type Parameters:
      T - Java type of range bounds
      Parameters:
      value - unique bounded value
      Returns:
      bounds containing exactly value

    • ge

      public static <T> Bounds<T> ge(T lowerBound)
      Create an instance with an inclusive lower bound.
      Type Parameters:
      T - Java type of range bounds
      Parameters:
      lowerBound - inclusive lower bound
      Returns:
      bounds containing all values greater than or equal to value

    • gt

      public static <T> Bounds<T> gt(T lowerBound)
      Create an instance with an exclusive lower bound.
      Type Parameters:
      T - Java type of range bounds
      Parameters:
      lowerBound - exclusive lower bound
      Returns:
      bounds containing all values greater than value

    • le

      public static <T> Bounds<T> le(T upperBound)
      Create an instance with an inclusive upper bound.
      Type Parameters:
      T - Java type of range bounds
      Parameters:
      upperBound - inclusive upper bound
      Returns:
      bounds containing all values less than or equal to value

    • lt

      public static <T> Bounds<T> lt(T upperBound)
      Create an instance with an exclusive upper bound.
      Type Parameters:
      T - Java type of range bounds
      Parameters:
      upperBound - exclusive upper bound
      Returns:
      bounds containing all values less than value

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object