com.dautelle.physics
Class Quantity

java.lang.Object
  java.lang.Number
      com.dautelle.math.numbers.RealtimeNumber
          com.dautelle.physics.Quantity

All Implemented Interfaces:

java.lang.Comparable, Operable, Realtime, Representable, java.io.Serializable

Direct Known Subclasses:

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

public class Quantity

extends RealtimeNumber

implements java.lang.Comparable

This class represents a measurable amount. The nature of the amount is deduced from the quantity's 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 this latter case the error associated with some (or all) components of the solution is potentially 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:

6.0, June 3, 2004

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Nested Class Summary

static class	Quantity.Factory This inner-class represents the ObjectFactory producing Quantity instances.
static class	Quantity.Value This inner class represents a mutable image of an imutable Quantity.

Constructor Summary

protected

Quantity() Default constructor.

Method Summary

Quantity	abs() Returns the absolute value of this quantity.
Quantity	add(Quantity that) Returns the sum of this quantity with the one specified.
java.lang.StringBuffer	appendTo(java.lang.StringBuffer sb, Unit outputUnit) Appends the text representation of this quantity stated in the specified unit to the StringBuffer argument.
static boolean	approxEquals(Matrix left, Matrix right) Indicates if the Quantity elements of the specified matrices are approximately equals.
boolean	approxEquals(Quantity that) Indicates if this quantity is approximately equals to the specified quantity.
int	compareTo(java.lang.Object obj) Compares this object with the specified object for order.
Quantity	divide(double divisor) Returns this quantity divided by the specified divisor.
Quantity	divide(Quantity that) Returns the division of this quantity by the one specified.
double	doubleValue() Returns the estimated value stated in this quantity's system unit as a double.
double	doubleValue(Unit unit) Returns the estimated value of this quantity stated in the specified unit as a double.
boolean	equals(java.lang.Object obj) Indicates if this quantity is strictly equals to the object specified.
float	floatValue() Returns the estimated value stated in this quantity's system unit as a float.
float	floatValue(Unit unit) Returns the estimated value of this quantity stated in the specified unit as a float.
double	getAbsoluteError() Returns the value by which the estimated amount may differ from the true amount.
double	getMaximum() Returns the maximum amount for this quantity.
double	getMinimum() Returns the minimum amount for this quantity.
Unit	getOutputUnit() Returns the unit that this quantity is showed as.
double	getRelativeError() Returns the percentage by which the estimated amount may differ from the true amount.
Unit	getSystemUnit() Returns the system unit for this quantity.
int	hashCode() Returns a hash code value for this quantity.
int	intValue() Returns the estimated value stated in this quantity's system unit as a int.
int	intValue(Unit unit) Returns the estimated value of this quantity stated in the specified unit as a int.
Quantity	inverse() Returns the inverse of this quantity.
boolean	isPossiblyZero() Indicates if this quantity is possibly amounting to nothing.
long	longValue() Returns the estimated value stated in this quantity's system unit as a long.
long	longValue(Unit unit) Returns the estimated value of this quantity stated in the specified unit as a long.
Quantity	multiply(double factor) Returns this quantity multiplied by the specified factor.
Quantity	multiply(Quantity that) Returns the product of this quantity with the one specified.
Quantity	negate() Returns the negation of this quantity.
Operable	opposite() Returns the additive inverse of this object.
Operable	plus(Operable that) Returns the sum of this object with the one specified.
Quantity	pow(double exp) Returns the quantity equals to this quantity raised to an exponent.
double	random() Returns a random but possible value for this quantity.
Operable	reciprocal() Returns the multiplicative inverse of this object.
Quantity	root(int n) Returns the given root of this quantity.
Quantity	subtract(Quantity that) Returns the difference of this quantity with the one specified.
Operable	times(Operable that) Returns the product of this object with the one specified.
java.lang.String	toString() Returns the text representation of this quantity using the local quantity format.
java.lang.String	toString(Unit outputUnit) Returns the text representation of this quantity stated in the specified unit.
void	toXml(XmlElement xml) Sets the attributes and content of the XML element corresponding to this object.
static Quantity	valueOf(java.lang.CharSequence chars) Returns the Quantity from the specified character sequence.
static Quantity	valueOf(double amount, double error, Unit unit) Returns the Quantity of specified amount and measurement error.
static Quantity	valueOf(double amount, Unit unit) Returns the Quantity of specified amount.
static Quantity	valueOf(XmlElement xml) XML factory method.

Methods inherited from class com.dautelle.math.numbers.RealtimeNumber

clone, export, isLocalObject, isPoolObject, pow, recycle, toHeap

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

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

Constructor Detail

Quantity

protected Quantity()

Default constructor.

Method Detail

valueOf

public static Quantity valueOf(java.lang.CharSequence chars)

Returns the Quantity from the specified character sequence. The system 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:

