Class Range<T>

java.lang.Object
org.apache.commons.lang3.Range<T>
Type Parameters:
T - The type of range values.
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
NumberRange

public class Range<T> extends Object implements Serializable
An immutable range of objects from a minimum to maximum point inclusive.

The objects need to either be implementations of Comparable or you need to supply a Comparator.

#ThreadSafe# if the objects and comparator are thread-safe.

Since:
3.0
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static enum 
     
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final Comparator<T>
    The ordering scheme used in this range.
    private int
    Cached output hashCode (class is immutable).
    private final T
    The maximum value in this range (inclusive).
    private final T
    The minimum value in this range (inclusive).
    private static final long
    Serialization version.
    private String
    Cached output toString (class is immutable).
  • Constructor Summary

    Constructors
    Constructor
    Description
    Range(T element1, T element2, Comparator<T> comp)
    Creates an instance.
  • Method Summary

    Modifier and Type
    Method
    Description
    static <T extends Comparable<? super T>>
    Range<T>
    between(T fromInclusive, T toInclusive)
    Deprecated.
    static <T> Range<T>
    between(T fromInclusive, T toInclusive, Comparator<T> comparator)
    boolean
    contains(T element)
    Checks whether the specified element occurs within this range.
    boolean
    containsRange(Range<T> otherRange)
    Checks whether this range contains all the elements of the specified range.
    int
    Checks where the specified element occurs relative to this range.
    boolean
    Compares this range to another object to test if they are equal.
    fit(T element)
    Fits the given element into this range by returning the given element or, if out of bounds, the range minimum if below, or the range maximum if above.
    Gets the comparator being used to determine if objects are within the range.
    Gets the maximum value in this range.
    Gets the minimum value in this range.
    private static int
    hash(Object value1, Object value2)
     
    int
    Gets a suitable hash code for the range.
    Calculate the intersection of this and an overlapping Range.
    static <T extends Comparable<? super T>>
    Range<T>
    is(T element)
    Creates a range using the specified element as both the minimum and maximum in this range.
    static <T> Range<T>
    is(T element, Comparator<T> comparator)
    Creates a range using the specified element as both the minimum and maximum in this range.
    boolean
    isAfter(T element)
    Tests whether this range is after the specified element.
    boolean
    isAfterRange(Range<T> otherRange)
    Tests whether this range is completely after the specified range.
    boolean
    isBefore(T element)
    Tests whether this range is before the specified element.
    boolean
    isBeforeRange(Range<T> otherRange)
    Tests whether this range is completely before the specified range.
    boolean
    isEndedBy(T element)
    Tests whether this range ends with the specified element.
    private static boolean
    isNaN(Object element)
    Tests whether the element is a floating-point NaN.
    boolean
    Tests whether or not the Range is using the natural ordering of the elements.
    boolean
    isOverlappedBy(Range<T> otherRange)
    Tests whether this range is overlapped by the specified range.
    boolean
    isStartedBy(T element)
    Tests whether this range starts with the specified element.
    static <T extends Comparable<? super T>>
    Range<T>
    of(T fromInclusive, T toInclusive)
    Creates a range with the specified minimum and maximum values (both inclusive).
    static <T> Range<T>
    of(T fromInclusive, T toInclusive, Comparator<T> comparator)
    Creates a range with the specified minimum and maximum values (both inclusive).
    private void
    Validates the endpoints and comparator and recomputes the cached hash code after deserialization.
    private static void
    requireNotNaN(Object element, String name)
    Validates that a floating-point endpoint is not NaN, mirroring the fail-closed posture of Validate.notNaN(double, String, Object...).
    Gets the range as a String.
    toString(String format)
    Formats the receiver using the given format.

    Methods inherited from class java.lang.Object

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

    • serialVersionUID

      private static final long serialVersionUID
      Serialization version.
      See Also:
    • comparator

      private final Comparator<T> comparator
      The ordering scheme used in this range.
    • hashCode

      private transient int hashCode
      Cached output hashCode (class is immutable).
    • maximum

      private final T maximum
      The maximum value in this range (inclusive).
    • minimum

      private final T minimum
      The minimum value in this range (inclusive).
    • toString

      private transient String toString
      Cached output toString (class is immutable).
  • Constructor Details

    • Range

      Range(T element1, T element2, Comparator<T> comp)
      Creates an instance.
      Parameters:
      element1 - The first element, not null.
      element2 - The second element, not null
      comp - The comparator to be used, null for natural ordering.
      Throws:
      NullPointerException - Thrown when element1 is null.
      NullPointerException - Thrown when element2 is null.
      IllegalArgumentException - Thrown when element1 or element2 is a floating-point NaN.
  • Method Details

    • between

      @Deprecated public static <T extends Comparable<? super T>> Range<T> between(T fromInclusive, T toInclusive)
      Deprecated.
      Creates a range with the specified minimum and maximum values (both inclusive).

      The range uses the natural ordering of the elements to determine where values lie in the range.

      The arguments may be passed in the order (min, max) or (max, min). The getMinimum and getMaximum methods will return the correct values.

      Type Parameters:
      T - The type of the elements in this range.
      Parameters:
      fromInclusive - The first value that defines the edge of the range, inclusive.
      toInclusive - The second value that defines the edge of the range, inclusive.
      Returns:
      The range object, not null.
      Throws:
      NullPointerException - Thrown when fromInclusive is null.
      NullPointerException - Thrown when toInclusive is null.
      ClassCastException - Thrown if the elements are not Comparable.
      IllegalArgumentException - Thrown if either element is a floating-point NaN.
    • between

      @Deprecated public static <T> Range<T> between(T fromInclusive, T toInclusive, Comparator<T> comparator)
      Creates a range with the specified minimum and maximum values (both inclusive).

      The range uses the specified Comparator to determine where values lie in the range.

      The arguments may be passed in the order (min, max) or (max, min). The getMinimum and getMaximum methods will return the correct values.

      Type Parameters:
      T - The type of the elements in this range.
      Parameters:
      fromInclusive - The first value that defines the edge of the range, inclusive.
      toInclusive - The second value that defines the edge of the range, inclusive.
      comparator - The comparator to be used, null for natural ordering.
      Returns:
      The range object, not null.
      Throws:
      NullPointerException - Thrown when fromInclusive is null.
      NullPointerException - Thrown when toInclusive is null.
      ClassCastException - Thrown if using natural ordering and the elements are not Comparable.
      IllegalArgumentException - Thrown if either element is a floating-point NaN.
    • hash

      private static int hash(Object value1, Object value2)
    • is

      public static <T extends Comparable<? super T>> Range<T> is(T element)
      Creates a range using the specified element as both the minimum and maximum in this range.

      The range uses the natural ordering of the elements to determine where values lie in the range.

      Type Parameters:
      T - The type of the elements in this range.
      Parameters:
      element - The value to use for this range, not null.
      Returns:
      The range object, not null.
      Throws:
      NullPointerException - Thrown if the element is null.
      ClassCastException - Thrown if the element is not Comparable.
      IllegalArgumentException - Thrown if the element is a floating-point NaN.
    • is

      public static <T> Range<T> is(T element, Comparator<T> comparator)
      Creates a range using the specified element as both the minimum and maximum in this range.

      The range uses the specified Comparator to determine where values lie in the range.

      Type Parameters:
      T - The type of the elements in this range.
      Parameters:
      element - The value to use for this range, must not be null.
      comparator - The comparator to be used, null for natural ordering.
      Returns:
      The range object, not null.
      Throws:
      NullPointerException - Thrown if the element is null.
      ClassCastException - Thrown if using natural ordering and the elements are not Comparable.
      IllegalArgumentException - Thrown if the element is a floating-point NaN.
    • isNaN

      private static boolean isNaN(Object element)
      Tests whether the element is a floating-point NaN. A NaN endpoint sorts above every value under the natural total order (Double.compareTo(Double) / Float.compareTo(Float)), silently producing a half-unbounded range whose contains/fit accept every value above the minimum.
      Parameters:
      element - The element to test, may be null.
      Returns:
      Whether the element is a floating-point NaN.
    • of

      public static <T extends Comparable<? super T>> Range<T> of(T fromInclusive, T toInclusive)
      Creates a range with the specified minimum and maximum values (both inclusive).

      The range uses the natural ordering of the elements to determine where values lie in the range.

      The arguments may be passed in the order (min, max) or (max, min). The getMinimum and getMaximum methods will return the correct values.

      Type Parameters:
      T - The type of the elements in this range.
      Parameters:
      fromInclusive - The first value that defines the edge of the range, inclusive.
      toInclusive - The second value that defines the edge of the range, inclusive.
      Returns:
      The range object, not null.
      Throws:
      NullPointerException - Thrown if either element is null.
      ClassCastException - Thrown if the elements are not Comparable.
      IllegalArgumentException - Thrown if either element is a floating-point NaN.
      Since:
      3.13.0
    • of

      public static <T> Range<T> of(T fromInclusive, T toInclusive, Comparator<T> comparator)
      Creates a range with the specified minimum and maximum values (both inclusive).

      The range uses the specified Comparator to determine where values lie in the range.

      The arguments may be passed in the order (min, max) or (max, min). The getMinimum and getMaximum methods will return the correct values.

      Type Parameters:
      T - The type of the elements in this range.
      Parameters:
      fromInclusive - The first value that defines the edge of the range, inclusive.
      toInclusive - The second value that defines the edge of the range, inclusive.
      comparator - The comparator to be used, null for natural ordering.
      Returns:
      The range object, not null.
      Throws:
      NullPointerException - Thrown when fromInclusive is null.
      NullPointerException - Thrown when toInclusive is null.
      ClassCastException - Thrown if using natural ordering and the elements are not Comparable.
      IllegalArgumentException - Thrown if either element is a floating-point NaN.
      Since:
      3.13.0
    • requireNotNaN

      private static void requireNotNaN(Object element, String name)
      Validates that a floating-point endpoint is not NaN, mirroring the fail-closed posture of Validate.notNaN(double, String, Object...).
      Parameters:
      element - The endpoint to validate.
      name - The parameter name for the exception message.
      Throws:
      IllegalArgumentException - Thrown if the endpoint is a floating-point NaN.
    • contains

      public boolean contains(T element)
      Checks whether the specified element occurs within this range.
      Parameters:
      element - The element to check for, null returns false.
      Returns:
      true if the specified element occurs within this range.
    • containsRange

      public boolean containsRange(Range<T> otherRange)
      Checks whether this range contains all the elements of the specified range.

      This method may fail if the ranges have two different comparators or element types.

      Parameters:
      otherRange - The range to check, null returns false.
      Returns:
      true if this range contains the specified range.
      Throws:
      RuntimeException - Thrown if ranges cannot be compared.
    • elementCompareTo

      public int elementCompareTo(T element)
      Checks where the specified element occurs relative to this range.

      The API is reminiscent of the Comparable interface returning -1 if the element is before the range, 0 if contained within the range and 1 if the element is after the range.

      Parameters:
      element - The element to check for, not null.
      Returns:
      -1, 0 or +1 depending on the element's location relative to the range.
      Throws:
      NullPointerException - Thrown if element is null.
    • equals

      public boolean equals(Object obj)
      Compares this range to another object to test if they are equal.

      To be equal, the minimum and maximum values must be equal, which ignores any differences in the comparator.

      Overrides:
      equals in class Object
      Parameters:
      obj - The reference object with which to compare.
      Returns:
      true if this object is equal.
    • fit

      public T fit(T element)
      Fits the given element into this range by returning the given element or, if out of bounds, the range minimum if below, or the range maximum if above.
      
       Range<Integer> range = Range.between(16, 64);
       range.fit(-9) -->  16
       range.fit(0)  -->  16
       range.fit(15) -->  16
       range.fit(16) -->  16
       range.fit(17) -->  17
       ...
       range.fit(63) -->  63
       range.fit(64) -->  64
       range.fit(99) -->  64
       
      Parameters:
      element - The element to check for, not null.
      Returns:
      The minimum, the element, or the maximum depending on the element's location relative to the range.
      Throws:
      NullPointerException - Thrown if element is null.
      Since:
      3.10
    • getComparator

      public Comparator<T> getComparator()
      Gets the comparator being used to determine if objects are within the range.

      Natural ordering uses an internal comparator implementation, thus this method never returns null. See isNaturalOrdering().

      Returns:
      The comparator being used, not null.
    • getMaximum

      public T getMaximum()
      Gets the maximum value in this range.
      Returns:
      The maximum value in this range, not null.
    • getMinimum

      public T getMinimum()
      Gets the minimum value in this range.
      Returns:
      The minimum value in this range, not null.
    • hashCode

      public int hashCode()
      Gets a suitable hash code for the range.
      Overrides:
      hashCode in class Object
      Returns:
      A hash code value for this object.
    • intersectionWith

      public Range<T> intersectionWith(Range<T> other)
      Calculate the intersection of this and an overlapping Range.
      Parameters:
      other - overlapping Range.
      Returns:
      range representing the intersection of this and other (this if equal).
      Throws:
      IllegalArgumentException - Thrown if other does not overlap this.
      Since:
      3.0.1
    • isAfter

      public boolean isAfter(T element)
      Tests whether this range is after the specified element.
      Parameters:
      element - The element to check for, null returns false.
      Returns:
      true if this range is entirely after the specified element.
    • isAfterRange

      public boolean isAfterRange(Range<T> otherRange)
      Tests whether this range is completely after the specified range.

      This method may fail if the ranges have two different comparators or element types.

      Parameters:
      otherRange - The range to check, null returns false.
      Returns:
      true if this range is completely after the specified range.
      Throws:
      RuntimeException - Thrown if ranges cannot be compared.
    • isBefore

      public boolean isBefore(T element)
      Tests whether this range is before the specified element.
      Parameters:
      element - The element to check for, null returns false.
      Returns:
      true if this range is entirely before the specified element.
    • isBeforeRange

      public boolean isBeforeRange(Range<T> otherRange)
      Tests whether this range is completely before the specified range.

      This method may fail if the ranges have two different comparators or element types.

      Parameters:
      otherRange - The range to check, null returns false.
      Returns:
      true if this range is completely before the specified range.
      Throws:
      RuntimeException - Thrown if ranges cannot be compared.
    • isEndedBy

      public boolean isEndedBy(T element)
      Tests whether this range ends with the specified element.
      Parameters:
      element - The element to check for, null returns false.
      Returns:
      true if the specified element occurs within this range.
    • isNaturalOrdering

      public boolean isNaturalOrdering()
      Tests whether or not the Range is using the natural ordering of the elements.

      Natural ordering uses an internal comparator implementation, thus this method is the only way to check if a null comparator was specified.

      Returns:
      true if using natural ordering.
    • isOverlappedBy

      public boolean isOverlappedBy(Range<T> otherRange)
      Tests whether this range is overlapped by the specified range.

      Two ranges overlap if there is at least one element in common.

      This method may fail if the ranges have two different comparators or element types.

      Parameters:
      otherRange - The range to test, null returns false.
      Returns:
      true if the specified range overlaps with this range; otherwise, false.
      Throws:
      RuntimeException - Thrown if ranges cannot be compared.
    • isStartedBy

      public boolean isStartedBy(T element)
      Tests whether this range starts with the specified element.
      Parameters:
      element - The element to check for, null returns false.
      Returns:
      true if the specified element occurs within this range.
    • readObject

      private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException
      Validates the endpoints and comparator and recomputes the cached hash code after deserialization.
      Parameters:
      in - See Serializable.
      Throws:
      IOException - Thrown as described in Serializable.
      ClassNotFoundException - Thrown as described in Serializable.
      InvalidObjectException - Thrown if the endpoints or comparator violate the range invariants.
    • toString

      public String toString()
      Gets the range as a String.

      The format of the String is '[min..max]'.

      Overrides:
      toString in class Object
      Returns:
      The String representation of this range.
    • toString

      public String toString(String format)
      Formats the receiver using the given format.

      This uses Formattable to perform the formatting. Three variables may be used to embed the minimum, maximum and comparator. Use %1$s for the minimum element, %2$s for the maximum element and %3$s for the comparator. The default format used by toString() is [%1$s..%2$s].

      Parameters:
      format - The format string, optionally containing %1$s, %2$s and %3$s, not null.
      Returns:
      The formatted string, not null.