Package org.apache.sis.measure
Class NumberRange<E extends Number & Comparable<? super E>>
java.lang.Object
org.apache.sis.measure.Range<E>
org.apache.sis.measure.NumberRange<E>
- Type Parameters:
E
- the type of range elements as a subclass ofNumber
.
- All Implemented Interfaces:
Serializable
,Formattable
,CheckedContainer<E>
,Emptiable
- Direct Known Subclasses:
DomainRange
,EPSGParameterDomain
,MeasurementRange
A range of numbers capable of widening conversions when performing range operations.
NumberRange
has no unit of measurement. For a range of physical measurements
with unit of measure, see MeasurementRange
.
NumberRange
has some capability to convert different number types before to
perform operations. In order to provide both this flexibility and the safety of generic
types, most operations in this class are defined in two versions:
- Methods inherited from the
Range
parent class (contains
,intersect
,intersects
,union
andsubtract
) requires argument or range elements of type<E>
. No type conversion is performed. - Methods defined in this class with the
Any
suffix (containsAny
,intersectAny
,intersectsAny
,unionAny
andsubtractAny
) are more lenient on the argument or range element type<E>
. Widening conversions are performed as needed.
<?>
).
Other methods defined in this class:
- Convenience
create(…)
static methods for every numeric primitive types. castTo(Class)
for casting the range values to another type.transform(MathTransform1D)
for applying an arbitrary conversion.
Relationship with standards
NumberRange
is the SIS class closest to the
mathematical definition of interval.
It is closely related, while not identical, to the ISO 19123 (Coverage geometry and functions)
definition of "ranges". At the difference of the parent Range
class, which can be used only with
discrete coverages, the NumberRange
class can
also be used with continuous coverages.
Immutability and thread safety
This class and theMeasurementRange
subclasses are immutable, and thus inherently thread-safe.
Other subclasses may or may not be immutable, at implementation choice. But implementers are encouraged
to make sure that all subclasses remain immutable for more predictable behavior.
Shared instances
Note: following is implementation details provided for information purpose. The caching policy may change in any SIS version.All create
static methods may return a shared instance. Those methods are preferred
to the constructors when the range is expected to have a long lifetime, typically as instance
given to parameter descriptor.
Other methods do not check for shared instances, since the created object is often temporary.
- Since:
- 0.3
- Version:
- 1.3
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final WeakHashSet<NumberRange<?>>
The pool of ranges created by thecreate(…)
methods.private static final long
Serial number for inter-operability with different versions.Fields inherited from class org.apache.sis.measure.Range
elementType, isMaxIncluded, isMinIncluded, maxValue, minValue
-
Constructor Summary
ConstructorsConstructorDescriptionNumberRange
(Class<E> type, E minValue, boolean isMinIncluded, E maxValue, boolean isMaxIncluded) Constructs a range ofNumber
objects.NumberRange
(Class<E> type, Range<? extends Number> range) Constructs a range with the same values than the specified range, casted to the specified type.NumberRange
(Class<E> type, ValueRange range) Constructs a range of the given type with values from the given annotation.NumberRange
(Range<E> range) Constructs a range with the same type and the same values than the specified range. -
Method Summary
Modifier and TypeMethodDescriptionstatic <N extends Number & Comparable<? super N>>
NumberRange<N>castOrCopy
(Range<N> range) Returns the specifiedRange
as aNumberRange
object.<N extends Number & Comparable<? super N>>
NumberRange<N>Casts this range to the specified type.boolean
containsAny
(Number value) Returnstrue
if this range contains the given value.boolean
containsAny
(NumberRange<?> range) Returnstrue
if the supplied range is fully contained within this range.(package private) <N extends Number & Comparable<? super N>>
NumberRange<N>convertAndCast
(NumberRange<?> range, Class<N> type) Casts the specified range to the specified type.static NumberRange<Byte>
create
(byte minValue, boolean isMinIncluded, byte maxValue, boolean isMaxIncluded) Constructs a range ofbyte
values.static NumberRange<Double>
create
(double minValue, boolean isMinIncluded, double maxValue, boolean isMaxIncluded) Constructs a range ofdouble
values.static NumberRange<Float>
create
(float minValue, boolean isMinIncluded, float maxValue, boolean isMaxIncluded) Constructs a range offloat
values.static NumberRange<Integer>
create
(int minValue, boolean isMinIncluded, int maxValue, boolean isMaxIncluded) Constructs a range ofint
values.static NumberRange<Long>
create
(long minValue, boolean isMinIncluded, long maxValue, boolean isMaxIncluded) Constructs a range oflong
values.static NumberRange<Short>
create
(short minValue, boolean isMinIncluded, short maxValue, boolean isMaxIncluded) Constructs a range ofshort
values.Creates a new range using the same element type than this range.static <N extends Number & Comparable<? super N>>
NumberRange<N>Constructs a range containing a single value of the given type.static NumberRange<?>
createBestFit
(boolean asFloat, Number minValue, boolean isMinIncluded, Number maxValue, boolean isMaxIncluded) Constructs a range using the smallest integer type or floating point type that can hold the given values.static NumberRange<?>
createBestFit
(Number minValue, boolean isMinIncluded, Number maxValue, boolean isMaxIncluded) Constructs a range using the smallest type ofNumber
that can hold the given values.static NumberRange<Integer>
createLeftBounded
(int minValue, boolean isMinIncluded) Constructs a range ofint
values without upper bound.double
Returns the maximum value as adouble
.double
getMaxDouble
(boolean inclusive) Returns the maximum value with the specified inclusive or exclusive state.double
Computes the average of minimum and maximum values.double
Returns the minimum value as adouble
.double
getMinDouble
(boolean inclusive) Returns the minimum value with the specified inclusive or exclusive state.double
getSpan()
Computes the difference between minimum and maximum values.NumberRange<?>
intersectAny
(NumberRange<?> range) Returns the union of this range with the given range.boolean
intersectsAny
(NumberRange<?> range) Returnstrue
if the supplied range intersects this range.(package private) static boolean
Returnstrue
if the given value is valid for a range to be cached byRange.union(Range)
.private static boolean
Returnstrue
if the given value can be casted to theFloat
type.private double
medianOrSpan
(boolean median) Implementation ofgetMedian()
andgetSpan()
.newArray
(int length) Returns an initially empty array of the given length.private static double
Returns the next value for the given type.NumberRange<?>[]
subtractAny
(NumberRange<?> range) Returns the range of values that are in this range but not in the given range.NumberRange<?>
transform
(org.opengis.referencing.operation.MathTransform1D converter) Returns this range converted using the given converter.NumberRange<?>
unionAny
(NumberRange<?> range) Returns the union of this range with the given range.(package private) static <E extends Number & Comparable<? super E>,
T extends NumberRange<E>>
Tunique
(T range) Returns a unique instance of the given range, except if the range is empty.(package private) static Double
Returns theDouble
wrapper of the given primitivedouble
, ornull
if it equals to the infinity value.(package private) static Float
Returns theFloat
wrapper of the given primitivefloat
, ornull
if it equals to the infinity value.Methods inherited from class org.apache.sis.measure.Range
contains, contains, equals, formatTo, getElementType, getMaxValue, getMinValue, hashCode, intersect, intersects, isBounded, isEmpty, isMaxIncluded, isMinIncluded, subtract, toString, union, unit
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
POOL
The pool of ranges created by thecreate(…)
methods.
-
-
Constructor Details
-
NumberRange
Constructs a range with the same type and the same values than the specified range. This is a copy constructor.- Parameters:
range
- the range to copy. The elements must beNumber
instances.
-
NumberRange
Constructs a range of the given type with values from the given annotation. This constructor does not verify if the given type is wide enough for the values of the given annotation, because those information are usually static. If nevertheless the given type is not wide enough, then the values are truncated in the same way than the Java language casts primitive types. -
NumberRange
public NumberRange(Class<E> type, E minValue, boolean isMinIncluded, E maxValue, boolean isMaxIncluded) Constructs a range ofNumber
objects.- Parameters:
type
- the element type, usually one ofByte
,Short
,Integer
,Long
,Float
orDouble
.minValue
- the minimal value, ornull
if none.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.maxValue
- the maximal value, ornull
if none.isMaxIncluded
-true
if the maximal value is inclusive, orfalse
if exclusive.
-
NumberRange
NumberRange(Class<E> type, Range<? extends Number> range) throws IllegalArgumentException Constructs a range with the same values than the specified range, casted to the specified type.
-
-
Method Details
-
unique
Returns a unique instance of the given range, except if the range is empty.Rational: we exclude empty ranges because theWe use this method only for caching range of wrapper of primitive types (Range.equals(Object)
consider them as equal. Consequently, if empty ranges were included in the pool, this method would return in some occasions an empty range with different values than the givenrange
argument.Byte
,Short
, etc.) because those types are known to be immutable. -
isCacheable
Returnstrue
if the given value is valid for a range to be cached byRange.union(Range)
. A range can be cached if theNumber
values are null or instances of a standard Java class known to be immutable, and the wrapped values are not NaN except the canonicalDouble.NaN
orFloat.NaN
values. This check is necessary becauseRange.equals(Object)
considers allNaN
values as equal. -
create
public static <N extends Number & Comparable<? super N>> NumberRange<N> create(Class<N> type, N value) Constructs a range containing a single value of the given type. The given value is used as the minimum and maximum values, inclusive. -
create
public static NumberRange<Byte> create(byte minValue, boolean isMinIncluded, byte maxValue, boolean isMaxIncluded) Constructs a range ofbyte
values. If the minimum is greater than the maximum, then the range is empty. This method may return a shared instance, at implementation choice.- Parameters:
minValue
- the minimal value.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.maxValue
- the maximal value.isMaxIncluded
-true
if the maximal value is inclusive, orfalse
if exclusive.- Returns:
- the new range of numeric values for the given endpoints.
-
create
public static NumberRange<Short> create(short minValue, boolean isMinIncluded, short maxValue, boolean isMaxIncluded) Constructs a range ofshort
values. If the minimum is greater than the maximum, then the range is empty. This method may return a shared instance, at implementation choice.- Parameters:
minValue
- the minimal value.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.maxValue
- the maximal value.isMaxIncluded
-true
if the maximal value is inclusive, orfalse
if exclusive.- Returns:
- the new range of numeric values for the given endpoints.
-
create
public static NumberRange<Integer> create(int minValue, boolean isMinIncluded, int maxValue, boolean isMaxIncluded) Constructs a range ofint
values. If the minimum is greater than the maximum, then the range is empty. This method may return a shared instance, at implementation choice.- Parameters:
minValue
- the minimal value.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.maxValue
- the maximal value.isMaxIncluded
-true
if the maximal value is inclusive, orfalse
if exclusive.- Returns:
- the new range of numeric values for the given endpoints.
- See Also:
-
create
public static NumberRange<Long> create(long minValue, boolean isMinIncluded, long maxValue, boolean isMaxIncluded) Constructs a range oflong
values. If the minimum is greater than the maximum, then the range is empty. This method may return a shared instance, at implementation choice.- Parameters:
minValue
- the minimal value.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.maxValue
- the maximal value.isMaxIncluded
-true
if the maximal value is inclusive, orfalse
if exclusive.- Returns:
- the new range of numeric values for the given endpoints.
-
create
public static NumberRange<Float> create(float minValue, boolean isMinIncluded, float maxValue, boolean isMaxIncluded) Constructs a range offloat
values. The minimum and maximum values cannot be NaN but can be infinite. If the minimum is greater than the maximum, then the range is empty. This method may return a shared instance, at implementation choice.- Parameters:
minValue
- the minimal value, orFloat.NEGATIVE_INFINITY
if none.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.maxValue
- the maximal value, orFloat.POSITIVE_INFINITY
if none.isMaxIncluded
-true
if the maximal value is inclusive, orfalse
if exclusive.- Returns:
- the new range of numeric values for the given endpoints.
- Throws:
IllegalArgumentException
- ifFloat.isNaN(float)
istrue
for a given value.
-
valueOf
Returns theFloat
wrapper of the given primitivefloat
, ornull
if it equals to the infinity value. -
create
public static NumberRange<Double> create(double minValue, boolean isMinIncluded, double maxValue, boolean isMaxIncluded) Constructs a range ofdouble
values. The minimum and maximum values cannot be NaN but can be infinite. If the minimum is greater than the maximum, then the range is empty. This method may return a shared instance, at implementation choice.- Parameters:
minValue
- the minimal value, orDouble.NEGATIVE_INFINITY
if none.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.maxValue
- the maximal value, orDouble.POSITIVE_INFINITY
if none.isMaxIncluded
-true
if the maximal value is inclusive, orfalse
if exclusive.- Returns:
- the new range of numeric values for the given endpoints.
- Throws:
IllegalArgumentException
- ifDouble.isNaN(double)
istrue
for a given value.
-
valueOf
Returns theDouble
wrapper of the given primitivedouble
, ornull
if it equals to the infinity value. -
createBestFit
public static NumberRange<?> createBestFit(Number minValue, boolean isMinIncluded, Number maxValue, boolean isMaxIncluded) Constructs a range using the smallest type ofNumber
that can hold the given values. The given numbers do not need to be of the same type since they will be casted as needed. More specifically this method returns:NumberRange<Byte>
if the given values are integers between 0x80 and 0x7f inclusive.NumberRange<Short>
if the given values are integers between -32768 and 32767 inclusive.NumberRange<Integer>
if the given values are integers between -2147483648 and 2147483647 inclusive.NumberRange<Long>
if the given values are integers between -9223372036854775808L and 9223372036854775807L inclusive.NumberRange<Float>
if the given values can be casted tofloat
values without data lost.NumberRange<Double>
if none of the above types is suitable.
- Parameters:
minValue
- the minimal value, ornull
if none.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.maxValue
- the maximal value, ornull
if none.isMaxIncluded
-true
if the maximal value is inclusive, orfalse
if exclusive.- Returns:
- the new range, or
null
if bothminValue
andmaxValue
arenull
. - Throws:
IllegalArgumentException
- if the given numbers are not primitive wrappers for numeric types.
-
createBestFit
public static NumberRange<?> createBestFit(boolean asFloat, Number minValue, boolean isMinIncluded, Number maxValue, boolean isMaxIncluded) Constructs a range using the smallest integer type or floating point type that can hold the given values. IfasFloat
isfalse
, then the returned range can use any wrapper type and this method behaves as described in above method. IfasFloat
istrue
, then the returned range is restricted toFloat
andDouble
number types; integer types are casted to one of the floating point types.- Parameters:
asFloat
- whether to restrict the returned range to floating point types.minValue
- the minimal value, ornull
if none.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.maxValue
- the maximal value, ornull
if none.isMaxIncluded
-true
if the maximal value is inclusive, orfalse
if exclusive.- Returns:
- the new range, or
null
if bothminValue
andmaxValue
arenull
. - Throws:
IllegalArgumentException
- if the given numbers are not primitive wrappers for numeric types.- Since:
- 1.2
-
isFloat
Returnstrue
if the given value can be casted to theFloat
type. -
createLeftBounded
Constructs a range ofint
values without upper bound. This method may return a shared instance, at implementation choice.Note: for creating left-bounded ranges of floating point values, use one of thecreate(…)
methods with aPOSITIVE_INFINITY
constant. We do not provide variants for other integer types because this method is typically invoked for defining the multiplicity of an attribute.- Parameters:
minValue
- the minimal value.isMinIncluded
-true
if the minimal value is inclusive, orfalse
if exclusive.- Returns:
- the new range of numeric values from
minValue
to positive infinity. - Since:
- 0.5
- See Also:
-
castOrCopy
Returns the specifiedRange
as aNumberRange
object. If the specified range is already an instance ofNumberRange
, then it is returned unchanged. Otherwise a new number range is created using the copy constructor.- Type Parameters:
N
- the type of elements in the given range.- Parameters:
range
- the range to cast or copy.- Returns:
- the same range than
range
as aNumberRange
object.
-
create
Creates a new range using the same element type than this range. This method will be overridden by subclasses in order to create a range of a more specific type. -
convertAndCast
<N extends Number & Comparable<? super N>> NumberRange<N> convertAndCast(NumberRange<?> range, Class<N> type) throws IllegalArgumentException Casts the specified range to the specified type. If this class is associated to a unit of measurement, then this method converts therange
unit to the same unit than this instance. This method is overridden byMeasurementRange
only in the way described above. -
castTo
public <N extends Number & Comparable<? super N>> NumberRange<N> castTo(Class<N> type) throws IllegalArgumentException Casts this range to the specified type. If the cast from this range type to the given type is a narrowing conversion, then the cast is performed according the rules of the Java language: the high-order bytes are silently dropped.- Type Parameters:
N
- the class to cast to.- Parameters:
type
- the class to cast to. Must be one ofByte
,Short
,Integer
,Long
,Float
orDouble
.- Returns:
- the casted range, or
this
if this range already uses the specified type. - Throws:
IllegalArgumentException
- if the given type is not one of the primitive wrappers for numeric types.
-
newArray
Returns an initially empty array of the given length. -
getMinDouble
public double getMinDouble()Returns the minimum value as adouble
. If this range is unbounded, thenDouble.NEGATIVE_INFINITY
is returned.- Returns:
- the minimum value.
-
getMinDouble
public double getMinDouble(boolean inclusive) Returns the minimum value with the specified inclusive or exclusive state. If this range is unbounded, thenDouble.NEGATIVE_INFINITY
is returned.- Parameters:
inclusive
-true
for the minimum value inclusive, orfalse
for the minimum value exclusive.- Returns:
- the minimum value, inclusive or exclusive as requested.
-
getMaxDouble
public double getMaxDouble()Returns the maximum value as adouble
. If this range is unbounded, thenDouble.POSITIVE_INFINITY
is returned.- Returns:
- the maximum value.
-
getMaxDouble
public double getMaxDouble(boolean inclusive) Returns the maximum value with the specified inclusive or exclusive state. If this range is unbounded, thenDouble.POSITIVE_INFINITY
is returned.- Parameters:
inclusive
-true
for the maximum value inclusive, orfalse
for the maximum value exclusive.- Returns:
- the maximum value, inclusive or exclusive as requested.
-
getMedian
public double getMedian()Computes the average of minimum and maximum values. If numbers are integers, the average is computed using inclusive values (e.g. equivalent togetMinDouble(true)
). Otherwise the minimum and maximum values are used as-is (because making them inclusive is considered an infinitely small change).Special cases:
- If one bound is infinite, the return value is the same infinity.
- If the two bounds are infinite, the return value is
Double.NaN
. - If the range is empty, the return value is
Double.NaN
. - If a bound is NaN, the return value is the same NaN (reminder: multiple NaN values are possible).
- Returns:
- (minimum + maximum) / 2 computed using inclusive values.
- Since:
- 1.1
-
getSpan
public double getSpan()Computes the difference between minimum and maximum values. If numbers are integers, the difference is computed using inclusive values (e.g. equivalent togetMinDouble(true)
). Otherwise the minimum and maximum values are used as-is (because making them inclusive is considered an infinitely small change).Special cases:
- If the range is empty, the return value is 0.
- If at least one bound is infinite, the return value is
Double.POSITIVE_INFINITY
. - If a bound is NaN, the return value is the same NaN (reminder: multiple NaN values are possible).
- Returns:
- (maximum − minimum) computed using inclusive values.
- Since:
- 1.1
-
medianOrSpan
private double medianOrSpan(boolean median) Implementation ofgetMedian()
andgetSpan()
. -
next
Returns the next value for the given type.- Parameters:
type
- the element type.value
- the value to increment or decrement.up
-true
for incrementing, orfalse
for decrementing.- Returns:
- the adjacent value.
-
containsAny
Returnstrue
if this range contains the given value. This method convertsthis
or the given argument to the widest numeric type, then performs the same work thanRange.contains(Comparable)
.- Parameters:
value
- the value to check for inclusion in this range.- Returns:
true
if the given value is included in this range.- Throws:
IllegalArgumentException
- if the given range cannot be converted to a valid type through widening conversion.
-
containsAny
Returnstrue
if the supplied range is fully contained within this range. This method convertsthis
or the given argument to the widest numeric type, then delegates toRange.contains(Range)
.- Parameters:
range
- the range to check for inclusion in this range.- Returns:
true
if the given range is included in this range.- Throws:
IllegalArgumentException
- if the given range cannot be converted to a valid type through widening conversion, or if the units of measurement are not convertible.
-
intersectsAny
Returnstrue
if the supplied range intersects this range. This method convertsthis
or the given argument to the widest numeric type, then delegates toRange.intersects(Range)
.- Parameters:
range
- the range to check for intersection with this range.- Returns:
true
if the given range intersects this range.- Throws:
IllegalArgumentException
- if the given range cannot be converted to a valid type through widening conversion, or if the units of measurement are not convertible.
-
intersectAny
Returns the union of this range with the given range. This method convertsthis
or the given argument to the widest numeric type, then delegates toRange.intersect(Range)
.- Parameters:
range
- the range to add to this range.- Returns:
- the intersection of this range with the given range.
- Throws:
IllegalArgumentException
- if the given range cannot be converted to a valid type through widening conversion, or if the units of measurement are not convertible.
-
unionAny
Returns the union of this range with the given range. This method convertsthis
or the given argument to the widest numeric type, then delegates toRange.union(Range)
.- Parameters:
range
- the range to add to this range.- Returns:
- the union of this range with the given range.
- Throws:
IllegalArgumentException
- if the given range cannot be converted to a valid type through widening conversion, or if the units of measurement are not convertible.
-
subtractAny
Returns the range of values that are in this range but not in the given range. This method convertsthis
or the given argument to the widest numeric type, then delegates toRange.subtract(Range)
.- Parameters:
range
- the range to subtract.- Returns:
- this range without the given range, as an array of length 0, 1 or 2.
- Throws:
IllegalArgumentException
- if the given range cannot be converted to a valid type through widening conversion, or if the units of measurement are not convertible.
-
transform
public NumberRange<?> transform(org.opengis.referencing.operation.MathTransform1D converter) throws org.opengis.referencing.operation.TransformException Returns this range converted using the given converter.- Parameters:
converter
- the converter to apply.- Returns:
- the converted range, or
this
if the result is the same as this range. - Throws:
org.opengis.referencing.operation.TransformException
- if an error occurred during the conversion.- Since:
- 1.3
-