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 of Number.

All Implemented Interfaces:

Serializable, Formattable, Checked­Container<E>, Emptiable, Lenient­Comparable

public class MeasurementRange<E extends Number & Comparable<? super E>>
extends NumberRange<E>

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 of Measurement­Range 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 with this range.
• convert­To(Unit) for converting the unit of measurement.
• cast­To(Class) for casting the range values to another type.

Null unit of measurement

The unit of measurement should not be null, otherwise a Number­Range should be used instead of Measurement­Range. 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 convert­To(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:

• Range­Format
• Range­Set
• Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface CheckedContainer

Checked­Container.Mutability

Modifier and Type	Interface	Description
static enum	Checked­Container.Mutability	Mutability status of a container.

Constructor Summary

Constructors

Constructor	Description
Measurement­Range(Class<E> type, E min­Value, boolean is­Min­Included, E max­Value, boolean is­Max­Included, Unit<?> unit)	Constructs a range of Number objects.
Measurement­Range(Class<E> type, Value­Range range, Unit<?> unit)	Constructs a range of the given type with values from the given annotation.
Measurement­Range(Range<E> range, Unit<?> unit)	Constructs a range with the same values as the specified range and the given unit.

Method Summary

Modifier and Type	Method	Description
<N extends Number & Comparable<? super N>> Measurement­Range<N>	cast­To(Class<N> type)	Casts this range to the specified type.
boolean	contains(Range<? extends E> range)	Returns true if the supplied range is fully contained within this range.
Measurement­Range<E>	convert­To(Unit<?> target­Unit)	Converts this range to the specified unit.
static Measurement­Range<Double>	create(double min­Value, boolean is­Min­Included, double max­Value, boolean is­Max­Included, Unit<?> unit)	Constructs a range of double values.
static Measurement­Range<Float>	create(float min­Value, boolean is­Min­Included, float max­Value, boolean is­Max­Included, Unit<?> unit)	Constructs a range of float values.
static Measurement­Range<?>	create­Best­Fit(Number min­Value, boolean is­Min­Included, Number max­Value, boolean is­Max­Included, Unit<?> unit)	Constructs a range using the smallest type of Number that can hold the given values.
static Measurement­Range<Double>	create­Greater­Than(double min­Value, Unit<?> unit)	Constructs a range of double values greater than the given value.
boolean	equals(Object object, Comparison­Mode mode)	Compares this measurement range with the specified object for equality according the specified criterion.
int	hash­Code()	Returns a hash code value for this measurement range.
Range<E>	intersect(Range<E> range)	Returns the intersection between this range and the given range.
boolean	intersects(Range<? extends E> range)	Returns true if this range intersects the given range.
Range<E>[]	subtract(Range<E> range)	Returns the range of values that are in this range but not in the given range.
Range<E>	union(Range<E> range)	Returns the union of this range with the given range.
Unit<?>	unit()	Returns the unit of measurement, or null if unknown.

Methods inherited from class NumberRange

cast­Or­Copy, contains­Any, contains­Any, create, create, create, create, create, create, create, create­Best­Fit, create­Best­Fit, create­Left­Bounded, get­Max­Double, get­Max­Double, get­Median, get­Min­Double, get­Min­Double, get­Span, intersect­Any, intersects­Any, subtract­Any, transform, union­Any

Modifier and Type	Method	Description
static <N extends Number & Comparable<? super N>> Number­Range<N>	cast­Or­Copy(Range<N> range)	Returns the specified Range as a Number­Range object.
boolean	contains­Any(Number value)	Returns true if this range contains the given value.
boolean	contains­Any(Number­Range<?> range)	Returns true if the supplied range is fully contained within this range.
static Number­Range<Byte>	create(byte min­Value, boolean is­Min­Included, byte max­Value, boolean is­Max­Included)	Constructs a range of byte values.
static Number­Range<Double>	create(double min­Value, boolean is­Min­Included, double max­Value, boolean is­Max­Included)	Constructs a range of double values.
static Number­Range<Float>	create(float min­Value, boolean is­Min­Included, float max­Value, boolean is­Max­Included)	Constructs a range of float values.
static Number­Range<Integer>	create(int min­Value, boolean is­Min­Included, int max­Value, boolean is­Max­Included)	Constructs a range of int values.
static Number­Range<Long>	create(long min­Value, boolean is­Min­Included, long max­Value, boolean is­Max­Included)	Constructs a range of long values.
static Number­Range<Short>	create(short min­Value, boolean is­Min­Included, short max­Value, boolean is­Max­Included)	Constructs a range of short values.
static <N extends Number & Comparable<? super N>> Number­Range<N>	create(Class<N> type, N value)	Constructs a range containing a single value of the given type.
static Number­Range<?>	create­Best­Fit(boolean as­Float, Number min­Value, boolean is­Min­Included, Number max­Value, boolean is­Max­Included)	Constructs a range using the smallest integer type or floating point type that can hold the given values.
static Number­Range<?>	create­Best­Fit(Number min­Value, boolean is­Min­Included, Number max­Value, boolean is­Max­Included)	Constructs a range using the smallest type of Number that can hold the given values.
static Number­Range<Integer>	create­Left­Bounded(int min­Value, boolean is­Min­Included)	Constructs a range of int values without upper bound.
double	get­Max­Double()	Returns the maximum value as a double.
double	get­Max­Double(boolean inclusive)	Returns the maximum value with the specified inclusive or exclusive state.
double	get­Median()	Computes the average of minimum and maximum values.
double	get­Min­Double()	Returns the minimum value as a double.
double	get­Min­Double(boolean inclusive)	Returns the minimum value with the specified inclusive or exclusive state.
double	get­Span()	Computes the difference between minimum and maximum values.
Number­Range<?>	intersect­Any(Number­Range<?> range)	Returns the union of this range with the given range.
boolean	intersects­Any(Number­Range<?> range)	Returns true if the supplied range intersects this range.
Number­Range<?>[]	subtract­Any(Number­Range<?> range)	Returns the range of values that are in this range but not in the given range.
Number­Range<?>	transform(Math­Transform1D converter)	Returns this range converted using the given converter.
Number­Range<?>	union­Any(Number­Range<?> range)	Returns the union of this range with the given range.

Methods inherited from class Range

contains, equals, format­To, get­Element­Type, get­Max­Value, get­Min­Value, get­Mutability, is­Bounded, is­Empty, is­Max­Included, is­Min­Included, to­String

Modifier and Type	Method	Description
boolean	contains(E value)	Returns true if this range contains the given value.
final boolean	equals(Object object)	Compares this range with the given object for equality.
void	format­To(Formatter formatter, int flags, int width, int precision)	Formats this range using the provided formatter.
Class<E>	get­Element­Type()	Returns the base type of elements in this range.
E	get­Max­Value()	Returns the maximal value, or null if this range has no upper limit.
E	get­Min­Value()	Returns the minimal value, or null if this range has no lower limit.
Checked­Container.Mutability	get­Mutability()	Indicates that this range is immutable (at least by default).
boolean	is­Bounded()	Returns true if this range is both left-bounded and right-bounded.
final boolean	is­Empty()	Returns true if this range is empty.
boolean	is­Max­Included()	Returns true if the maximal value is inclusive, or false if exclusive.
boolean	is­Min­Included()	Returns true if the minimal value is inclusive, or false if exclusive.
String	to­String()	Returns a unlocalized string representation of this range.

Methods inherited from class Object

clone, finalize, get­Class, notify, notify­All, wait, wait, wait

Methods inherited from interface LenientComparable

get­Standard­Type

Modifier and Type	Method	Description
default Type	get­Standard­Type()	Returns the interface or base class that defines the public properties of this instance.

Constructor Details

MeasurementRange

public MeasurementRange(Range<E> range,
 Unit<?> unit)

Constructs a range with the same values as 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 be Number instances.

unit - the unit of measurement, or null if 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.

Parameters:

type - the element type, restricted to one of Byte, Short, Integer, Long, Float or Double.

range - the range of values.

unit - the unit of measurement, or null if unknown.

Throws:

Illegal­Argument­Exception - if the given type is not one of the primitive wrappers for numeric types.

MeasurementRange

public MeasurementRange(Class<E> type,
 E minValue,
 boolean isMinIncluded,
 E maxValue,
 boolean isMaxIncluded,
 Unit<?> unit)

Constructs a range of Number objects.

Parameters:

type - the element type, usually one of Float or Double.

min­Value - the minimal value, or null if none.

is­Min­Included - true if the minimal value is inclusive, or false if exclusive.

max­Value - the maximal value, or null if none.

is­Max­Included - true if the maximal value is inclusive, or false if exclusive.

unit - the unit of measurement, or null if unknown.

Method Details

create

public static MeasurementRange<Float> create(float minValue,
 boolean isMinIncluded,
 float maxValue,
 boolean isMaxIncluded,
 Unit<?> unit)

Constructs a range of float 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:

min­Value - the minimal value, or Float.NEGATIVE_INFINITY if none.

is­Min­Included - true if the minimal value is inclusive, or false if exclusive.

max­Value - the maximal value, or Float.POSITIVE_INFINITY if none.

is­Max­Included - true if the maximal value is inclusive, or false if exclusive.

unit - the unit of measurement, or null if unknown.

Returns:

the new range of numeric values for the given endpoints and unit of measurement.

Throws:

Illegal­Argument­Exception - if Float.is­Na­N(float) is true for a given value.

create

public static MeasurementRange<Double> create(double minValue,
 boolean isMinIncluded,
 double maxValue,
 boolean isMaxIncluded,
 Unit<?> unit)

Constructs a range of double 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:

min­Value - the minimal value, or Double.NEGATIVE_INFINITY if none.

is­Min­Included - true if the minimal value is inclusive, or false if exclusive.

max­Value - the maximal value, or Double.POSITIVE_INFINITY if none.

is­Max­Included - true if the maximal value is inclusive, or false if exclusive.

unit - the unit of measurement, or null if unknown.

Returns:

the new range of numeric values for the given endpoints and unit of measurement.

Throws:

Illegal­Argument­Exception - if Double.is­Na­N(double) is true for a given value.

createGreaterThan

public static MeasurementRange<Double> createGreaterThan(double minValue,
 Unit<?> unit)

Constructs a range of double values greater than the given value. The min­Value is often zero for creating a range of strictly positive values. This method may return a shared instance, at implementation choice.

Parameters:

min­Value - the minimal value (exclusive), or Double.NEGATIVE_INFINITY if none.

unit - the unit of measurement, or null if unknown.

Returns:

the new range of numeric values greater than the given value.

Throws:

Illegal­Argument­Exception - if Double.is­Na­N(double) is true for 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 of Number that can hold the given values. This method performs the same work as Number­Range.create­Best­Fit(…) with an additional unit argument.

This method may return a shared instance, at implementation choice.

Parameters:

min­Value - the minimal value, or null if none.

is­Min­Included - true if the minimal value is inclusive, or false if exclusive.

max­Value - the maximal value, or null if none.

is­Max­Included - true if the maximal value is inclusive, or false if exclusive.

unit - the unit of measurement, or null if unknown.

Returns:

the new range, or null if both min­Value and max­Value are null.

See Also:

• Number­Range.create­Best­Fit(Number, boolean, Number, boolean)

unit

public Unit<?> unit()

Returns the unit of measurement, or null if unknown. In principle the unit should never be null, otherwise a Number­Range should have been used instead of Measurement­Range. Nevertheless this method may return null if a unit should exist but for some reason is unavailable.

Returns:

the unit of measurement, or null.

convertTo

public MeasurementRange<E> convertTo(Unit<?> targetUnit)
                              throws 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:

target­Unit - the target unit, or null for keeping the unit unchanged.

Returns:

the converted range, or this if no conversion is needed.

Throws:

Incommensurable­Exception - if the target unit are not compatible with this range unit.

castTo

public <N extends Number & Comparable<? super N>>
MeasurementRange<N> castTo(Class<N> type)

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:

cast­To in class Number­Range<E extends Number & Comparable<? super E>>

Type Parameters:

N - the class to cast to.

Parameters:

type - the class to cast to. Must be one of Byte, Short, Integer, Long, Float or Double.

Returns:

the cast range, or this if this range already uses the specified type.

contains

public boolean contains(Range<? extends E> range)
                 throws IllegalArgumentException

Returns true if the supplied range is fully contained within this range. If the given range is an instance of Measurement­Range, 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 class Range<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:

Illegal­Argument­Exception - if the given range is an instance of Measurement­Range using incommensurable unit of measurement.

intersects

public boolean intersects(Range<? extends E> range)
                   throws IllegalArgumentException

Returns true if this range intersects the given range. If the given range is an instance of Measurement­Range, 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 class Range<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:

Illegal­Argument­Exception - if the given range is an instance of Measurement­Range using incommensurable unit of measurement.

intersect

public Range<E> intersect(Range<E> range)
                   throws IllegalArgumentException

Returns the intersection between this range and the given range. If the given range is an instance of Measurement­Range, 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 class Range<E extends Number & Comparable<? super E>>

Parameters:

range - the range to intersect.

Returns:

the intersection of this range with the given range.

Throws:

Illegal­Argument­Exception - if the given range is an instance of Measurement­Range using incommensurable unit of measurement.

union

public Range<E> union(Range<E> range)
               throws IllegalArgumentException

Returns the union of this range with the given range. If the given range is an instance of Measurement­Range, 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 class Range<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:

Illegal­Argument­Exception - if the given range is an instance of Measurement­Range using incommensurable unit of measurement.

subtract

public Range<E>[] subtract(Range<E> range)
                    throws IllegalArgumentException

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.

If the given range is an instance of Measurement­Range, 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 class Range<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:

Illegal­Argument­Exception - if the given range is an instance of Measurement­Range using incommensurable unit of measurement.

equals

public boolean equals(Object object,
 ComparisonMode mode)

Compares this measurement range with the specified object for equality according the specified criterion. Two Measurement­Range instances are considered equal if they met all conditions documented in the parent class and their units are equal. Note that this comparison does not distinguish the various Float.Na­N or Double.Na­N bit patterns.

Specified by:

equals in interface Lenient­Comparable

Overrides:

equals in class Range<E extends Number & Comparable<? super E>>

Parameters:

object - the object to compare with this range for equality.

mode - the strictness level of the comparison.

Returns:

true if the given object is equal to this range at the given strictness level.

Since:

1.7

See Also:

• Utilities.deep­Equals(Object, Object, Comparison­Mode)

hashCode

public int hashCode()

Returns a hash code value for this measurement range.

Overrides:

hash­Code in class Range<E extends Number & Comparable<? super E>>

Returns:

a hash code value for this range.