Package org.jscience.physics.amount

Class Amount<Q extends Quantity>

java.lang.Object
org.jscience.physics.amount.Amount<Q>
All Implemented Interfaces:
Serializable, 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 Object implements Measurable<Q>, Field<Amount<?>>, 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.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Amount<Dimensionless>
    ONE
    Holds a dimensionless measure of one (exact).
    protected static final javolution.xml.XMLFormat<Amount>
    XML
    Holds the default XML representation for measures.
    static final Amount<Dimensionless>
    ZERO
    Holds a dimensionless measure of zero (exact).

  • Method Summary

    Modifier and Type
    Method
    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()
     
    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).
    Amount<? extends Quantity>
    divide(Amount that)
    Returns this measure divided by the one specified.
    double
    doubleValue(Unit<Q> unit)
    Returns the value of this measurable stated in the specified unit as a double.
    boolean
    equals(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).
    final 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<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).
    Amount<? extends Quantity>
    times(Amount that)
    Returns the product of this measure with the one specified.
    <R extends Quantity>
    Amount<R>
    to(Unit<R> unit)
    Returns the measure equivalent to this measure but stated in the specified unit.
    final 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 <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.
    static Amount<?>
    valueOf(CharSequence csq)
    Returns the measure represented by the specified character sequence.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • 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 Details

    • 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:
      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:
      IllegalArgumentException - if minimum > maximum

    • valueOf

      public static Amount<?> valueOf(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<Q extends Quantity>
      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<Q extends Quantity>
      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<Q extends Quantity>
      Specified by:
      times in interface Ring<Q extends Quantity>
      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<Q extends Quantity>
      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:
      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:
      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:
      thisexp

    • compareTo

      public int compareTo(Measurable<Q> that)
      Compares this measure with the specified measurable object.
      Specified by:
      compareTo in interface Comparable<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(Object that)
      Compares this measure against the specified object for strict equality (same value interval and same units).
      Overrides:
      equals in class 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 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 String toString()
      Returns the text representation of this amount as a java.lang.String.
      Overrides:
      toString in class 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()
      Specified by:
      copy in interface javolution.lang.ValueType