Package org.apache.sis.measure
Class MeasurementRange<E extends Number & Comparable<? super E>>
Object
Range<E>
NumberRange<E>
MeasurementRange<E>
- Type Parameters:
E- the type of range elements as a subclass ofNumber.
- All Implemented Interfaces:
Serializable,Formattable,CheckedContainer<E>,Emptiable
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 ofMeasurementRangewith 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
- See Also:
Defined in the sis-utility module
-
Constructor Summary
ConstructorsConstructorDescriptionMeasurementRange(Class<E> type, E minValue, boolean isMinIncluded, E maxValue, boolean isMaxIncluded, Unit<?> unit) Constructs a range ofNumberobjects.MeasurementRange(Class<E> type, ValueRange range, Unit<?> unit) Constructs a range of the given type with values from the given annotation.MeasurementRange(Range<E> range, 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.booleanReturnstrueif the supplied range is fully contained within this range.convertTo(Unit<?> targetUnit) Converts this range to the specified unit.static MeasurementRange<Double>create(double minValue, boolean isMinIncluded, double maxValue, boolean isMaxIncluded, Unit<?> unit) Constructs a range ofdoublevalues.static MeasurementRange<Float>create(float minValue, boolean isMinIncluded, float maxValue, boolean isMaxIncluded, Unit<?> unit) Constructs a range offloatvalues.static MeasurementRange<?>createBestFit(Number minValue, boolean isMinIncluded, Number maxValue, boolean isMaxIncluded, Unit<?> unit) Constructs a range using the smallest type ofNumberthat can hold the given values.static MeasurementRange<Double>createGreaterThan(double minValue, Unit<?> unit) Constructs a range ofdoublevalues greater than the given value.booleanCompares this measurement range with the specified object for equality.intReturns a hash code value for this measurement range.Returns the intersection between this range and the given range.booleanintersects(Range<? extends E> range) Returnstrueif this range intersects the given range.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.Unit<?>unit()Returns the unit of measurement, ornullif unknown.Methods inherited from class NumberRange
castOrCopy, containsAny, containsAny, create, create, create, create, create, create, create, createBestFit, createBestFit, createLeftBounded, getMaxDouble, getMaxDouble, getMedian, getMinDouble, getMinDouble, getSpan, intersectAny, intersectsAny, subtractAny, transform, unionAnyMethods inherited from class Range
contains, formatTo, getElementType, getMaxValue, getMinValue, isBounded, isEmpty, isMaxIncluded, isMinIncluded, toString
-
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 beNumberinstances.unit- the unit of measurement, ornullif unknown.
-
MeasurementRange
public MeasurementRange(Class<E> type, ValueRange range, 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, Unit<?> unit) Constructs a range ofNumberobjects.- Parameters:
type- the element type, usually one ofFloatorDouble.minValue- the minimal value, ornullif none.isMinIncluded-trueif the minimal value is inclusive, orfalseif exclusive.maxValue- the maximal value, ornullif none.isMaxIncluded-trueif the maximal value is inclusive, orfalseif exclusive.unit- the unit of measurement, ornullif unknown.
-
-
Method Details
-
create
public static MeasurementRange<Float> create(float minValue, boolean isMinIncluded, float maxValue, boolean isMaxIncluded, Unit<?> unit) Constructs a range offloatvalues. 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_INFINITYif none.isMinIncluded-trueif the minimal value is inclusive, orfalseif exclusive.maxValue- the maximal value, orFloat.POSITIVE_INFINITYif none.isMaxIncluded-trueif the maximal value is inclusive, orfalseif exclusive.unit- the unit of measurement, ornullif unknown.- Returns:
- the new range of numeric values for the given endpoints and unit of measurement.
- Throws:
IllegalArgumentException- ifFloat.isNaN(float)istruefor a given value.
-
create
public static MeasurementRange<Double> create(double minValue, boolean isMinIncluded, double maxValue, boolean isMaxIncluded, Unit<?> unit) Constructs a range ofdoublevalues. 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_INFINITYif none.isMinIncluded-trueif the minimal value is inclusive, orfalseif exclusive.maxValue- the maximal value, orDouble.POSITIVE_INFINITYif none.isMaxIncluded-trueif the maximal value is inclusive, orfalseif exclusive.unit- the unit of measurement, ornullif unknown.- Returns:
- the new range of numeric values for the given endpoints and unit of measurement.
- Throws:
IllegalArgumentException- ifDouble.isNaN(double)istruefor a given value.
-
createGreaterThan
Constructs a range ofdoublevalues greater than the given value. TheminValueis 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_INFINITYif none.unit- the unit of measurement, ornullif unknown.- Returns:
- the new range of numeric values greater than the given value.
- Throws:
IllegalArgumentException- ifDouble.isNaN(double)istruefor the given value.- Since:
- 0.6
-
createBestFit
public static MeasurementRange<?> createBestFit(Number minValue, boolean isMinIncluded, Number maxValue, boolean isMaxIncluded, Unit<?> unit) Constructs a range using the smallest type ofNumberthat can hold the given values. This method performs the same work thanNumberRange.createBestFit(…)with an additionalunitargument.This method may return a shared instance, at implementation choice.
- Parameters:
minValue- the minimal value, ornullif none.isMinIncluded-trueif the minimal value is inclusive, orfalseif exclusive.maxValue- the maximal value, ornullif none.isMaxIncluded-trueif the maximal value is inclusive, orfalseif exclusive.unit- the unit of measurement, ornullif unknown.- Returns:
- the new range, or
nullif bothminValueandmaxValuearenull. - See Also:
-
unit
Returns the unit of measurement, ornullif unknown. In principle the unit should never be null, otherwise aNumberRangeshould have been used instead ofMeasurementRange. Nevertheless this method may returnnullif a unit should exist but for some reason is unavailable.- Returns:
- the unit of measurement, or
null.
-
convertTo
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, ornullfor keeping the unit unchanged.- Returns:
- the converted range, or
thisif no conversion is needed. - Throws:
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:
castToin 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,FloatorDouble.- Returns:
- the casted range, or
thisif this range already uses the specified type.
-
contains
Returnstrueif 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:
containsin classRange<E extends Number & Comparable<? super E>>- Parameters:
range- the range to check for inclusion in this range.- Returns:
trueif the given range is included in this range.- Throws:
IllegalArgumentException- if the given range is an instance ofMeasurementRangeusing incommensurable unit of measurement.
-
intersects
Returnstrueif 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:
intersectsin classRange<E extends Number & Comparable<? super E>>- Parameters:
range- the range to check for intersection with this range.- Returns:
trueif the given range intersects this range.- Throws:
IllegalArgumentException- if the given range is an instance ofMeasurementRangeusing 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:
intersectin 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 ofMeasurementRangeusing 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:
unionin 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 ofMeasurementRangeusing 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:
subtractin 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 ofMeasurementRangeusing incommensurable unit of measurement.
-
equals
Compares this measurement range with the specified object for equality. TwoMeasurementRangeinstances 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.NaNorDouble.NaNbit patterns. -
hashCode
public int hashCode()Returns a hash code value for this measurement range.
-