Amount

java.lang.Object
- org.jscience.physics.amount.Amount<Q>

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Measurable<Q>>, Measurable<Q>, javolution.lang.Immutable, javolution.lang.ValueType, Field<Amount<?>>, GroupAdditive<Amount<?>>, GroupMultiplicative<Amount<?>>, Ring<Amount<?>>, Structure<Amount<?>>
```
public final class Amount<Q extends Quantity>
extends java.lang.Object
implements Measurable<Q>, 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 m = Amount.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[/code]

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, non-exact 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: Jean-Marie Dautelle See Also: Wikipedia: Measuring, Serialized Form










Field Summary

Fields 

Modifier and Type
Field and Description


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



static Amount<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(Measurable<Q> that)
Compares this measure with the specified measurable object.



Amount<Q>
copy()
Returns a deep copy of this object allocated in the memory area (RTSJ) 
 and/or context (Javolution)
 of the calling thread (the one making the 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
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).









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

Specified by:
opposite in interface GroupAdditive<Amount<?>>
Returns:
-this.








plus
public Amount<Q> plus(Amount that)
               throws ConversionException
Returns the sum of this measure with the one specified.

Specified by:
plus in interface GroupAdditive<Amount<?>>
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.

Specified by:
times in interface GroupMultiplicative<Amount<?>>
Specified by:
times in interface Ring<Amount<?>>
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[).

Specified by:
inverse in interface 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 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()
Description copied from interface: javolution.lang.ValueType
Returns a deep copy of this object allocated in the memory area (RTSJ) 
 and/or context (Javolution)
 of the calling thread (the one making the copy).

Specified by:
copy in interface javolution.lang.ValueType
Returns:
an object identical to this object but allocated by the calling
         thread (e.g. on the "stack" of the calling thread).

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

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(Measurable<Q> that)` Compares this measure with the specified measurable object.
`Amount<Q>`	`copy()` Returns a deep copy of this object allocated in the memory area (RTSJ) and/or `context` (Javolution) of the calling thread (the one making the 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 the`estimated 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.

Class Amount<Q extends Quantity>

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ZERO

ONE

Method Detail

valueOf

valueOf

valueOf

rangeOf

valueOf

isExact

getUnit

getExactValue

getEstimatedValue

getMinimumValue

getMaximumValue

getAbsoluteError

getRelativeError

to

opposite

plus

minus

times

times

times

inverse

divide

divide

divide

abs

sqrt

root

pow

compareTo

equals

hashCode

approximates

isLessThan

isGreaterThan

isLargerThan

toText

toString

doubleValue

longValue

copy