org.jscience.physics.measures
Class Measure<Q extends Quantity>

java.lang.Object
  javolution.context.RealtimeObject
      org.jscience.physics.measures.Measure<Q>

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Measure>, Quantity<Q>, Realtime, Immutable, Field<Measure<?>>, GroupAdditive<Measure<?>>, GroupMultiplicative<Measure<?>>, Ring<Measure<?>>, Structure<Measure<?>>

public final class Measure<Q extends Quantity>
extends RealtimeObject
implements Quantity<Q>, Field<Measure<?>>, java.lang.Comparable<Measure>, java.io.Serializable, Immutable

This class represents a measurable amount; the nature of the amount is deduced from the measure unit; the quality of the measure is given by the measurement error.

Measures can be exact, in which case they can be expressed as an exact long integer in the measure unit. The framework tries to keep measures exact as much as possible. For example:

        Measure<Length> m = Measure.valueOf(33, FOOT).divide(11).times(2);
        System.out.println(m);
        System.out.println(m.isExact() ? "exact" : "inexact");
        System.out.println(m.getExactValue());
        > 6 ft
        > exact
        > 6

Errors (including numeric errors) are calculated using numeric intervals. It is possible to resolve systems of linear equations involving measures (ref. Matrix), even if the system is close to singularity; in which case the error associated with some (or all) components of the solution may be large.

By default, non-exact measure instances are shown using the plus/minus character ('±') (see MeasureFormat). For example, "(2.0 ± 0.001) km/s" represents a velocity of 2 km/s with an absolute error of ± 1 m/s. Exact measurements use an integer notation (no decimal point, e.g. "2000 m").

Operations between different measures may or may not be authorized based upon the current PhysicalModel. For example, adding Measure<Length> and Measure<Duration> is not allowed by the StandardModel, but is authorized with the RelativisticModel.

Version:

3.0, February 26, 2006

Author:

Jean-Marie Dautelle

See Also:

Wikipedia: Measuring, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javolution.context.RealtimeObject

RealtimeObject.Factory<T extends RealtimeObject>

Nested classes/interfaces inherited from interface javolution.context.Realtime

Realtime.ObjectSpace

Field Summary

static Measure<Dimensionless>	ONE Holds a dimensionless measure of one (exact).
protected static XMLFormat<Measure>	XML Holds the default XML representation for measures.
static Measure<Dimensionless>	ZERO Holds a dimensionless measure of zero (exact).

Method Summary

