public final class Amount<Q extends javax.measure.quantity.Quantity> extends java.lang.Object implements Measurable<Q>, org.jscience.mathematics.structure.Field<Amount<?>>, java.io.Serializable, javolution.lang.Immutable
This class represents a determinate or estimated amount for which
operations such as addition, subtraction, multiplication and division
can be performed (it implements the Field
interface).
The nature of an amount can be deduced from its parameterization
(compile time) or its unit
(run time).
Its precision is given by its error
.
Amounts can be exact
, in which case they can be
expressed as an exact long
integer in the amount unit.
The framework tries to keep amount exact as much as possible.
For example:[code]
Amount
Errors (including numeric errors) are calculated using numeric intervals.
It is possible to resolve systems of linear equations involving
matrices
, 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, nonexact amounts are shown using the plus/minus
character ('±') (see AmountFormat
). For example,
"(2.0 ± 0.001) km/s"
represents a velocity of
2 km/s with an absolute error of ± 1 m/s. Exact amount use an
integer notation (no decimal point, e.g. "2000 m"
).
Operations between different amounts may or may not be authorized
based upon the current PhysicalModel
. For example, adding Amount<Length> and
Amount<Duration> is not allowed by the
StandardModel
,
but is authorized with the RelativisticModel
.
 Version:
 4.0, June 4, 2007
 Author:
 JeanMarie Dautelle
 See Also:

Wikipedia: Measuring
Modified on 8/14/2007 by Michael J. North to allow Groovy comparision operators
to work despite the following issues:
http://jira.codehaus.org/browse/GROOVY1888
http://jira.codehaus.org/browse/GROOVY1889,
Serialized Form


Field Summary
Fields
Modifier and Type
Field and Description
static Amount<javax.measure.quantity.Dimensionless>
ONE
Holds a dimensionless measure of one (exact).
static Amount<javax.measure.quantity.Dimensionless>
ZERO
Holds a dimensionless measure of zero (exact).

