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

java.lang.Object
  extended by 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...

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:

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:

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


Copyright © 2009-2013. All Rights Reserved.