Measure<Q>	abs() Returns the absolute value of this measure.
boolean	approximates(Measure that) Indicates if this measure approximates that measure.
int	compareTo(Measure that) Compares this measure with the one specified regardless of the units in which this measure and that measure are stated.
Measure<Q>	divide(double divisor) Returns this measure divided by the specified approximate divisor (dimensionless).
Measure<Q>	divide(long divisor) Returns this measure divided by the specified exact divisor (dimensionless).
Measure<? extends Quantity>	divide(Measure that) Returns this measure divided by the one specified.
double	doubleValue(Unit<Q> unit) Returns the estimated value of this quantity stated in the specified unit as a double.
boolean	equals(java.lang.Object that) Compares this measure against the specified object for strict equality (same value interval and same units).
double	getAbsoluteError() Returns the value by which theestimated value may differ from the true value (all stated in base units).
double	getEstimatedValue() Returns the estimated value for this measure stated in this measure unit.
long	getExactValue() Returns the exact value for this measure stated in this measure unit.
double	getMaximumValue() Returns the upper bound interval value for this measure stated in this measure unit.
double	getMinimumValue() Returns the lower bound interval value for this measure stated in this measure unit.
double	getRelativeError() Returns the percentage by which the estimated amount may differ from the true amount.
Unit<Q>	getUnit() Returns the unit in which the estimated value and absolute error are stated.
int	hashCode() Returns the hash code for this measure.
Measure<? extends Quantity>	inverse() Returns the multiplicative inverse of this measure.
boolean	isExact() Indicates if this measure amount is exact.
boolean	isGreaterThan(Measure<Q> that) Indicates if this measure is ordered after that measure (independently of the measure unit).
boolean	isLargerThan(Measure<Q> that) Compares this measure with that measure ignoring the sign.
boolean	isLessThan(Measure<Q> that) Indicates if this measure is ordered before that measure (independently of the measure unit).
long	longValue(Unit<Q> unit) Returns the estimated value of this quantity stated in the specified unit as a long.
Measure<Q>	minus(Measure that) Returns the difference of this measure with the one specified.
Measure<Q>	opposite() Returns the opposite of this measure.
Measure<Q>	plus(Measure that) Returns the sum of this measure with the one specified.
Measure<? extends Quantity>	pow(int exp) Returns this measure raised at the specified exponent.
static <Q extends Quantity> Measure<Q>	rangeOf(double minimum, double maximum, Unit<Q> unit) Returns the measure corresponding to the specified interval stated in the specified unit.
Measure<? extends Quantity>	root(int n) Returns the given root of this measure.
Measure<? extends Quantity>	sqrt() Returns the square root of this measure.
Measure<Q>	times(double factor) Returns this measure scaled by the specified approximate factor (dimensionless).
Measure<Q>	times(long factor) Returns this measure scaled by the specified exact factor (dimensionless).
Measure<? extends Quantity>	times(Measure that) Returns the product of this measure with the one specified.
<R extends Quantity> Measure<R>	to(Unit<R> unit) Returns the measure equivalent to this measure but stated in the specified unit.
Text	toText() Returns the text representation of this measure.
static Measure<?>	valueOf(java.lang.CharSequence csq) Returns the measure represented by the specified character sequence.
static <Q extends Quantity> Measure<Q>	valueOf(double value, double error, Unit<Q> unit) Returns the measure corresponding to the specified approximate value and measurement error, both stated in the specified unit.
static <Q extends Quantity> Measure<Q>	valueOf(double value, Unit<Q> unit) Returns the measure corresponding to an approximate value (double) stated in the specified unit; the precision of the measure is assumed to be the double precision (64 bits IEEE 754 format).
static <Q extends Quantity> Measure<Q>	valueOf(long value, Unit<Q> unit) Returns the exact measure corresponding to the value stated in the specified unit.

Methods inherited from class javolution.context.RealtimeObject

export, isLocal, move, moveHeap, preserve, toString, unpreserve

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface javolution.context.Realtime

move

Field Detail

ZERO

public static final Measure<Dimensionless> ZERO

Holds a dimensionless measure of zero (exact).

ONE

public static final Measure<Dimensionless> ONE

Holds a dimensionless measure of one (exact).

XML

protected static final XMLFormat<Measure> XML

Holds the default XML representation for measures. This representation consists of a value, an unit and an optional error attribute when the measure is not exact. The unit attribute determinates the measurement type. For example:

 <Measure value="12" unit="µA"/>

represents an electric current measurement.

Method Detail

valueOf

public static <Q extends Quantity> Measure<Q> valueOf(long value,
                                                      Unit<Q> unit)

Returns the exact measure corresponding to the value stated in the specified unit.

Parameters:

value - the exact value stated in the specified unit.

unit - the unit in which the value is stated.

Returns:

the corresponding measure object.

valueOf

public static <Q extends Quantity> Measure<Q> valueOf(double value,
                                                      Unit<Q> unit)

Returns the measure corresponding to an approximate value (double) stated in the specified unit; the precision of the measure is assumed to be the double precision (64 bits IEEE 754 format).

Parameters:

value - the estimated value (± LSB) stated in the specified unit.

unit - the unit in which the value is stated.

Returns:

the corresponding measure object.

valueOf

public static <Q extends Quantity> Measure<Q> valueOf(double value,
                                                      double error,
                                                      Unit<Q> unit)

Returns the measure corresponding to the specified approximate value and measurement error, both stated in the specified unit.

Parameters:

value - the estimated amount (± error) stated in the specified unit.

error - the measurement error (absolute).

