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

java.lang.Object
  org.apache.commons.lang3.Range<T>

All Implemented Interfaces:

Serializable

public final class Range<T>
extends Object
implements Serializable

Range represents an immutable range of numbers of the same type.

The objects need to either be implementations of java.lang.Comparable or you need to supply a java.util.Comparator.

#ThreadSafe#

Since:

3.0

Version:

$Id: Range.java 967237 2010-07-23 20:08:57Z mbenson $

Author:

Apache Software Foundation

See Also:

Serialized Form

Method Summary

static <T extends Comparable<T>> Range<T>	between(T element1, T element2) Constructs a new Range with the specified minimum and maximum values (both inclusive).
static <T> Range<T>	between(T element1, T element2, Comparator<T> c) Constructs a new Range with the specified minimum and maximum values (both inclusive).
boolean	contains(T element) Tests whether the specified element occurs within this range.
boolean	containsRange(Range<T> range) Tests whether the specified range occurs entirely within this range.
boolean	elementAfter(T element) Tests whether the specified element occurs after this range.
boolean	elementBefore(T element) Tests whether the specified element occurs before this range.
int	elementCompareTo(T element) Tests 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 hashCode for the range.
static <T extends Comparable<T>> Range<T>	is(T element) Constructs a new Range using the specified element as both the minimum and maximum in this range.
static <T> Range<T>	is(T element, Comparator<T> c) Constructs a new Range using the specified element as both the minimum and maximum in this range.
boolean	isDefaultNaturalOrdering() Whether or not the Range is using the default natural comparison method to compare elements.
boolean	overlapsRange(Range<T> range) Tests whether the specified range overlaps with this range.
String	toString() Gets the range as a String.

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)

Constructs a new 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.

Parameters:

element - the value to use for this range, must not be null

Returns:

the new range object

Throws:

IllegalArgumentException - if the value is null

ClassCastException - if the value is not Comparable

between

public static <T extends Comparable<T>> Range<T> between(T element1,
                                                         T element2)

Constructs a new 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.

Parameters:

element1 - first value that defines the edge of the range, inclusive

element2 - second value that defines the edge of the range, inclusive

Returns:

the new range object

Throws:

IllegalArgumentException - if either value is null

ClassCastException - if either value is not Comparable

is

public static <T> Range<T> is(T element,
                              Comparator<T> c)

Constructs a new Range using the specified element as both the minimum and maximum in this range.

The range uses the passed in Comparator to determine where values lie in the range.

Parameters:

element - the value to use for this range, must not be null

c - comparator to be used

Returns:

the new range object

Throws:

IllegalArgumentException - if the value is null

between

public static <T> Range<T> between(T element1,
                                   T element2,
                                   Comparator<T> c)

Constructs a new Range with the specified minimum and maximum values (both inclusive).

The range uses the passed in 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.

Parameters:

element1 - first value that defines the edge of the range, inclusive

element2 - second value that defines the edge of the range, inclusive

c - comparator to be used

Returns:

the new range object

Throws:

IllegalArgumentException - if either value is null

getMinimum

public T getMinimum()

Gets the minimum value in this range.

Returns:

the minimum value in this range

getMaximum

public T getMaximum()

Gets the maximum value in this range.

Returns:

the maximum value in this range

getComparator

public Comparator<T> getComparator()

Gets the comparator being used to determine if objects are within the range.

Returns:

the comparator being used

isDefaultNaturalOrdering

public boolean isDefaultNaturalOrdering()

Whether or not the Range is using the default natural comparison method to compare elements.

Returns:

whether or not the default Comparator is in use

contains

public boolean contains(T element)

Tests whether the specified element occurs within this range.

null is handled and returns false.

Parameters:

element - the element to test, may be null

Returns:

true if the specified element occurs within this range

elementBefore

public boolean elementBefore(T element)

Tests whether the specified element occurs before this range.

null is handled and returns false.

Parameters:

element - the element to test, may be null

Returns:

true if the specified element occurs before this range

elementAfter

public boolean elementAfter(T element)

Tests whether the specified element occurs after this range.

null is handled and returns false.

Parameters:

element - the element to test, may be null

Returns:

true if the specified element occurs after this range

elementCompareTo

public int elementCompareTo(T element)

Tests 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 test

Returns:

-1, 0 or +1 depending on the element's location relative to the range

containsRange

public boolean containsRange(Range<T> range)

Tests whether the specified range occurs entirely within this range.

null is handled and returns false.

Parameters:

range - the range to test, may be null

Returns:

true if the specified range occurs entirely within this range; otherwise, false

Throws:

IllegalArgumentException - if the Range cannot be compared

overlapsRange

public boolean overlapsRange(Range<T> range)

Tests whether the specified range overlaps with this range.

null is handled and returns false.

Parameters:

range - the range to test, may be null

Returns:

true if the specified range overlaps with this range; otherwise, false

Throws:

IllegalArgumentException - if the Range cannot be compared

equals

public boolean equals(Object obj)

Compares this range to another object to test if they are equal.

.

To be equal, the class, minimum and maximum must be equal.

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 hashCode 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 'Range[min,max]'.

Overrides:

toString in class Object

Returns:

the String representation of this range