org.apache.commons.lang3
Class Range<T>

java.lang.Object
  extended by org.apache.commons.lang3.Range<T>
All Implemented Interfaces:
Serializable

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

Since:
3.0
Version:
$Id: Range.java 1147537 2011-07-17 06:10:37Z mbenson $
See Also:
Serialized Form

Method Summary
static
<T extends Comparable<T>>
Range<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.
 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>>
Range<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 starts 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.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

is

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.

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

is

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.

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

between

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.

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:
IllegalArgumentException - if either element is null
ClassCastException - if the elements are not Comparable

between

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.

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

getMinimum

public T getMinimum()

Gets the minimum value in this range.

Returns:
the minimum value in this range, not null

getMaximum

public T getMaximum()

Gets the maximum value in this range.

Returns:
the maximum value in this range, not null

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

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

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

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

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

isEndedBy

public boolean isEndedBy(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

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

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

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

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

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

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

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

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

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

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-2011 The Apache Software Foundation. All Rights Reserved.