org.apache.commons.lang3

## 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:
    Serialized Form

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T extends Comparable<? super T>> Range<T>` | `between(T fromInclusive, T toInclusive)` Deprecated. Use `of(Comparable, Comparable)`.
    `static <T> Range<T>` | `between(T fromInclusive, T toInclusive, Comparator<T> comparator)` Deprecated. Use `of(Object, Object, 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` | `elementCompareTo(T element)` Checks where the specified element occurs relative to this range.
    `boolean` | `equals(Object obj)` Compares this range to another object to test if they are equal..
    `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.
    `Comparator<T>` | `getComparator()` Gets the comparator being used to determine if objects are within the range.
    `T` | `getMaximum()` Gets the maximum value in this range.
    `T` | `getMinimum()` Gets the minimum value in this range.
    `int` | `hashCode()` Gets a suitable hash code for the range.
    `Range<T>` | `intersectionWith(Range<T> other)` 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)` Checks whether this range is after the specified element.
    `boolean` | `isAfterRange(Range<T> otherRange)` Checks whether this range is completely after the specified range.
    `boolean` | `isBefore(T element)` Checks whether this range is before the specified element.
    `boolean` | `isBeforeRange(Range<T> otherRange)` Checks whether this range is completely before the specified range.
    `boolean` | `isEndedBy(T element)` Checks whether this range ends with the specified element.
    `boolean` | `isNaturalOrdering()` Whether or not the Range is using the natural ordering of the elements.
    `boolean` | `isOverlappedBy(Range<T> otherRange)` Checks whether this range is overlapped by the specified range.
    `boolean` | `isStartedBy(T element)` Checks 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).
    `String` | `toString()` Gets the range as a `String`.
    `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`

- - ### Method Detail

    - #### between

          @Deprecated
          public static <T extends Comparable<? super T>> Range<T> between(T fromInclusive,
                                                                                       T toInclusive)

      Deprecated. Use `of(Comparable, Comparable)`.
      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` - when fromInclusive is null.
        `NullPointerException` - when toInclusive is null.
        `ClassCastException` - if the elements are not `Comparable`

    - #### between

          @Deprecated
          public static <T> Range<T> between(T fromInclusive,
                                                         T toInclusive,
                                                         Comparator<T> comparator)

      Deprecated. Use `of(Object, Object, 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` - when fromInclusive is null.
        `NullPointerException` - when toInclusive is null.
        `ClassCastException` - if using natural ordering and the elements are not `Comparable`

    - #### 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` - if the element is null
        `ClassCastException` - if the element is not `Comparable`

    - #### 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` - if the element is null
        `ClassCastException` - if using natural ordering and the elements are not `Comparable`

    - #### 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` - if either element is null
        `ClassCastException` - if the elements are not `Comparable`
      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` - when fromInclusive is null.
        `NullPointerException` - when toInclusive is null.
        `ClassCastException` - if using natural ordering and the elements are not `Comparable`
      Since:
        3.13.0

    - #### 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` - 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` - 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` - 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` - if `other` does not overlap `this`
      Since:
        3.0.1

    - #### isAfter

          public boolean isAfter(T element)

      Checks 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)

      Checks 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` - if ranges cannot be compared

    - #### isBefore

          public boolean isBefore(T element)

      Checks 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)

      Checks 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` - if ranges cannot be compared

    - #### isEndedBy

          public boolean isEndedBy(T element)

      Checks 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()

      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)

      Checks 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` - if ranges cannot be compared

    - #### isStartedBy

          public boolean isStartedBy(T element)

      Checks 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

    - #### 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

Copyright © 2001–2023 The Apache Software Foundation. All rights reserved.