org.jaitools.numeric
Class Range<T extends Number & Comparable>

java.lang.Object
  org.jaitools.numeric.Range<T>

Type Parameters:

T -

public class Range<T extends Number & Comparable>
extends Object

Yet another numeric interval class. It is used with the RangeLookup operator but is also available for general use and does not depend on JAI classes.

Range is a generic class that can be used all Number types. A range is defined by its endpoints. If the min (lower bound) end-point is the same as the max (upper-bound) end-point then the range represents a point, also referred to as a degenerate interval.

An end-point can be positioned at a finite value, in which case it is said to be closed, or at positive or negative infinity, in which case it is said to be open. For finite end-points, a range can include or exclude the end-point. Included end-points correspond to square-brackets in interval notation, while excluded end-points correspond to round brackets.

The following rules apply to Float and Double NaN values...

• Float and Double NaN are considered equal
• Point intervals can have value NaN
• Proper intervals treat NaN at their lower end-point as negative infinity and at their upper end-point as positive infinity
• A test value of NaN can be equal to a point interval
• A test value of NaN will always be treated as outside a proper interval

Since:

1.0

Version:

$Id$

Author:

Michael Bedward

See Also:

RangeComparator, RangeLookupDescriptor

Nested Class Summary

static class

Range.Type Constants to specify whether a Range parameter defines included or excluded values.

Field Summary

static int	INF Integer flag value for positive infinity.
static int	NEG_INF Integer flag value for negative infinity.

Constructor Summary

Range(Range<T> other)
Creates a copy of another Range instance.

Range(T minValue, boolean minIncluded, T maxValue, boolean maxIncluded)
Creates a new Range with non-zero width (may be infinite).

Range(T value, int... inf)
Creates a new point (degenerate) range.

Method Summary

boolean	contains(T value) Tests if this range contains the specified, non-null value.
static <T extends Number & Comparable> Range<T>	create(T minValue, boolean minIncluded, T maxValue, boolean maxIncluded) Static create method.
static <T extends Number & Comparable> Range<T>	create(T value, int... inf) Creates a Range instance that is a point (degenerate) interval.
boolean	equals(Object obj) Tests for equality with another range.
T	getMax() Gets the maximum value of this range.
T	getMin() Gets the minimum value for this range.
int	hashCode()
boolean	intersects(Range<T> other) Tests if this range intersects another range.
boolean	isMaxClosed() Tests if this range has a bounded (closed) maximum value.
boolean	isMaxIncluded() Tests if the maximum range value is included in the range.
boolean	isMaxInf() Tests if the maximum value is positive infinity.
boolean	isMaxNegInf() Tests if the maximum value is negative infinity.
boolean	isMaxOpen() Tests if this range has unbounded (open) upper end, ie the range extends to positive infinity.
boolean	isMinClosed() Tests if this range has a bounded (closed) minimum.
boolean	isMinIncluded() Tests if the minimum value is included in the range.
boolean	isMinInf() Tests if the minimum value is positive infinity.
boolean	isMinNegInf() Tests if the minimum value is negative infinity.
boolean	isMinOpen() Tests if this range has an unbounded (open) minimum, ie.
boolean	isPoint() Checks if this range is a point (degenerate) interval
String	toString() Returns a string representation of this range.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NEG_INF

public static final int NEG_INF

Integer flag value for negative infinity. Can be used as an argument to the Range(org.jaitools.numeric.Range) constructor for point (degenerate) intervals.

See Also:

Constant Field Values

INF

public static final int INF

Integer flag value for positive infinity. Can be used as an argument to the Range(org.jaitools.numeric.Range) constructor for point (degenerate) intervals.

See Also:

Constant Field Values

Constructor Detail

Range

public Range(T minValue,
             boolean minIncluded,
             T maxValue,
             boolean maxIncluded)

Creates a new Range with non-zero width (may be infinite).

Parameters:

minValue - the lower bound; passing null for this parameter means an open lower bound; for Float or Double types, the relevant NEGATIVE_INFINITY value can also be used.

minIncluded - true if the lower bound is to be included in the range; false to exclude the lower bound; overridden to be false if the lower bound is open

maxValue - the upper bound; passing null for this parameter means an open upper bound; for Float or Double types, the relevant NEGATIVE_INFINITY value can also be used.

maxIncluded - true if the upper bound is to be included in the range; false to exclude the upper bound; overridden to be false if the upper bound is open

Range

public Range(T value,
             int... inf)

Creates a new point (degenerate) range.

Where value is finite the following apply:

• min value is equal to max value
• upper and lower bounds are treated as closed
• upper and lower bounds are treated as included

If the type parameter T is Float or Double then value can be set to the relevant POSITIVE_INFINITY or NEGATIVE_INFINITY. For other types such as Integer which lack infinity flag values a point range at infinity can be created as in this example...

    Range<Integer> rInf = new Range<Integer>(null, Range.INF);
    Range<Integer> rNegInf = new Range<Integer>(null, Range.NEG_INF);

    // or with the static create method...
    Range<Integer> rInf2 = Range.create(null, Range.INF);
 

For a point interval at positive or negative infinity the following apply:

• getting the min or max value of the range will return null
• the upper and lower bounds are treated as open
• the upper and lower bounds are treated as not included (ie. an infinite point does not contain itself !)

