org.jscience.physics.quantities
Class Quantity

java.lang.Object
  javolution.realtime.RealtimeObject
      org.jscience.mathematics.numbers.Number<Quantity>
          org.jscience.physics.quantities.Quantity

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Quantity>, Realtime, Operable<Quantity>, Numeric<Quantity>

Direct Known Subclasses:

Acceleration, AmountOfSubstance, AngularAcceleration, AngularVelocity, Area, CatalyticActivity, DataRate, Dimensionless, Duration, ElectricCapacitance, ElectricCharge, ElectricConductance, ElectricCurrent, ElectricInductance, ElectricPotential, ElectricResistance, Energy, Force, Frequency, Illuminance, Length, LuminousFlux, LuminousIntensity, MagneticFlux, MagneticFluxDensity, Mass, Money, Power, Pressure, RadiationDoseAbsorbed, RadiationDoseEffective, RadioactiveActivity, Temperature, Torque, Velocity, Volume, VolumetricDensity

public class Quantity
extends Number<Quantity>

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

Errors (including numeric errors) are calculated using numeric intervals. It is possible to resolve systems of linear equations involving physical quantities (e.g. using 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.

The decimal representations of quantities instances are indicative of their precision as only digits guaranteed to be exact are written out. For example, the string "2.000 km/s" represents a Velocity of (2.0 ± 0.001) km/s.

Finally, operations between quantities may or may not be authorized based upon the current PhysicalModel (e.g. adding a length to a duration is not allowed by the StandardModel, but is authorized with the RelativisticModel).

Version:

2.0, June 6, 2005

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Nested Class Summary

static class

Quantity.Factory<Q extends Quantity> This inner-class represents the factory producing quantity instances.

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

Realtime.ObjectSpace

Constructor Summary

protected

Quantity() Default constructor.

Method Summary

boolean	approxEquals(Quantity that) Indicates if this quantity is approximately equals to the specified quantity (regardless of the quantity unit).
int	compareTo(Quantity that) Compares this quantity with the specified quantity for order.
Quantity	divide(double divisor) Returns this quantity divided by the specified divisor.
double	doubleValue() Returns the estimated value stated in base units represented as a double.
boolean	equals(java.lang.Object obj) Indicates if this quantity is strictly equals to the object specified (same amount and same system unit).
double	getAbsoluteError() Returns the value by which the estimated value may differ from the true value (all stated in base units).
double	getAmount() Returns this quantity estimated amount stated in this quantity unit.
double	getMaximum() Returns the maximum value for this quantity stated in base units.
double	getMinimum() Returns the minimum value for this quantity stated in base units.
double	getRelativeError() Returns the percentage by which the estimated amount may differ from the true amount.
Unit	getUnit() Returns the unit identifying this quantity type; it is also the unit in which this quantity is displayed by default.
int	hashCode() Returns a well distributed hash code value for this quantity.
boolean	isLargerThan(Quantity that) Compares this quantity amount with that quantity amount ignoring the sign.
long	longValue() Returns the estimated value stated in base units represented as a long.
Quantity	minus(Quantity that) Returns the difference of this quantity with the one specified.
Quantity	norm() Returns the magnitude (positive) of this quantity.
Quantity	opposite() Returns the opposite of this quantity.
Quantity	plus(Quantity that) Returns the sum of this quantity with the one specified.
static <Q extends Quantity> Q	rangeOf(double minimum, double maximum, Unit<Q> unit) Returns the quantity whose amount is in the specified range.
Quantity	reciprocal() Returns the reciprocal of this quantity.
Quantity	root(int n) Returns the given root of this quantity.
Quantity	sqrt() Returns the square root of this quantity.
Quantity	times(double factor) Returns this quantity multiplied by the specified factor.
Quantity	times(Quantity that) Returns the product of this quantity with the one specified.
<Q extends Quantity> Q	to(Unit<Q> unit) Returns the quantity equivalent to this quantity but stated using the specified unit.
Text	toText() Returns the textual representation of this quantity.
static <Q extends Quantity> Q	valueOf(java.lang.CharSequence csq) Returns the quantity corresponding to the specified character sequence.
static <Q extends Quantity> Q	valueOf(double amount, double error, Unit<Q> unit) Returns the quantity of specified amount and measurement error.
static <Q extends Quantity> Q	valueOf(double amount, Unit<Q> unit) Returns the quantity for the specified amount.

Methods inherited from class org.jscience.mathematics.numbers.Number

abs, byteValue, divide, floatValue, intValue, inverse, isGreaterThan, isLessThan, pow, shortValue

Methods inherited from class javolution.realtime.RealtimeObject

export, move, moveHeap, preserve, recycle, toString, unpreserve

Methods inherited from class java.lang.Object

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

Methods inherited from interface javolution.realtime.Realtime

move

Constructor Detail

Quantity

protected Quantity()

Default constructor.

Method Detail

valueOf

public static <Q extends Quantity> Q valueOf(java.lang.CharSequence csq)

Returns the quantity corresponding to the specified character sequence. The unit of the specified quantity determinates the class of the quantity being returned. For example:

Quantity.valueOf("1.2 GeV")

returns an Energy instance.

Parameters:

csq - the character sequence.

Returns:

QuantityFormat.current().parse(csq)

Throws:

java.lang.IllegalArgumentException - if the specified character sequence cannot be parsed.

See Also:

QuantityFormat

valueOf

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

Returns the quantity for the specified amount. The specified unit determinates the class of the quantity being returned. For example:

Quantity.valueOf(30, NonSI.FOOT)

returns a Length instance.

Parameters:

amount - the estimated amount (± 1/2 LSB).

unit - the amount's unit.

Returns:

the corresponding quantity.

valueOf

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

Returns the quantity of specified amount and measurement error. The specified unit determinates the class of the quantity being returned. For example:

Quantity.valueOf(20, 0.1, SI.KILO(SI.HERTZ))

returns a Frequency instance.

Parameters:

amount - the estimated amount (± error).

error - the measurement error (absolute).

unit - the amount's unit.

Returns:

the corresponding quantity.

rangeOf

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

Returns the quantity whose amount is in the specified range.

Parameters:

minimum - the lower bound for the quantity amount.

maximum - the upper bound of the quantity amount.

unit - the bounds unit.

Returns:

the corresponding quantity.

getAmount

public double getAmount()

Returns this quantity estimated amount stated in this quantity unit.

Returns:

this quantity estimated amount.

getUnit

public Unit getUnit()

Returns the unit identifying this quantity type; it is also the unit in which this quantity is displayed by default.

Returns:

the unit for this quantity.

getMinimum

public final double getMinimum()

Returns the minimum value for this quantity stated in base units.

Returns:

the minimum value.

getMaximum

public final double getMaximum()

Returns the maximum value for this quantity stated in base units.

Returns:

the maximum amount value.

getAbsoluteError

public final 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 final double getRelativeError()

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

Returns:

the relative error.

to

public final <Q extends Quantity> Q to(Unit<Q> unit)

Returns the quantity equivalent to this quantity but stated using the specified unit. This method may return a quantity of different type than this quantity (the unit determinates the quantity sub-class).

Parameters:

unit - the unit of the quantity being returned.

Returns:

a quantity equivalent to this unit but stated using a different unit.

Throws:

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

opposite

public final Quantity opposite()

Returns the opposite of this quantity.

Returns:

-this.

plus

public final Quantity plus(Quantity that)
                    throws ConversionException

Returns the sum of this quantity with the one specified.

Parameters:

that - the quantity to be added.

Returns:

this + that.

Throws:

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

minus

public final Quantity minus(Quantity that)
                     throws ConversionException

Returns the difference of this quantity with the one specified.

Overrides:

minus in class Number<Quantity>

Parameters:

that - the quantity to be subtracted.

Returns:

this - that.

Throws:

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

times

public final Quantity times(double factor)

Returns this quantity multiplied by the specified factor.

Parameters:

factor - the multiplier.

Returns:

this * factor.

times

public final Quantity times(Quantity that)

Returns the product of this quantity with the one specified.

Parameters:

that - the quantity multiplier.

Returns:

this * that.

reciprocal

public final Quantity reciprocal()

Returns the reciprocal of this quantity. If this quantity is possbily zero, then the resulting quantity is unbounded.

Returns:

1 / this.

divide

public final Quantity divide(double divisor)

Returns this quantity divided by the specified divisor.

Parameters:

divisor - the divisor.

Returns:

this / divisor.

sqrt

public final Quantity sqrt()

Returns the square root of this quantity.

Returns:

sqrt(this)

root

public final Quantity root(int n)

Returns the given root of this quantity.

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.

norm

public final Quantity norm()

Returns the magnitude (positive) of this quantity.

Returns:

|this|.

isLargerThan

public final boolean isLargerThan(Quantity that)

Compares this quantity amount with that quantity amount ignoring the sign.

Parameters:

that - the numeric to be compared with.

Returns:

|this| > |that|

equals

public boolean equals(java.lang.Object obj)

Indicates if this quantity is strictly equals to the object specified (same amount and same system unit).

Note: Unlike approxEquals(org.jscience.physics.quantities.Quantity), this method does not take into account possible errors (e.g. numeric errors).

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare with.

Returns:

true if this quantity and the specified object represent the exact same quantity; false otherwise.

hashCode

public int hashCode()

Returns a well distributed hash code value for this quantity.

Overrides:

hashCode in class java.lang.Object

Returns:

this quantity hash code value.

See Also:

equals(java.lang.Object)

approxEquals

public boolean approxEquals(Quantity that)

Indicates if this quantity is approximately equals to the specified quantity (regardless of the quantity unit). This method takes into account possible errors (e.g. numeric errors) to make this determination.

Parameters:

that - the quantity to compare with.

Returns:

this ≊ that.

compareTo

public int compareTo(Quantity that)

Compares this quantity with the specified quantity for order. Returns a negative integer, zero, or a positive integer as this quantity is less than, equal to, or greater than the specified quantity. This method does not require both units to be stated using the same units.

Specified by:

compareTo in interface java.lang.Comparable<Quantity>

Specified by:

compareTo in class Number<Quantity>

Parameters:

that - the quantity to be compared.

Returns:

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

Throws:

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

See Also:

Unit.isCompatible(org.jscience.physics.units.Unit)

toText

public Text toText()

Returns the textual representation of this quantity. By default the quantity amount stated in the quantity unit.

Specified by:

toText in interface Realtime

Overrides:

toText in class RealtimeObject

Returns:

the textual representation of this quantity.

See Also:

QuantityFormat

longValue

public final long longValue()

Returns the estimated value stated in base units represented as a long.

Specified by:

longValue in class Number<Quantity>

Returns:

the numeric value after conversion to type long.

doubleValue

public final double doubleValue()

Returns the estimated value stated in base units represented as a double.

Specified by:

doubleValue in class Number<Quantity>

Returns:

the numeric value after conversion to type double.