T
- the range typepublic final class CircularRange<T> extends Object implements Serializable
A range from a possible set of values that rolls over when defined circular
start and end is reached. Because the range is circular, there is no
concept of before and after and maximum range can be smaller than minimum.
Otherwise similar to Apache Commons Lang Range
class.
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 also
serving as circular start and end (all inclusive).
|
static <T> CircularRange<T> |
between(T fromInclusive,
T toInclusive,
Comparator<T> comparator)
Obtains a range with the specified minimum and maximum values also
serving as circular start and end (all inclusive).
|
static <T extends Comparable<T>> |
between(T circleStartInclusive,
T circleEndInclusive,
T rangeFromInclusive,
T rangeToInclusive)
Obtains a range with the specified minimum and maximum values
and circular start and end values (all inclusive).
|
static <T> CircularRange<T> |
between(T circleStartInclusive,
T circleEndInclusive,
T rangeFromInclusive,
T rangeToInclusive,
Comparator<T> comparator)
Obtains a range with the specified minimum and maximum values
and circular start and end values (all inclusive).
|
boolean |
contains(T element)
Checks whether the specified element occurs within this range.
|
boolean |
containsRange(CircularRange<T> otherRange)
Checks whether this range contains all the elements of the
specified range.
|
boolean |
equals(Object obj)
Compares this range to another object to test if they are equal.
|
T |
getCircleEnd()
Gets the end value of this circular range.
|
T |
getCircleStart()
Gets the start value of this circular range.
|
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.
|
static <T extends Comparable<T>> |
is(T element)
Obtains a range using the specified element as both the minimum
and maximum in this range and as both circular start and end.
|
static <T> CircularRange<T> |
is(T element,
Comparator<T> comparator)
Obtains a range using the specified element as both the minimum
and maximum in this range and as both circular start and end.
|
boolean |
isEndedBy(T element)
Checks whether this range ends with the specified element.
|
boolean |
isNaturalOrdering()
Whether or not the CircularRange is using the natural ordering of
the elements.
|
boolean |
isOverlappedBy(CircularRange<T> otherRange)
Checks whether this range is overlapped by the specified range.
|
boolean |
isRolling()
Whether or not the range rolls over the circular end.
|
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.
|
CircularRange<T> |
withCircularBoundaries(T circleStartInclusive,
T circleEndInclusive)
Obtains a new range with the specified circular start and end
values (both inclusive).
|
CircularRange<T> |
withRange(T rangeFromInclusive,
T rangeToInclusive)
Obtains a new range with the specified minimum and maximum range
values (both inclusive).
|
public static <T extends Comparable<T>> CircularRange<T> is(T element)
Obtains a range using the specified element as both the minimum and maximum in this range and as both circular start and end.
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> CircularRange<T> is(T element, Comparator<T> comparator)
Obtains a range using the specified element as both the minimum and maximum in this range and as both circular start and end.
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 static <T extends Comparable<T>> CircularRange<T> between(T fromInclusive, T toInclusive)
Obtains a range with the specified minimum and maximum values also serving as circular start and end (all inclusive).
The range uses the natural ordering of the elements to determine where values lie in the range.
The arguments must be passed in order (min,max).
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 null or not in orderClassCastException
- if the elements are not Comparable
public static <T> CircularRange<T> between(T fromInclusive, T toInclusive, Comparator<T> comparator)
Obtains a range with the specified minimum and maximum values also serving as circular start and end (all inclusive).
The range uses the specified Comparator
to determine where
values lie in the range.
The arguments must be passed in order (min,max).
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>> CircularRange<T> between(T circleStartInclusive, T circleEndInclusive, T rangeFromInclusive, T rangeToInclusive)
Obtains a range with the specified minimum and maximum values and circular start and end values (all inclusive).
The range uses the natural ordering of the elements to determine where values lie in the range.
The circle arguments must be passed in order (min,max). The range arguments can be passed in any order (min,max or max,min). The order will be respected.
T
- the type of the elements in this rangerangeFromInclusive
- the first value that defines the edge of
the range, inclusiverangeToInclusive
- the second value that defines the edge of
the range, inclusivecircleStartInclusive
- the value that defines the circular start,
inclusivecircleEndInclusive
- the value that defines the circular end,
inclusiveIllegalArgumentException
- if either element is null or not in orderClassCastException
- if the elements are not Comparable
public static <T> CircularRange<T> between(T circleStartInclusive, T circleEndInclusive, T rangeFromInclusive, T rangeToInclusive, Comparator<T> comparator)
Obtains a range with the specified minimum and maximum values and circular start and end values (all inclusive).
The range uses the specified Comparator
to determine where
values lie in the range.
The circle arguments must be passed in order (min,max). The range arguments can be passed in any order (min,max or max,min). The order will be respected.
T
- the type of the elements in this rangerangeFromInclusive
- the first value that defines the edge of the
range, inclusiverangeToInclusive
- the second value that defines the edge of the
range, inclusivecircleStartInclusive
- the value that defines the circular start,
inclusivecircleEndInclusive
- the value that defines the circular end,
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 CircularRange<T> withCircularBoundaries(T circleStartInclusive, T circleEndInclusive)
Obtains a new range with the specified circular start and end values (both inclusive). The range values and comparator are the same.
circleStartInclusive
- the value that defines the circular start,
inclusivecircleEndInclusive
- the value that defines the circular end,
inclusiveIllegalArgumentException
- if either element is nullpublic CircularRange<T> withRange(T rangeFromInclusive, T rangeToInclusive)
Obtains a new range with the specified minimum and maximum range values (both inclusive). The circular start and end are the same.
rangeFromInclusive
- the first value that defines the edge of the
range, inclusiverangeToInclusive
- the second value that defines the edge of the
range, inclusiveIllegalArgumentException
- if either element is nullpublic T getMinimum()
Gets the minimum value in this range.
public T getMaximum()
Gets the maximum value in this range.
public T getCircleStart()
Gets the start value of this circular range.
public T getCircleEnd()
Gets the end value of this circular range.
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 boolean isNaturalOrdering()
Whether or not the CircularRange 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 isRolling()
Whether or not the range rolls over the circular end. Basically, if the range maximum is smaller than the minimum.
true
if rolling overpublic boolean contains(T element)
Checks whether the specified element occurs within this range.
element
- the element to check for, null returns falsepublic boolean isStartedBy(T element)
Checks whether this range starts with the specified element.
element
- the element to check for, null returns falsepublic boolean isEndedBy(T element)
Checks whether this range ends with the specified element.
element
- the element to check for, null returns falsepublic boolean containsRange(CircularRange<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 boolean isOverlappedBy(CircularRange<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 equals(Object obj)
Compares this range to another object to test if they are equal.
.To be equal, the minimum and maximum values as well as circular start and end values must be equal, which ignores any differences in the comparator.
public int hashCode()
Gets a suitable hash code for the range.
public String toString()
Gets the range as a String
.
The format of the String is '[min..max](start..end)'.
public String toString(String format)
Formats the receiver using the given format.
This uses Formattable
to perform the formatting.
Five variables may be used to embed the minimum, maximum, circular start,
circular end and comparator.
Use %1$s
for the minimum element,
%2$s
for the maximum element,
%3$s
for the circular start,
%4$s
for the circular end,
and %5$s
for the comparator.
The default format used by toString()
is
[%1$s..%2$s](%3$s..%4$s)
.
format
- the format string, optionally containing %1$s
,
%2$s
, %3$s
, %4$s
and %3$s
,
not nullCopyright © 2008–2021 Norconex Inc.. All rights reserved.