Class Range<T>
- Type Parameters:
T- The type of range values.
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
NumberRange
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 -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final Comparator<T>The ordering scheme used in this range.private intCached output hashCode (class is immutable).private final TThe maximum value in this range (inclusive).private final TThe minimum value in this range (inclusive).private static final longSerialization version.private StringCached output toString (class is immutable). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic <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) Deprecated.booleanChecks whether the specified element occurs within this range.booleancontainsRange(Range<T> otherRange) Checks whether this range contains all the elements of the specified range.intelementCompareTo(T element) Checks where the specified element occurs relative to this range.booleanCompares this range to another object to test if they are equal.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 intinthashCode()Gets a suitable hash code for the range.intersectionWith(Range<T> other) Calculate the intersection ofthisand 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.booleanTests whether this range is after the specified element.booleanisAfterRange(Range<T> otherRange) Tests whether this range is completely after the specified range.booleanTests whether this range is before the specified element.booleanisBeforeRange(Range<T> otherRange) Tests whether this range is completely before the specified range.booleanTests whether this range ends with the specified element.private static booleanTests whether the element is a floating-point NaN.booleanTests whether or not the Range is using the natural ordering of the elements.booleanisOverlappedBy(Range<T> otherRange) Tests whether this range is overlapped by the specified range.booleanisStartedBy(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 voidValidates the endpoints and comparator and recomputes the cached hash code after deserialization.private static voidrequireNotNaN(Object element, String name) Validates that a floating-point endpoint is not NaN, mirroring the fail-closed posture ofValidate.notNaN(double, String, Object...).toString()Gets the range as aString.Formats the receiver using the given format.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerialization version.- See Also:
-
comparator
The ordering scheme used in this range. -
hashCode
private transient int hashCodeCached output hashCode (class is immutable). -
maximum
The maximum value in this range (inclusive). -
minimum
The minimum value in this range (inclusive). -
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 nullcomp- 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 notComparable.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) Deprecated.Creates a range with the specified minimum and maximum values (both inclusive).The range uses the specified
Comparatorto 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 notComparable.IllegalArgumentException- Thrown if either element is a floating-point NaN.
-
hash
-
is
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 notComparable.IllegalArgumentException- Thrown if the element is a floating-point NaN.
-
is
Creates a range using the specified element as both the minimum and maximum in this range.The range uses the specified
Comparatorto 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 benull.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 notComparable.IllegalArgumentException- Thrown if the element is a floating-point NaN.
-
isNaN
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 whosecontains/fitaccept every value above the minimum.- Parameters:
element- The element to test, may be null.- Returns:
- Whether the element is a floating-point NaN.
-
of
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 notComparable.IllegalArgumentException- Thrown if either element is a floating-point NaN.- Since:
- 3.13.0
-
of
Creates a range with the specified minimum and maximum values (both inclusive).The range uses the specified
Comparatorto 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 notComparable.IllegalArgumentException- Thrown if either element is a floating-point NaN.- Since:
- 3.13.0
-
requireNotNaN
Validates that a floating-point endpoint is not NaN, mirroring the fail-closed posture ofValidate.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
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
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
Checks where the specified element occurs relative to this range.The API is reminiscent of the Comparable interface returning
-1if the element is before the range,0if contained within the range and1if 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 ifelementisnull.
-
equals
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.
-
fit
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 ifelementisnull.- Since:
- 3.10
-
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
Gets the maximum value in this range.- Returns:
- The maximum value in this range, not null.
-
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. -
intersectionWith
Calculate the intersection ofthisand an overlapping Range.- Parameters:
other- overlapping Range.- Returns:
- range representing the intersection of
thisandother(thisif equal). - Throws:
IllegalArgumentException- Thrown ifotherdoes not overlapthis.- Since:
- 3.0.1
-
isAfter
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
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
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
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
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
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
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
Validates the endpoints and comparator and recomputes the cached hash code after deserialization.- Parameters:
in- SeeSerializable.- Throws:
IOException- Thrown as described inSerializable.ClassNotFoundException- Thrown as described inSerializable.InvalidObjectException- Thrown if the endpoints or comparator violate the range invariants.
-
toString
Gets the range as aString.The format of the String is '[min..max]'.
-
toString
Formats the receiver using the given format.This uses
Formattableto perform the formatting. Three variables may be used to embed the minimum, maximum and comparator. Use%1$sfor the minimum element,%2$sfor the maximum element and%3$sfor the comparator. The default format used bytoString()is[%1$s..%2$s].- Parameters:
format- The format string, optionally containing%1$s,%2$sand%3$s, not null.- Returns:
- The formatted string, not null.
-
of(Comparable, Comparable).