Package org.apache.sis.measure
Class MeasurementRange<E extends Number & Comparable<? super E>>
java.lang.Object
org.apache.sis.measure.Range<E>
org.apache.sis.measure.NumberRange<E>
org.apache.sis.measure.MeasurementRange<E>
- Type Parameters:
E
- the type of range elements as a subclass ofNumber
.
- All Implemented Interfaces:
Serializable
,Formattable
,CheckedContainer<E>
,Emptiable
- Direct Known Subclasses:
ConvertedRange
A range of numbers associated with a unit of measurement. All operations performed by this
class (union, intersection, etc.) are
performed in the unit of measurement of
this
range object - values of the range
object given in argument are converted if needed before an operation is applied.
Other methods defined in this class:
- Convenience
create(…)
static methods for every floating point primitive types. Usage ofMeasurementRange
with integer types is possible, but no convenience method is provided for integers because they are usually not representative of the nature of physical measurements. unit()
for getting the unit of measurement associated to this range.convertTo(Unit)
for converting the unit of measurement.castTo(Class)
for casting the range values to another type.
Null unit of measurement
The unit of measurement should not be null, otherwise aNumberRange
should be used
instead of MeasurementRange
. Nevertheless this class is tolerant to null
units in order to support situations where a unit of measurement should be specified,
but for some reason is unavailable. If the unit of measurement become known at a later stage,
it can be specified by a call to convertTo(Unit)
.
Immutability and thread safety
This class is immutable and thus inherently thread-safe. Subclasses may or may not be immutable, at implementation choice. But implementers are encouraged to make sure that subclasses remain immutable for more predictable behavior.- Since:
- 0.3
- Version:
- 0.6
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final long
Serial number for inter-operability with different versions.private final javax.measure.Unit<?>
The unit of measurement, ornull
if unknown.Fields inherited from class org.apache.sis.measure.Range
elementType, isMaxIncluded, isMinIncluded, maxValue, minValue
-
Constructor Summary
ConstructorsModifierConstructorDescriptionMeasurementRange
(Class<E> type, E minValue, boolean isMinIncluded, E maxValue, boolean isMaxIncluded, javax.measure.Unit<?> unit) Constructs a range ofNumber
objects.private
MeasurementRange
(Class<E> type, Range<? extends Number> range, javax.measure.Unit<?> unit) Constructs a range with the same values than the specified range, casted to the specified type.MeasurementRange
(Class<E> type, ValueRange range, javax.measure.Unit<?> unit) Constructs a range of the given type with values from the given annotation.MeasurementRange
(Range<E> range, javax.measure.Unit<?> unit) Constructs a range with the same values than the specified range and the given unit. -
Method Summary
Modifier and TypeMethodDescription<N extends Number & Comparable<? super N>>
MeasurementRange<N>Casts this range to the specified type.boolean
Returnstrue
if the supplied range is fully contained within this range.If the given range is an instance ofMeasurementRange
, converts that range to the unit of this range.private <N extends Number & Comparable<? super N>>
MeasurementRange<N>convertAndCast
(Class<N> type, javax.measure.Unit<?> targetUnit) Casts this range to the specified type and converts to the specified unit.(package private) <N extends Number & Comparable<? super N>>
NumberRange<N>convertAndCast
(NumberRange<?> range, Class<N> type) Casts the specified range to the specified type.convertTo
(javax.measure.Unit<?> targetUnit) Converts this range to the specified unit.static MeasurementRange<Double>
create
(double minValue, boolean isMinIncluded, double maxValue, boolean isMaxIncluded, javax.measure.Unit<?> unit) Constructs a range ofdouble
values.static MeasurementRange<Float>
create
(float minValue, boolean isMinIncluded, float maxValue, boolean isMaxIncluded, javax.measure.Unit<?> unit) Constructs a range offloat
values.Creates a new range using the same element type and the same unit than this range.static MeasurementRange<?>
createBestFit
(Number minValue, boolean isMinIncluded, Number maxValue, boolean isMaxIncluded, javax.measure.Unit<?> unit) Constructs a range using the smallest type ofNumber
that can hold the given values.static MeasurementRange<Double>
createGreaterThan
(double minValue, javax.measure.Unit<?> unit) Constructs a range ofdouble
values greater than the given value.boolean
Compares this measurement range with the specified object for equality.int
hashCode()
Returns a hash code value for this measurement range.Returns the intersection between this range and the given range.boolean
intersects
(Range<? extends E> range) Returnstrue
if this range intersects the given range.newArray
(int length) Returns an initially empty array of the given length.Returns the range of values that are in this range but not in the given range.Returns the union of this range with the given range.javax.measure.Unit<?>
unit()
Returns the unit of measurement, ornull
if unknown.Methods inherited from class org.apache.sis.measure.NumberRange
castOrCopy, containsAny, containsAny, create, create, create, create, create, create, create, createBestFit, createBestFit, createLeftBounded, getMaxDouble, getMaxDouble, getMedian, getMinDouble, getMinDouble, getSpan, intersectAny, intersectsAny, isCacheable, subtractAny, transform, unionAny, unique, valueOf, valueOf
Methods inherited from class org.apache.sis.measure.Range
contains, formatTo, getElementType, getMaxValue, getMinValue, isBounded, isEmpty, isMaxIncluded, isMinIncluded, toString
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
unit
private final javax.measure.Unit<?> unitThe unit of measurement, ornull
if unknown.- See Also:
-
-
Constructor Details
-
MeasurementRange
Constructs a range with the same values than the specified range and the given unit. This is a copy constructor, with the addition of a unit of measurement.- Parameters:
range
- the range to copy. The elements must beNumber
instances.unit
- the unit of measurement, ornull
if unknown.
-
MeasurementRange
public MeasurementRange(Class<E> type, ValueRange range, javax.measure.Unit<?> unit) throws IllegalArgumentException 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. -
MeasurementRange
public MeasurementRange(Class<E> type, E minValue, boolean isMinIncluded, E maxValue, boolean isMaxIncluded, javax.measure.Unit<?> unit) Constructs a range ofNumber
objects.- Parameters:
type
- the element type, usually one ofFloat
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.unit
- the unit of measurement, ornull
if unknown.
-
MeasurementRange
Constructs a range with the same values than the specified range, casted to the specified type.
-
-
Method Details
-
create
public static MeasurementRange<Float> create(float minValue, boolean isMinIncluded, float maxValue, boolean isMaxIncluded, javax.measure.Unit<?> unit) 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.unit
- the unit of measurement, ornull
if unknown.- Returns:
- the new range of numeric values for the given endpoints and unit of measurement.
- Throws:
IllegalArgumentException
- ifFloat.isNaN(float)
istrue
for a given value.
-
create
public static MeasurementRange<Double> create(double minValue, boolean isMinIncluded, double maxValue, boolean isMaxIncluded, javax.measure.Unit<?> unit) 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.unit
- the unit of measurement, ornull
if unknown.- Returns:
- the new range of numeric values for the given endpoints and unit of measurement.
- Throws:
IllegalArgumentException
- ifDouble.isNaN(double)
istrue
for a given value.
-
createGreaterThan
public static MeasurementRange<Double> createGreaterThan(double minValue, javax.measure.Unit<?> unit) Constructs a range ofdouble
values greater than the given value. TheminValue
is often zero for creating a range of strictly positive values. This method may return a shared instance, at implementation choice.- Parameters:
minValue
- the minimal value (exclusive), orDouble.NEGATIVE_INFINITY
if none.unit
- the unit of measurement, ornull
if unknown.- Returns:
- the new range of numeric values greater than the given value.
- Throws:
IllegalArgumentException
- ifDouble.isNaN(double)
istrue
for the given value.- Since:
- 0.6
-
createBestFit
public static MeasurementRange<?> createBestFit(Number minValue, boolean isMinIncluded, Number maxValue, boolean isMaxIncluded, javax.measure.Unit<?> unit) Constructs a range using the smallest type ofNumber
that can hold the given values. This method performs the same work thanNumberRange.createBestFit(…)
with an additionalunit
argument.This method may return a shared instance, at implementation choice.
- 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.unit
- the unit of measurement, ornull
if unknown.- Returns:
- the new range, or
null
if bothminValue
andmaxValue
arenull
. - See Also:
-
create
Creates a new range using the same element type and the same unit than this range.- Overrides:
create
in classNumberRange<E extends Number & Comparable<? super E>>
-
unit
public javax.measure.Unit<?> unit()Returns the unit of measurement, ornull
if unknown. In principle the unit should never be null, otherwise aNumberRange
should have been used instead ofMeasurementRange
. Nevertheless this method may returnnull
if a unit should exist but for some reason is unavailable. -
convertTo
public MeasurementRange<E> convertTo(javax.measure.Unit<?> targetUnit) throws javax.measure.IncommensurableException Converts this range to the specified unit. If this measurement range has null unit, then the specified target unit are simply assigned to the returned range with no other changes.- Parameters:
targetUnit
- the target unit, ornull
for keeping the unit unchanged.- Returns:
- the converted range, or
this
if no conversion is needed. - Throws:
javax.measure.IncommensurableException
- if the target unit are not compatible with this range unit.
-
castTo
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.- Overrides:
castTo
in classNumberRange<E extends Number & Comparable<? super E>>
- 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.
-
convert
If the given range is an instance ofMeasurementRange
, converts that range to the unit of this range. Otherwise returns the given range unchanged.- Parameters:
range
- the range to convert.- Returns:
- the converted range.
- Throws:
IllegalArgumentException
- if the given target unit is not compatible with the unit of this range.
-
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 convert therange
unit to the same unit than this instance.- Overrides:
convertAndCast
in classNumberRange<E extends Number & Comparable<? super E>>
- Parameters:
type
- the class to cast to. Must be one ofByte
,Short
,Integer
,Long
,Float
orDouble
.- Returns:
- the casted range, or
range
if no cast is needed. - Throws:
IllegalArgumentException
- if the given type is not one of the primitive wrappers for numeric types.
-
convertAndCast
private <N extends Number & Comparable<? super N>> MeasurementRange<N> convertAndCast(Class<N> type, javax.measure.Unit<?> targetUnit) throws javax.measure.IncommensurableException Casts this range to the specified type and converts to the specified unit. This method is invoked on theother
instance in expressions likethis.operation(other)
.- Parameters:
type
- the class to cast to. Must be one ofByte
,Short
,Integer
,Long
,Float
orDouble
.targetUnit
- the target unit, ornull
for no change.- Returns:
- the casted range, or
this
. - Throws:
javax.measure.IncommensurableException
- if the given target unit is not compatible with the unit of this range.
-
newArray
Returns an initially empty array of the given length.- Overrides:
newArray
in classNumberRange<E extends Number & Comparable<? super E>>
-
contains
Returnstrue
if the supplied range is fully contained within this range. If the given range is an instance ofMeasurementRange
, then this method converts the value of the other range to the unit of measurement of this range before to perform the operation.- Overrides:
contains
in classRange<E extends Number & Comparable<? super E>>
- 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 is an instance ofMeasurementRange
using incommensurable unit of measurement.
-
intersects
Returnstrue
if this range intersects the given range. If the given range is an instance ofMeasurementRange
, then this method converts the value of the other range to the unit of measurement of this range before to perform the operation.- Overrides:
intersects
in classRange<E extends Number & Comparable<? super E>>
- 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 is an instance ofMeasurementRange
using incommensurable unit of measurement.
-
intersect
Returns the intersection between this range and the given range. If the given range is an instance ofMeasurementRange
, then this method converts the value of the other range to the unit of measurement of this range before to perform the operation.- Overrides:
intersect
in classRange<E extends Number & Comparable<? super E>>
- Parameters:
range
- the range to intersect.- Returns:
- the intersection of this range with the given range.
- Throws:
IllegalArgumentException
- if the given range is an instance ofMeasurementRange
using incommensurable unit of measurement.
-
union
Returns the union of this range with the given range. If the given range is an instance ofMeasurementRange
, then this method converts the value of the other range to the unit of measurement of this range before to perform the operation.- Overrides:
union
in classRange<E extends Number & Comparable<? super E>>
- 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 is an instance ofMeasurementRange
using incommensurable unit of measurement.
-
subtract
Returns the range of values that are in this range but not in the given range. This method returns an array of length 0, 1 or 2:- If the given range contains fully this range, returns an array of length 0.
- If the given range is in the middle of this range, then the subtraction results in two disjoint ranges which will be returned as two elements in the array.
- Otherwise returns an array of length 1.
MeasurementRange
, then this method converts the value of the other range to the unit of measurement of this range before to perform the operation.- Overrides:
subtract
in classRange<E extends Number & Comparable<? super E>>
- 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 is an instance ofMeasurementRange
using incommensurable unit of measurement.
-
equals
Compares this measurement range with the specified object for equality. TwoMeasurementRange
instances are considered equal if they met all conditions documented in the parent class and theirunit()
are equal in the sense ofObjects.equals(Object, Object)
. Note that this comparison does not distinguish the variousFloat.NaN
orDouble.NaN
bit patterns. -
hashCode
public int hashCode()Returns a hash code value for this measurement range.
-