Parameters:

value - the value to set for both min and max end-points

inf - either Range.INF or Range.NEG_INF (ignored if present when value is non-null)

Range

public Range(Range<T> other)

Creates a copy of another Range instance.

Parameters:

other - the range to copy

Method Detail

create

public static <T extends Number & Comparable> Range<T> create(T minValue,
                                                             boolean minIncluded,
                                                             T maxValue,
                                                             boolean maxIncluded)

Static create method. This just relieves the tedium of having to specify the type parameter on both sides of the creation expression. So instead of this...

    Range<Integer> r = new Range<Integer>(10, false, 20, true);
 

you can do this...

    Range<Integer> r = Range.create(10, false, 20, true);
 

Type Parameters:

T - value type

Parameters:

minValue - the lower bound; passing null for this parameter means an open lower bound; for Float or Double types, the relevant NEGATIVE_INFINITY value can also be used.

minIncluded - true if the lower bound is to be included in the range; false to exclude the lower bound; overridden to be false if the lower bound is open

maxValue - the upper bound; passing null for this parameter means an open upper bound; for Float or Double types, the relevant NEGATIVE_INFINITY value can also be used.

maxIncluded - true if the upper bound is to be included in the range; false to exclude the upper bound; overridden to be false if the upper bound is open

Returns:

the new instance

create

public static <T extends Number & Comparable> Range<T> create(T value,
                                                             int... inf)

Creates a Range instance that is a point (degenerate) interval. If value is null, for a point at infinity, the inf argument must be provided and be one of Range.INF or Range.NEG_INF.

Type Parameters:

T - value type

Parameters:

value - the value to set for both min and max end-points

inf - either Range.INF or Range.NEG_INF (ignored if value is non-null)

Returns:

the new instance

isPoint

public boolean isPoint()

Checks if this range is a point (degenerate) interval

Returns:

true if this is a point; false otherwise

getMin

public T getMin()

Gets the minimum value for this range. The minimum value is not necessarily included in the range (see isMinIncluded()).

Caution: If the range is lower-open (ie. isMinOpen() returns true) this method will return null.

Returns:

the minimum value or null if this range is lower-open

isMinInf

public boolean isMinInf()

Tests if the minimum value is positive infinity. If so, the range must be a point (degenerate) interval.

Returns:

true if positive infinity; false otherwise

isMinNegInf

public boolean isMinNegInf()

Tests if the minimum value is negative infinity. This is equivalent to isMinOpen()

Returns:

true if negative infinity; false otherwise

getMax

public T getMax()

Gets the maximum value of this range. The maximum value is not necessarily included in the range (see isMaxIncluded()).

Caution: If the range is upper-open (ie. isMaxOpen() returns true) this method will return null.

Returns:

the maximum value or null if this range is upper-open

isMaxInf

public boolean isMaxInf()

Tests if the maximum value is positive infinity. This is equivalent to isMaxOpen()

Returns:

true if positive infinity; false otherwise

isMaxNegInf

public boolean isMaxNegInf()

Tests if the maximum value is negative infinity. If so, the range must be a point (degenerate) interval.

Returns:

true if negative infinity; false otherwise

isMinIncluded

public boolean isMinIncluded()

Tests if the minimum value is included in the range. This will return false if the range has an unbounded minimum.

Returns:

true if minimum value is included; false otherwise

See Also:

isMinOpen(), isMinClosed()

isMaxIncluded

public boolean isMaxIncluded()

Tests if the maximum range value is included in the range. This will return false if the range has an unbounded maximum.

Returns:

true if maximum value is included; false otherwise

See Also:

isMaxOpen(), isMaxClosed()

isMinOpen

public boolean isMinOpen()

Tests if this range has an unbounded (open) minimum, ie. the range extends to negative infinity.

Returns:

true if unbounded; false otherwise

See Also:

isMinIncluded()

isMinClosed

public boolean isMinClosed()

Tests if this range has a bounded (closed) minimum.

Returns:

true if bounded; false otherwise

See Also:

isMinIncluded()

isMaxOpen

public boolean isMaxOpen()

Tests if this range has unbounded (open) upper end, ie the range extends to positive infinity.

Returns:

true if unbounded; false otherwise

See Also:

isMaxIncluded()

isMaxClosed

public boolean isMaxClosed()

Tests if this range has a bounded (closed) maximum value.

Returns:

true if bounded; false otherwise

See Also:

isMaxIncluded()

contains

public boolean contains(T value)

Tests if this range contains the specified, non-null value.

Parameters:

value - the value

Returns:

true if the value is within this range; false otherwise

intersects

public boolean intersects(Range<T> other)

Tests if this range intersects another range. Two ranges intersect if there is at least one value, x, for which contains(x) returns true for both ranges

Parameters:

other - the range to check for intersection

Returns:

true if the ranges intersect; false otherwise

equals

public boolean equals(Object obj)

Tests for equality with another range. Two ranges are equal if their respective end-points are identical in both value and type (included / excluded).

Overrides:

equals in class Object

Parameters:

obj - the other range

Returns:

true if equal; false otherwise

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Returns a string representation of this range. The common interval notation of square brackets for closed boundaries and round brackets for open boundaries is used.

Examples of output:

[10, 20]
(-Inf, 42)

Overrides:

toString in class Object

Returns:

the string