unit - the unit in which the amount and the error are stated.

Returns:

the corresponding measure object.

Throws:

java.lang.IllegalArgumentException - if error < 0.0

rangeOf

public static <Q extends Quantity> Measure<Q> rangeOf(double minimum,
                                                      double maximum,
                                                      Unit<Q> unit)

Returns the measure corresponding to the specified interval stated in the specified unit.

Parameters:

minimum - the lower bound for the measure value.

maximum - the upper bound for the measure value.

unit - the unit for both the minimum and maximum values.

Returns:

the corresponding measure object.

Throws:

java.lang.IllegalArgumentException - if minimum > maximum

valueOf

public static Measure<?> valueOf(java.lang.CharSequence csq)

Returns the measure represented by the specified character sequence.

Parameters:

csq - the character sequence.

Returns:

MeasureFormat.getInstance().parse(csq)

isExact

public boolean isExact()

Indicates if this measure amount is exact. An exact amount is guarantee exact only when stated in this measure unit (e.g. this.longValue()); stating the amount in any other unit may introduce conversion errors.

Returns:

true if this measure is exact; false otherwise.

getUnit

public Unit<Q> getUnit()

Returns the unit in which the estimated value and absolute error are stated.

Returns:

the measure unit.

getExactValue

public long getExactValue()
                   throws MeasureException

Returns the exact value for this measure stated in this measure unit.

Returns:

the exact measure value (long) stated in this measure's unit

Throws:

MeasureException - if this measure is not isExact()

getEstimatedValue

public double getEstimatedValue()

Returns the estimated value for this measure stated in this measure unit.

Returns:

the median value of the measure interval.

getMinimumValue

public double getMinimumValue()

Returns the lower bound interval value for this measure stated in this measure unit.

Returns:

the minimum value.

getMaximumValue

public double getMaximumValue()

Returns the upper bound interval value for this measure stated in this measure unit.

Returns:

the maximum value.

getAbsoluteError

public double getAbsoluteError()

Returns the value by which theestimated value may differ from the true value (all stated in base units).

Returns:

the absolute error stated in base units.

getRelativeError

public double getRelativeError()

Returns the percentage by which the estimated amount may differ from the true amount.

Returns:

the relative error.

to

public <R extends Quantity> Measure<R> to(Unit<R> unit)

Returns the measure equivalent to this measure but stated in the specified unit. The returned measure may not be exact even if this measure is exact due to conversion errors.

Parameters:

unit - the unit of the measure to be returned.

Returns:

a measure equivalent to this measure but stated in the specified unit.

Throws:

ConversionException - if the current model does not allows for conversion to the specified unit.

opposite

public Measure<Q> opposite()

Returns the opposite of this measure.

Specified by:

opposite in interface GroupAdditive<Measure<?>>

Returns:

-this.

plus

public Measure<Q> plus(Measure that)
                                 throws ConversionException

Returns the sum of this measure with the one specified.

Specified by:

plus in interface GroupAdditive<Measure<?>>

Parameters:

that - the measure to be added.

Returns:

this + that.

Throws:

ConversionException - if the current model does not allows for these quantities to be added.

minus

public Measure<Q> minus(Measure that)
                                  throws ConversionException

Returns the difference of this measure with the one specified.

Parameters:

that - the measure to be subtracted.

Returns:

this - that.

Throws:

ConversionException - if the current model does not allows for these quantities to be subtracted.

times

public Measure<Q> times(long factor)

Returns this measure scaled by the specified exact factor (dimensionless).

Parameters:

factor - the scaling factor.

Returns:

this · factor.

times

public Measure<Q> times(double factor)

Returns this measure scaled by the specified approximate factor (dimensionless).

Parameters:

factor - the scaling factor.

Returns:

this · factor.

times

public Measure<? extends Quantity> times(Measure that)

Returns the product of this measure with the one specified.

Specified by:

times in interface GroupMultiplicative<Measure<?>>

Specified by:

times in interface Ring<Measure<?>>

Parameters:

that - the measure multiplier.

Returns:

this · that.