chars - the character sequence.

Returns:

QuantityFormat.getInstance().parse(chars)

Throws:

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

valueOf

public static Quantity valueOf(double amount,
                               Unit unit)

Returns the Quantity of specified amount. The system unit of 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 Quantity valueOf(double amount,
                               double error,
                               Unit unit)

Returns the Quantity of specified amount and measurement error. The system unit of 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.

valueOf

public static Quantity valueOf(XmlElement xml)

XML factory method. The unit xml attribute determinates the class of the quantity being returned. For example:

 <Quantity amount="12.3" error="1.0E-4" unit="µA"/>

returns an ElectricCurrent instance.

Note: In the future, the tag name (class) will identify the quantity to return (to support model-dependent conversion). For example:

     <Mass amount="12" error="0.01" unit="GeV"/>
     

which is valid input in a relativistic context, should produce a Mass instance (and not an Energy) when deserialized. It is assumed that the same relativistic model is selected during deserialization (to avoid conversion errors).

Parameters:

xml - the XML element describing the Quantity to return.

Returns:

the corresponding Quantity.

getSystemUnit

public final Unit getSystemUnit()

Returns the system unit for this quantity. The system unit identifies the nature of the quantity and can be mapped to quantity's sub-classes for automatic instantiation of the proper quantity class.

Returns:

this quantity's system unit.

getOutputUnit

public Unit getOutputUnit()

Returns the unit that this quantity is showed as. The default output unit is specified by the current model. This default may be overriden for predefined quantities using the context-local showAs(Unit) static method.

Returns:

getModel().unitFor(this)

See Also:

toString(), toXml(com.dautelle.xml.XmlElement)

getAbsoluteError

public final double getAbsoluteError()

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

Returns:

the absolute error stated in this quantity's system unit.

getRelativeError

public final double getRelativeError()

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

Returns:

the relative error.

getMinimum

public final double getMinimum()

Returns the minimum amount for this quantity.

Returns:

the minimun amount stated in this quantity's system unit.

getMaximum

public final double getMaximum()

Returns the maximum amount for this quantity.

Returns:

the maximun amount stated in this quantity's system unit.

isPossiblyZero

public final boolean isPossiblyZero()

Indicates if this quantity is possibly amounting to nothing.

Returns:

true if this quantity can be zero; false otherwise.

negate

public final Quantity negate()

Returns the negation of this quantity.

Returns:

-this.

add

public final Quantity add(Quantity that)
                   throws ConversionException

Returns the sum of this quantity with the one specified. The returned quantity is of the same class that this quantity.

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.

subtract

public final Quantity subtract(Quantity that)
                        throws ConversionException

Returns the difference of this quantity with the one specified. The returned quantity is of the same class that this 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.

multiply

public final Quantity multiply(double factor)

Returns this quantity multiplied by the specified factor.

Parameters:

factor - the multiplier.

Returns:

this * factor.

multiply

public final Quantity multiply(Quantity that)

Returns the product of this quantity with the one specified.

Parameters:

that - the quantity multiplier.

Returns:

this * that.

inverse

public final Quantity inverse()

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

Returns:

1 / this.

See Also:

isPossiblyZero()

divide

public final Quantity divide(double divisor)

Returns this quantity divided by the specified divisor.

Parameters:

divisor - the divisor.

Returns:

this / divisor.

divide

public final Quantity divide(Quantity that)

Returns the division of this quantity by the one specified.

Parameters:

that - the quantity divisor.

Returns:

this / that.

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.

pow

public final Quantity pow(double exp)

Returns the quantity equals to this quantity raised to an exponent.

Parameters:

exp - the exponent.

Returns:

thisexp

Throws:

java.lang.ArithmeticException - if the exponent is a non-integer value and this quantity is not dimensionless.

abs

public final Quantity abs()

Returns the absolute value of this quantity.

Returns:

abs(this).

random

public final double random()

Returns a random but possible value for this quantity.

Returns:

a double value r such as this.getMinimum{} < r > this.getMaximum().

equals

public final boolean equals(java.lang.Object obj)

Indicates if this quantity is strictly equals to the object specified.

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

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 final int hashCode()

Returns a hash code value for this quantity.

Returns:

this quantity hash code value.

See Also:

equals(java.lang.Object)

approxEquals

public final boolean approxEquals(Quantity that)

Indicates if this quantity is approximately equals to the specified quantity. 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.

approxEquals

public static final boolean approxEquals(Matrix left,
                                         Matrix right)

Indicates if the Quantity elements of the specified matrices are approximately equals.

Parameters:

left - the first matrix to compare.

right - the second matrix to compare.

Returns:

true if both matrices have same dimension and their quantity elements are approximately equals; false otherwise.

Throws:

java.lang.ClassCastException - if the specified matrices are not composed of Quantity elements.

See Also:

