

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object org.jscience.measure.Amount<Q>
public final class Amount<Q extends Quantity>
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
.
 See Also:

Wikipedia: Measuring,
Serialized Form
Field Summary
static Amount<Dimensionless>
ONE
Holds a dimensionless measure of one (exact).
protected static javolution.xml.XMLFormat<Amount>
XML
Holds the default XML representation for measures.
static Amount<Dimensionless>
ZERO
Holds a dimensionless measure of zero (exact).
Method Summary
Amount<Q>
abs()
Returns the absolute value of this measure.
boolean
approximates(Amount that)
Indicates if this measure approximates that measure.
int
compareTo(Measurable<Q> that)
Compares this measure with the specified measurable object.
Amount<Q>
copy()
Amount<? extends 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(Unit<Q> unit)
Returns the value of this measurable 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.
Amount<? extends 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(Unit<Q> unit)
Returns the estimated integral value of this measurable 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 Quantity>
pow(int exp)
Returns this measure raised at the specified exponent.
static
<Q extends Quantity>
Amount<Q>
rangeOf(double minimum,
double maximum,
Unit<Q> unit)
Returns the measure corresponding to the specified interval stated
in the specified unit.
Amount<? extends Quantity>
root(int n)
Returns the given root of this measure.
Amount<? extends Quantity>
sqrt()
Returns the square root of this measure.
Amount<? extends 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 Quantity>
Amount<R>
to(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 Quantity>
Amount<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>
Amount<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>
Amount<Q>
valueOf(long value,
Unit<Q> unit)
Returns the exact measure corresponding to the value stated in the
specified unit.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Field Detail
ZERO
public static final Amount<Dimensionless> ZERO
 Holds a dimensionless measure of zero (exact).
ONE
public static final Amount<Dimensionless> ONE
 Holds a dimensionless measure of one (exact).
XML
protected static final javolution.xml.XMLFormat<Amount> 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: <Amount value="12" unit="µA"/>
represents an electric current measurement.
Method Detail
valueOf
public static <Q extends Quantity> Amount<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> Amount<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> Amount<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> Amount<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 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 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 AmountException
 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:
AmountException
 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 the
estimated
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> Amount<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 Amount<Q> opposite()
 Returns the opposite of this measure.
 Returns:
this
.
plus
public Amount<Q> plus(Amount that)
throws ConversionException
 Returns the sum of this measure with the one specified.
 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 Amount<Q> minus(Amount 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 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 Quantity> times(Amount that)
 Returns the product of this measure with the one specified.
 Parameters:
that
 the measure multiplier.
 Returns:
this · that
.
inverse
public Amount<? extends Quantity> inverse()
 Returns the multiplicative inverse of this measure.
If this measure is possibly zero, then the result is unbounded
(]infinity, +infinity[).
 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 Quantity> divide(Amount that)
 Returns this measure divided by the one specified.
 Parameters:
that
 the measure divisor.
 Returns:
this / that
.
abs
public Amount<Q> abs()
 Returns the absolute value of this measure.
 Returns:
this
.
sqrt
public Amount<? extends Quantity> sqrt()
 Returns the square root of this measure.
 Returns:
sqrt(this)
root
public Amount<? 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 Amount<? extends Quantity> pow(int exp)
 Returns this measure raised at the specified exponent.
 Parameters:
exp
 the exponent.
 Returns:
this^{exp}
compareTo
public int compareTo(Measurable<Q> that)
 Compares this measure with the specified measurable object.
 Specified by:
compareTo
in interface java.lang.Comparable<Measurable<Q extends Quantity>>
 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:
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(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(Unit<Q> unit)
 Description copied from interface:
Measurable
 Returns the value of this measurable stated in the specified unit as
a
double
. If the measurable has too great a magnitude to
be represented as a double
, it will be converted to
Double.NEGATIVE_INFINITY
or
Double.POSITIVE_INFINITY
as appropriate.
 Specified by:
doubleValue
in interface Measurable<Q extends Quantity>
 Parameters:
unit
 the unit in which this measurable value is stated.
 Returns:
 the numeric value after conversion to type
double
.
longValue
public final long longValue(Unit<Q> unit)
 Description copied from interface:
Measurable
 Returns the estimated integral value of this measurable stated in
the specified unit as a
long
.
Note: This method differs from the Number.longValue()
in the sense that the closest integer value is returned
and an ArithmeticException is raised instead
of a bit truncation in case of overflow (safety critical).
 Specified by:
longValue
in interface Measurable<Q extends Quantity>
 Parameters:
unit
 the unit in which the measurable value is stated.
 Returns:
 the numeric value after conversion to type
long
.
copy
public Amount<Q> copy()
Overview
Package
Class
Tree
Deprecated
Index
Help
PREV CLASS
NEXT CLASS
FRAMES
NO FRAMES
SUMMARY: NESTED  FIELD  CONSTR  METHOD
DETAIL: FIELD  CONSTR  METHOD