T
- The type of range values.public final 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
Modifier and Type | Method and Description |
---|---|
static <T extends Comparable<T>> |
between(T fromInclusive,
T toInclusive)
Obtains a range with the specified minimum and maximum values (both inclusive).
|
static <T> Range<T> |
between(T fromInclusive,
T toInclusive,
Comparator<T> comparator)
Obtains a range with the specified minimum and maximum values (both inclusive).
|
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<T>> |
is(T element)
Obtains 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)
Obtains 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.
|
String |
toString()
Gets the range as a
String . |
String |
toString(String format)
Formats the receiver using the given format.
|
public static <T extends Comparable<T>> Range<T> between(T fromInclusive, T toInclusive)
Obtains 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.
T
- the type of the elements in this rangefromInclusive
- the first value that defines the edge of the range, inclusivetoInclusive
- the second value that defines the edge of the range, inclusiveIllegalArgumentException
- if either element is nullClassCastException
- if the elements are not Comparable
public static <T> Range<T> between(T fromInclusive, T toInclusive, Comparator<T> comparator)
Obtains 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.
T
- the type of the elements in this rangefromInclusive
- the first value that defines the edge of the range, inclusivetoInclusive
- the second value that defines the edge of the range, inclusivecomparator
- the comparator to be used, null for natural orderingIllegalArgumentException
- if either element is nullClassCastException
- if using natural ordering and the elements are not Comparable
public static <T extends Comparable<T>> Range<T> is(T element)
Obtains 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.
T
- the type of the elements in this rangeelement
- the value to use for this range, not nullIllegalArgumentException
- if the element is nullClassCastException
- if the element is not Comparable
public static <T> Range<T> is(T element, Comparator<T> comparator)
Obtains 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.
T
- the type of the elements in this rangeelement
- the value to use for this range, must not be null
comparator
- the comparator to be used, null for natural orderingIllegalArgumentException
- if the element is nullClassCastException
- if using natural ordering and the elements are not Comparable
public boolean contains(T element)
Checks whether the specified element occurs within this range.
element
- the element to check for, null returns falsepublic 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.
otherRange
- the range to check, null returns falseRuntimeException
- if ranges cannot be comparedpublic 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.
element
- the element to check for, not nullpublic 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.
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()
.
public T getMaximum()
Gets the maximum value in this range.
public T getMinimum()
Gets the minimum value in this range.
public int hashCode()
Gets a suitable hash code for the range.
public Range<T> intersectionWith(Range<T> other)
this
and an overlapping Range.other
- overlapping Rangethis
and other
(this
if equal)IllegalArgumentException
- if other
does not overlap this
public boolean isAfter(T element)
Checks whether this range is after the specified element.
element
- the element to check for, null returns falsepublic 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.
otherRange
- the range to check, null returns falseRuntimeException
- if ranges cannot be comparedpublic boolean isBefore(T element)
Checks whether this range is before the specified element.
element
- the element to check for, null returns falsepublic 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.
otherRange
- the range to check, null returns falseRuntimeException
- if ranges cannot be comparedpublic boolean isEndedBy(T element)
Checks whether this range ends with the specified element.
element
- the element to check for, null returns falsepublic 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.
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.
otherRange
- the range to test, null returns falsefalse
RuntimeException
- if ranges cannot be comparedpublic boolean isStartedBy(T element)
Checks whether this range starts with the specified element.
element
- the element to check for, null returns falsepublic 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
element
- the element to check for, not nullpublic String toString()
Gets the range as a String
.
The format of the String is '[min..max]'.
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]
.
format
- the format string, optionally containing %1$s
, %2$s
and %3$s
, not nullCopyright © 2001–2020 The Apache Software Foundation. All rights reserved.