inverse

public Measure<? extends Quantity> inverse()

Returns the multiplicative inverse of this measure. If this measure is possibly zero, then the result is unbounded (]-infinity, +infinity[).

Specified by:

inverse in interface GroupMultiplicative<Measure<?>>

Returns:

1 / this.

divide

public Measure<Q> divide(long divisor)

Returns this measure divided by the specified exact divisor (dimensionless).

Parameters:

divisor - the exact divisor.

Returns:

this / divisor.

Throws:

java.lang.ArithmeticException - if this measure is exact and the specified divisor is zero.

divide

public Measure<Q> divide(double divisor)

Returns this measure divided by the specified approximate divisor (dimensionless).

Parameters:

divisor - the approximated divisor.

Returns:

this / divisor.

divide

public Measure<? extends Quantity> divide(Measure that)

Returns this measure divided by the one specified.

Parameters:

that - the measure divisor.

Returns:

this / that.

abs

public Measure<Q> abs()

Returns the absolute value of this measure.

Returns:

|this|.

sqrt

public Measure<? extends Quantity> sqrt()

Returns the square root of this measure.

Returns:

sqrt(this)

root

public Measure<? extends Quantity> root(int n)

Returns the given root of this measure.

Parameters:

n - the root's order (n != 0).

Returns:

the result of taking the given root of this quantity.

Throws:

java.lang.ArithmeticException - if n == 0.

pow

public Measure<? extends Quantity> pow(int exp)

Returns this measure raised at the specified exponent.

Parameters:

exp - the exponent.

Returns:

thisexp

compareTo

public int compareTo(Measure that)

Compares this measure with the one specified regardless of the units in which this measure and that measure are stated.

Specified by:

compareTo in interface java.lang.Comparable<Measure>

Parameters:

that - the measure to compare with.

Returns:

a negative integer, zero, or a positive integer as this measure is less than, equal to, or greater than that measure.

Throws:

ConversionException - if the current model does not allows for these measure to be compared.

equals

public boolean equals(java.lang.Object that)

Compares this measure against the specified object for strict equality (same value interval and same units).

Overrides:

equals in class java.lang.Object

Parameters:

that - the object to compare with.

Returns:

true if this measure is identical to that measure; false otherwise.

hashCode

public int hashCode()

Returns the hash code for this measure.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value.

approximates

public boolean approximates(Measure that)

Indicates if this measure approximates that measure. Measures are considered approximately equals if their value intervals overlaps. It should be noted that less accurate measurements are more likely to be approximately equals. It is therefore recommended to ensure that the measurement error is not too large before testing for approximate equality.

Returns:

this ≅ that

isLessThan

public boolean isLessThan(Measure<Q> that)

Indicates if this measure is ordered before that measure (independently of the measure unit).

Returns:

this.compareTo(that) < 0.

isGreaterThan

public boolean isGreaterThan(Measure<Q> that)

Indicates if this measure is ordered after that measure (independently of the measure unit).

Returns:

this.compareTo(that) > 0.

isLargerThan

public boolean isLargerThan(Measure<Q> that)

Compares this measure with that measure ignoring the sign.

Returns:

|this| > |that|

toText

public Text toText()

Returns the text representation of this measure.

Specified by:

toText in interface Realtime

Overrides:

toText in class RealtimeObject

Returns:

MeasureFormat.getInstance().format(this)

doubleValue

public double doubleValue(Unit<Q> unit)

Description copied from interface: Quantity

Returns the estimated value of this quantity stated in the specified unit as a double.

Specified by:

doubleValue in interface Quantity<Q extends Quantity>

Parameters:

unit - the unit in which the measurement value is stated.

Returns:

the numeric value after conversion to type double.

longValue

public final long longValue(Unit<Q> unit)

Description copied from interface: Quantity

Returns the estimated value of this quantity stated in the specified unit as a long.

Specified by:

longValue in interface Quantity<Q extends Quantity>

Parameters:

unit - the unit in which the measurement value is stated.

Returns:

the numeric value after conversion to type long.