Method Summary
All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type
Method and Description
Amount<Q>
abs()
Returns the absolute value of this measure.
boolean
approximates(Amount that)
Indicates if this measure approximates that measure.
int
compareTo(java.lang.Object that)
Compares this measure with the specified measurable object.
Amount<Q>
copy()
Amount<? extends javax.measure.quantity.Quantity>
divide(Amount that)
Returns this measure divided by the one specified.
Amount<Q>
divide(double divisor)
Returns this measure divided by the specified approximate divisor
(dimensionless).
Amount<Q>
divide(long divisor)
Returns this measure divided by the specified exact divisor
(dimensionless).
double
doubleValue(javax.measure.unit.Unit<Q> unit)
Returns the estimated value of this measurable 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.
javax.measure.unit.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.
Amount<? extends javax.measure.quantity.Quantity>
inverse()
Returns the multiplicative inverse of this measure.
boolean
isExact()
Indicates if this measure amount is exact.
boolean
isGreaterThan(Amount<Q> that)
Indicates if this measure is ordered after that measure
(independently of the measure unit).
boolean
isLargerThan(Amount<Q> that)
Compares this measure with that measure ignoring the sign.
boolean
isLessThan(Amount<Q> that)
Indicates if this measure is ordered before that measure
(independently of the measure unit).
long
longValue(javax.measure.unit.Unit<Q> unit)
Returns the estimated value of this quantity stated in the specified
unit as a long
.
Amount<Q>
minus(Amount that)
Returns the difference of this measure with the one specified.
Amount<Q>
opposite()
Returns the opposite of this measure.
Amount<Q>
plus(Amount that)
Returns the sum of this measure with the one specified.
Amount<? extends javax.measure.quantity.Quantity>
pow(int exp)
Returns this measure raised at the specified exponent.
static <Q extends javax.measure.quantity.Quantity>
Amount<Q>
rangeOf(double minimum,
double maximum,
javax.measure.unit.Unit<Q> unit)
Returns the measure corresponding to the specified interval stated
in the specified unit.
Amount<? extends javax.measure.quantity.Quantity>
root(int n)
Returns the given root of this measure.
Amount<? extends javax.measure.quantity.Quantity>
sqrt()
Returns the square root of this measure.
Amount<? extends javax.measure.quantity.Quantity>
times(Amount that)
Returns the product of this measure with the one specified.
Amount<Q>
times(double factor)
Returns this measure scaled by the specified approximate factor
(dimensionless).
Amount<Q>
times(long factor)
Returns this measure scaled by the specified exact factor
(dimensionless).
<R extends javax.measure.quantity.Quantity>
Amount<R>
to(javax.measure.unit.Unit<R> unit)
Returns the measure equivalent to this measure but stated in the
specified unit.
java.lang.String
toString()
Returns the text representation of this amount as a
java.lang.String
.
javolution.text.Text
toText()
Returns the text representation of this measure.
static Amount<?>
valueOf(java.lang.CharSequence csq)
Returns the measure represented by the specified character sequence.
static <Q extends javax.measure.quantity.Quantity>
Amount<Q>
valueOf(double value,
double error,
javax.measure.unit.Unit<Q> unit)
Returns the measure corresponding to the specified approximate value
and measurement error, both stated in the specified unit.
static <Q extends javax.measure.quantity.Quantity>
Amount<Q>
valueOf(double value,
javax.measure.unit.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 javax.measure.quantity.Quantity>
Amount<Q>
valueOf(long value,
javax.measure.unit.Unit<Q> unit)
Returns the exact measure corresponding to the value stated in the
specified unit.


Field Detail

ZERO
public static final Amount<javax.measure.quantity.Dimensionless> ZERO
Holds a dimensionless measure of zero (exact).

ONE
public static final Amount<javax.measure.quantity.Dimensionless> ONE
Holds a dimensionless measure of one (exact).

Method Detail

valueOf
public static <Q extends javax.measure.quantity.Quantity> Amount<Q> valueOf(long value,
javax.measure.unit.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 javax.measure.quantity.Quantity> Amount<Q> valueOf(double value,
javax.measure.unit.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 javax.measure.quantity.Quantity> Amount<Q> valueOf(double value,
double error,
javax.measure.unit.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 javax.measure.quantity.Quantity> Amount<Q> rangeOf(double minimum,
double maximum,
javax.measure.unit.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 Amount<?> valueOf(java.lang.CharSequence csq)
Returns the measure represented by the specified character sequence.
 Parameters:
csq
 the character sequence.
 Returns:
AmountFormat.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 javax.measure.unit.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 org.jscience.physics.amount.AmountException
Returns the exact value for this measure stated in this measure
unit
.

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 javax.measure.quantity.Quantity> Amount<R> to(javax.measure.unit.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:
javax.measure.converter.ConversionException
 if the current model does not allows for
conversion to the specified unit.

opposite
public Amount<Q> opposite()
Returns the opposite of this measure.
 Specified by:
opposite
in interface org.jscience.mathematics.structure.GroupAdditive<Amount<?>>
 Returns:
this
.

plus
public Amount<Q> plus(Amount that)
throws javax.measure.converter.ConversionException
Returns the sum of this measure with the one specified.
 Specified by:
plus
in interface org.jscience.mathematics.structure.GroupAdditive<Amount<?>>
 Parameters:
that
 the measure to be added.
 Returns:
this + that
.
 Throws:
javax.measure.converter.ConversionException
 if the current model does not allows for
these quantities to be added.

minus
public Amount<Q> minus(Amount that)
throws javax.measure.converter.ConversionException
Returns the difference of this measure with the one specified.
 Parameters:
that
 the measure to be subtracted.
 Returns:
this  that
.
 Throws:
javax.measure.converter.ConversionException
 if the current model does not allows for
these quantities to be subtracted.

times
public Amount<Q> times(long factor)
Returns this measure scaled by the specified exact factor
(dimensionless).
 Parameters:
factor
 the scaling factor.
 Returns:
this · factor
.

times
public Amount<Q> times(double factor)
Returns this measure scaled by the specified approximate factor
(dimensionless).
 Parameters:
factor
 the scaling factor.
 Returns:
this · factor
.

times
public Amount<? extends javax.measure.quantity.Quantity> times(Amount that)
Returns the product of this measure with the one specified.

inverse
public Amount<? extends javax.measure.quantity.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 org.jscience.mathematics.structure.GroupMultiplicative<Amount<?>>
 Returns:
1 / this
.

divide
public Amount<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 Amount<Q> divide(double divisor)
Returns this measure divided by the specified approximate divisor
(dimensionless).
 Parameters:
divisor
 the approximated divisor.
 Returns:
this / divisor
.

divide
public Amount<? extends javax.measure.quantity.Quantity> divide(Amount that)
Returns this measure divided by the one specified.
 Parameters:
that
 the measure divisor.
 Returns:
this / that
.

sqrt
public Amount<? extends javax.measure.quantity.Quantity> sqrt()
Returns the square root of this measure.
 Returns:
sqrt(this)

root
public Amount<? extends javax.measure.quantity.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 Amount<? extends javax.measure.quantity.Quantity> pow(int exp)
Returns this measure raised at the specified exponent.
 Parameters:
exp
 the exponent.
 Returns:
this^{exp}

compareTo
public int compareTo(java.lang.Object that)
Compares this measure with the specified measurable object.
 Specified by:
compareTo
in interface java.lang.Comparable
 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 measurable.
 Throws:
javax.measure.converter.ConversionException
 if the current model does not allows for
these measure to be compared.
Modified on 8/14/2007 by Michael J. North to allow Groovy comparision operators
to work despite the following issues:
http://jira.codehaus.org/browse/GROOVY1888
http://jira.codehaus.org/browse/GROOVY1889

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.
Modified on 8/14/2007 by Michael J. North to allow Groovy comparision operators
to work despite the following issues:
http://jira.codehaus.org/browse/GROOVY1888
http://jira.codehaus.org/browse/GROOVY1889

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(Amount 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(Amount<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(Amount<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(Amount<Q> that)
Compares this measure with that measure ignoring the sign.
 Returns:
this > that

toText
public javolution.text.Text toText()
Returns the text representation of this measure.
 Returns:
AmountFormat.getInstance().format(this)

toString
public final java.lang.String toString()
Returns the text representation of this amount as a
java.lang.String
.
 Overrides:
toString
in class java.lang.Object
 Returns:
toText().toString()

doubleValue
public double doubleValue(javax.measure.unit.Unit<Q> unit)
Description copied from interface: Measurable
Returns the estimated value of this measurable quantity stated
in the specified unit as a double
.
 Specified by:
doubleValue
in interface Measurable<Q extends javax.measure.quantity.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(javax.measure.unit.Unit<Q> unit)
Description copied from interface: Measurable
Returns the estimated value of this quantity stated in the specified
unit as a long
.
 Specified by:
longValue
in interface Measurable<Q extends javax.measure.quantity.Quantity>
 Parameters:
unit
 the unit in which the measurement value is stated.
 Returns:
 the numeric value after conversion to type
long
.