approxEquals(com.dautelle.physics.Quantity)

compareTo

public final int compareTo(java.lang.Object obj)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Note: This comparator imposes orderings that are inconsistent with equals. In particular, this.compareTo(that) == 0 does not imply this.equals(that) (but the reverse is true).

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - the object to be compared.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

java.lang.ClassCastException - if the specified object's type prevents it from being compared to this object.

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

See Also:

Unit.isCompatible(javax.units.Unit)

toString

public final java.lang.String toString()

Returns the text representation of this quantity using the local quantity format.

Returns:

toString(getOutputUnit())

See Also:

toString(Unit)

toString

public final java.lang.String toString(Unit outputUnit)

Returns the text representation of this quantity stated in the specified unit.

Parameters:

outputUnit - the unit this quantity is showed as.

Returns:

appendTo(new StringBuffer(), outputUnit).toString()

See Also:

appendTo(StringBuffer, Unit)

appendTo

public java.lang.StringBuffer appendTo(java.lang.StringBuffer sb,
                                       Unit outputUnit)

Appends the text representation of this quantity stated in the specified unit to the StringBuffer argument. Only the digits guaranteed to be exact are written out. In other words, the error is always on the last digit and less than the last digit weight. For example, if "1.33" is appended then the quantity is guaranteed to be in the range ]1.32, 1.34[.

Note: Sub-classes with custom formatting should override this method.

Parameters:

sb - the StrinBuffer to append.

outputUnit - the unit this quantity is showed as.

Returns:

the specified StringBuffer object.

Throws:

ConversionException - if the current model does not allow this quantity to be stated in the specified unit.

intValue

public final int intValue()

Returns the estimated value stated in this quantity's system unit as a int. This may involve rounding or truncation.

Returns:

the numeric value represented by this object after conversion to type int.

longValue

public final long longValue()

Returns the estimated value stated in this quantity's system unit as a long. This may involve rounding or truncation.

Returns:

the numeric value represented by this object after conversion to type long.

floatValue

public final float floatValue()

Returns the estimated value stated in this quantity's system unit as a float. This may involve rounding.

Returns:

the numeric value represented by this object after conversion to type float.

doubleValue

public final double doubleValue()

Returns the estimated value stated in this quantity's system unit as a double.

Returns:

the numeric value represented by this object after conversion to type double.

intValue

public final int intValue(Unit unit)

Returns the estimated value of this quantity stated in the specified unit as a int. This may involve rounding or truncation.

Parameters:

unit - the unit for the returned value.

Returns:

the numeric value represented by this object after conversion to type int.

Throws:

ConversionException - if the current model does not allow this quantity to be stated in the specified unit.

longValue

public final long longValue(Unit unit)

Returns the estimated value of this quantity stated in the specified unit as a long. This may involve rounding or truncation.

Parameters:

unit - the unit for the returned value.

Returns:

the numeric value represented by this object after conversion to type long.

Throws:

ConversionException - if the current model does not allow this quantity to be stated in the specified unit.

floatValue

public final float floatValue(Unit unit)

Returns the estimated value of this quantity stated in the specified unit as a float. This may involve rounding.

Parameters:

unit - the unit for the returned value.

Returns:

the numeric value represented by this object after conversion to type float.

Throws:

ConversionException - if the current model does not allow this quantity to be stated in the specified unit.

doubleValue

public final double doubleValue(Unit unit)

Returns the estimated value of this quantity stated in the specified unit as a double.

Parameters:

unit - the unit for the returned value.

Returns:

the numeric value represented by this object after conversion to type double.

Throws:

ConversionException - if the current model does not allow this quantity to be stated in the specified unit.

plus

public final Operable plus(Operable that)

Description copied from interface: Operable

Returns the sum of this object with the one specified.

Specified by:

plus in interface Operable

Parameters:

that - the object to be added.

Returns:

this + that.

opposite

public final Operable opposite()

Description copied from interface: Operable

Returns the additive inverse of this object. It is the object such as this.plus(this.opposite()) == ZERO, with ZERO being the additive identity.

Specified by:

opposite in interface Operable

Returns:

-this.

times

public final Operable times(Operable that)

Description copied from interface: Operable

Returns the product of this object with the one specified.

Specified by:

times in interface Operable

Parameters:

that - the object multiplier.

Returns:

this * that.

reciprocal

public final Operable reciprocal()

Description copied from interface: Operable

Returns the multiplicative inverse of this object. It it the object such as this.times(this.reciprocal()) == ONE , with ONE being the multiplicative identity.

Specified by:

reciprocal in interface Operable

Returns:

ONE / this.

toXml

public void toXml(XmlElement xml)

Description copied from interface: Representable

Sets the attributes and content of the XML element corresponding to this object.

Specified by:

toXml in interface Representable

Parameters:

xml - the XML element to set according to this object's desired XML representation.