com.rubecula.jquantity
Class JQuantity

java.lang.Object
  com.rubecula.util.Item
      com.rubecula.jquantity.BaseNumber
          com.rubecula.jquantity.JQuantity

All Implemented Interfaces:

Arithmetical, Auditable, java.lang.Cloneable, java.lang.Comparable, Divisible, Fuzzy, Identifiable, Measurable, Millable, Presentable, java.io.Serializable

public class JQuantity

extends BaseNumber

implements Measurable, java.lang.Cloneable, Divisible

This class represents a quantity, that is to say a value and its units. A quantity is immutable.

Methods of BaseNumber are generally delegated via the private field _Number. All methods of Measurable are delegated via the private field _Units. Although this class does not implement Divisible, it emulates it (where the return types are different and where the divide method is missing, since JQuantity is not mutable).

Copyright: Copyright (c) 2002, 2003

Company: Rubecula Software

Version:

$Revision: 1.29 $

Author:

Robin Hillyard

See Also:

Serialized Form

Field Summary

private BaseNumber	_Number The value of this JQuantity.
private Measurable	_Units The units of this JQuantity.
static JQuantity	$1
static PresentationFactoryInterface	$PRES_FACTORY

Fields inherited from class com.rubecula.jquantity.BaseNumber

Fields inherited from class com.rubecula.util.Item

JQUANTITY_TEST

Fields inherited from interface com.rubecula.jquantity.Fuzzy

$DistGaussian, $DistInvalid, $DistNone, $DistUniform, $Names

Constructor Summary

JQuantity(BaseNumber number)
Constructor for a new dimensionless JQuantity.

JQuantity(BaseNumber number, Measurable units)
Primary constructor for a new JQuantity.

JQuantity(java.lang.String presentation)
Constructs a dimensionless JQuantity from a String representing a number.

JQuantity(java.lang.String presentation, Units units)
Constructs a JQuantity from a String representing a number and a Units.

Method Summary

java.lang.String	audit(java.lang.String label) Method to implement com.rubecula.util.Auditable.
java.lang.Object	clone() Creates and returns a copy of this JQuantity.
int	compareTo(JQuantity q) Method to implement java.lang.Comparable.
JQuantity	convertUnits(Measurable newUnits)
protected JQuantity	convertUnits(SystemFlag system)
(package private) Measurable	createUnits(UnitsName name, SystemFlag system) Create a new unit from this quantity and call it by name.
double	doubleValue() Method to implement java.lang.Number.
Divisible	factored(double factor) Method to yield the quotient of this divided by factor, and return it as the result.
BaseUnit	flatten() Method to reduce a Units tree to a single flattened version.
float	floatValue() Method to implement java.lang.Number.
Dimensions	getDimensions() Method to return the dimensions of this Measurable.
java.lang.String	getIdentifier() Method to get the specific identifier for an object.
protected BaseNumber	getNumber() Accessor method to get the number represented by this JQuantity.
Rational	getOffset() Method to return the offset of this Measurable.
Rational	getScale() Method to return the scale of this Measurable.
SystemFlag	getSystem()
protected Measurable	getUnit() Accessor method to get the unit represented by this JQuantity.
int	intValue() Returns the value of the specified number as an int.
Divisible	inverse() Method to yield the reciprocal of this and return it as the result.
boolean	isInfinite() Method to implement Arithmetical.
boolean	isInteger() Method to implement Arithmetical.
boolean	isNumber() Method to determine if this is dimensionless (i.e. unitless).
boolean	isParallel(Measurable that) Method to determine if this Measurable is parallel to that Measurable.
boolean	isUnity() Method to implement Arithmetical.
long	longValue() Returns the value of the specified number as a long.
static void	main(java.lang.String[] args) Main method for testing purposes.
Presentable	makePresentableInstance(Presentation presentation) Instance method to convert a Presentation into a Presentable.
protected BaseNumber	minus() Method to implement BaseNumber.
void	normalize() MUTATING instance method to normalize this object.
protected void	normalize(Measurable units) MUTATING instance method to normalize this object by setting the units as specified and adjusting the value accordingly.
protected BaseNumber	pow(int power) Method to raise this to the power power return the result.
Presentation	present(AttrMap attributes) Convert this Presentable object into a Presentation, according to the set of attributes provided.
BaseNumber	product(BaseNumber multiplicand) Method to implement form the product of this JQuantity and a BaseNumber.
(package private) JQuantity	productJQuantity(JQuantity that, boolean standardize) Method to multiply two Quantities together.
Divisible	quotient(BaseNumber divisor) Method to divide this by multiplicand and return the quotient as the result.
(package private) JQuantity	quotientJQuantity(JQuantity that) Method to divide two Quantities.
protected BaseNumber	scaled(long scale) Method to multiply this quantity by an integral scale factor.
int	signum() Method to implement Arithmetical.
protected JQuantity	standardizeUnits(SystemFlag system)
protected BaseNumber	sum(BaseNumber addend) Method to determine the sum of a quantity with a base number.
private JQuantity	sum(JQuantity addend) Method to add two quantities together.
static BaseNumber	valueOf(Presentable presentable)
static BaseNumber	valueOf(java.lang.String presentation) Constructs a dimensionless JQuantity from a String representing a number.

Methods inherited from class com.rubecula.jquantity.BaseNumber

abs, bestModel, BestModel, byteValue, characteristic, Characteristic, difference, getBound, getBoundAbs, getModel, impartFuzziness, isEqual, isExact, isUncertain, isZero, shortValue, valueOf, valueOfLog10

Methods inherited from class com.rubecula.util.Item

audit, audit, compareTo, Debug, getClassNameShort, getType, IsDebug, present, SetDebug, test, test, toString, Wrap

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.rubecula.util.Auditable

audit, audit

Field Detail

$1

public static final JQuantity $1

$PRES_FACTORY

public static final PresentationFactoryInterface $PRES_FACTORY

_Number

private final BaseNumber _Number

The value of this JQuantity.

_Units

private final Measurable _Units

The units of this JQuantity.

Constructor Detail

JQuantity

public JQuantity(BaseNumber number,
                 Measurable units)

Primary constructor for a new JQuantity.

Parameters:

number - the value of the new JQuantity which can be an instance of any concrete subclass of MutableNumber.

units - the units of the new JQuantity.

JQuantity

public JQuantity(BaseNumber number)

Constructor for a new dimensionless JQuantity.

Parameters:

number - the value of the new JQuantity which can be an instance of any concrete subclass of MutableNumber.

JQuantity

public JQuantity(java.lang.String presentation,
                 Units units)
          throws PresentationException

Constructs a JQuantity from a String representing a number and a Units.
Note that it is possible for this method to throw a ClassCastException which will occur if NumberPresentation.parse() returns on object which cannot be cast as a MutableNumber. This is unlikely, however.

Parameters:

presentation - representation of number in the form understood by

units - the units to be used for this quantity.

Throws:

PresentationException - if unable to parse appropriately.

See Also:

NumberPresentation.NumberPresentation(String).

JQuantity

public JQuantity(java.lang.String presentation)
          throws PresentationException

Constructs a dimensionless JQuantity from a String representing a number.
Note that it is possible for this method to throw a ClassCastException which will occur if NumberPresentation.parse() returns on object which cannot be cast as a MutableNumber. This is unlikely, however.

Parameters:

presentation - representation of number in the form understood by

Throws:

PresentationException - if unable to parse appropriately.

See Also:

JQuantity(String, Units).

Method Detail

main

public static void main(java.lang.String[] args)

Main method for testing purposes.

Parameters:

args - command line arguments.

valueOf

public static final BaseNumber valueOf(java.lang.String presentation)
                                throws PresentationException

Constructs a dimensionless JQuantity from a String representing a number.
Note that it is possible for this method to throw a ClassCastException which will occur if NumberPresentation.parse() returns on object which cannot be cast as a MutableNumber. This is unlikely, however.

Parameters:

presentation - representation of number in the form understood by

Returns:

a new instance of JQuantity.

Throws:

PresentationException - if unable to parse appropriately.

See Also:

QuantityPresentation.valueOf(String)

valueOf

public static final BaseNumber valueOf(Presentable presentable)

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Creates and returns a copy of this JQuantity. Note that if the units of this JQuantity is not

Returns:

a clone of this instance.

Throws:

java.lang.CloneNotSupportedException - : not Cloneable (should be impossible)

See Also:

Cloneable

inverse

public Divisible inverse()

Method to yield the reciprocal of this and return it as the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

inverse in interface Divisible

Returns:

the reciprocal of this.

quotient

public Divisible quotient(BaseNumber divisor)
                   throws InvalidOperandException

Method to divide this by multiplicand and return the quotient as the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

quotient in interface Divisible

Parameters:

divisor - the number to multiply by this.

Returns:

the quotient of this divided by divisor.

Throws:

InvalidOperandException - operands are not compatible for the quotient operation.

getIdentifier

public java.lang.String getIdentifier()

Method to get the specific identifier for an object. If no identifier has been set, one will be generated.

Specified by:

getIdentifier in interface Identifiable

Returns:

the defined identifier, else "<" value ">"

isInteger

public boolean isInteger()

Method to implement Arithmetical.

Specified by:

isInteger in interface Arithmetical

Returns:

true if this is a dimensionless, exact integer.

compareTo

public int compareTo(JQuantity q)

Method to implement java.lang.Comparable.

Parameters:

q - the comparand object.

Returns:

an integer in range -1..1 depending with this is less than, equal or greater than the comparand.

product

public BaseNumber product(BaseNumber multiplicand)
                   throws InvalidOperandException

Method to implement form the product of this JQuantity and a BaseNumber.

Specified by:

product in class BaseNumber

Parameters:

multiplicand - the number which is to be multiplied by this.

Returns:

the product of this and the multiplicand, in the same units as this. If multiplicand is also a JQuantity, then the new units are the combination (sum) of the two units.

Throws:

InvalidOperandException - operands are not compatible for the quotient operation.

doubleValue

public double doubleValue()

Method to implement java.lang.Number.

Specified by:

doubleValue in class BaseNumber

Returns:

Note likely loss of precision.

floatValue

public float floatValue()

Method to implement java.lang.Number.

Specified by:

floatValue in class BaseNumber

Returns:

Note likely loss of precision.

intValue

public int intValue()

Description copied from class: BaseNumber

Returns the value of the specified number as an int. This may involve rounding or truncation.

Specified by:

intValue in class BaseNumber

Returns:

the integer value of the normalized version of this. Note likely loss of precision.

longValue

public long longValue()

Description copied from class: BaseNumber

Returns the value of the specified number as a long. This may involve rounding or truncation.

Specified by:

longValue in class BaseNumber

Returns:

Note likely loss of precision.

isInfinite

public boolean isInfinite()

Method to implement Arithmetical.

Specified by:

isInfinite in interface Arithmetical

Returns:

true if this is infinite.

isUnity

public boolean isUnity()

Method to implement Arithmetical.

Specified by:

isUnity in interface Arithmetical

Returns:

true if this is equal to 1.

signum

public int signum()

Method to implement Arithmetical.

Specified by:

signum in interface Arithmetical

Returns:

-1,0,1 according as the numerical value of this is less than, equal to, or greater than zero.

audit

public java.lang.String audit(java.lang.String label)

Method to implement com.rubecula.util.Auditable.

Specified by:

audit in interface Auditable

Parameters:

label - the label which is to be embedded into the result (may be null).

Returns:

an audit string for the number and units of this.

present

public Presentation present(AttrMap attributes)
                     throws PresentationException

Description copied from interface: Presentable

Convert this Presentable object into a Presentation, according to the set of attributes provided.

Specified by:

present in interface Presentable

Parameters:

attributes - the map of attributes required for the resulting presentation.

Returns:

an appropriate presentation of this quantity.

Throws:

PresentationException - if unable to parse appropriately.

makePresentableInstance

public Presentable makePresentableInstance(Presentation presentation)
                                    throws PresentationException

Instance method to convert a Presentation into a Presentable. Ideally, this would be a class method, but such a method cannot be defined in an interface. Nor can it be defined in an abstract class with the intention of overriding it in a subclass. Polymorphism just doesn't work that way.
Therefore, the present value (as in fields) of the instance is essentially ignored - only the methods are important.

Specified by:

makePresentableInstance in interface Presentable

Parameters:

presentation - of a number to be converted into a Presentable number.

Returns:

a number in the form of a Presentable.

Throws:

PresentationException - if presentation cannot be parsed appropriately.

sum

protected BaseNumber sum(BaseNumber addend)
                  throws InvalidOperandException

Method to determine the sum of a quantity with a base number.

Specified by:

sum in class BaseNumber

Parameters:

addend - the number which is to be added to this.

Returns:

the sum of this and addend.

Throws:

InvalidOperandException - operands are not compatible for the quotient operation.

pow

protected BaseNumber pow(int power)

Description copied from class: BaseNumber

Method to raise this to the power power return the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

pow in class BaseNumber

Parameters:

power - the power to which this quantity is to be raised.

Returns:

this^power.

scaled

protected BaseNumber scaled(long scale)

Method to multiply this quantity by an integral scale factor.

Specified by:

scaled in class BaseNumber

Parameters:

scale - the number which is to be multiplied by this.

Returns:

the product of this and scale (in the same units as this).

minus

protected BaseNumber minus()

Method to implement BaseNumber.

Specified by:

minus in class BaseNumber

Returns:

-this (in the same units as this).

getDimensions

public Dimensions getDimensions()

Method to return the dimensions of this Measurable.

Specified by:

getDimensions in interface Measurable

Returns:

the Dimensions.

getScale

public Rational getScale()

Method to return the scale of this Measurable.

Specified by:

getScale in interface Measurable

Returns:

the scale.

getOffset

public Rational getOffset()

Method to return the offset of this Measurable.

Specified by:

getOffset in interface Measurable

Returns:

the offset, usually $0.

flatten

public BaseUnit flatten()

Method to reduce a Units tree to a single flattened version.

Specified by:

flatten in interface Measurable

Returns:

the equivalent FlatUnit.

Throws:

JQuantityException

isNumber

public boolean isNumber()

Method to determine if this is dimensionless (i.e. unitless).

Specified by:

isNumber in interface Measurable

Returns:

true if not in any System.

isParallel

public boolean isParallel(Measurable that)

Method to determine if this Measurable is parallel to that Measurable.

Specified by:

isParallel in interface Measurable

Parameters:

that - the Measurable to compare.

Returns:

true if the Measurables are the same or if they differ only by a scale or offset.

normalize

public void normalize()

MUTATING instance method to normalize this object. Repeated applications of this method on an object should have no effect. The effective value of this object before and after normalization must be the same.

normalize

protected final void normalize(Measurable units)

MUTATING instance method to normalize this object by setting the units as specified and adjusting the value accordingly. Repeated applications of this method on an object should have no effect. The effective value of this object before and after normalization must be the same.

Parameters:

units - the units into which this should be converted.

getNumber

protected final BaseNumber getNumber()

Accessor method to get the number represented by this JQuantity.

Returns:

the value of the field _Number.

getUnit

protected final Measurable getUnit()

Accessor method to get the unit represented by this JQuantity.

Returns:

the value of the field _Units.

createUnits

final Measurable createUnits(UnitsName name,
                             SystemFlag system)

Create a new unit from this quantity and call it by name.

Parameters:

name - the name of the new Unit

Returns:

the new unit.

sum

private JQuantity sum(JQuantity addend)
               throws InvalidOperandException,
                      java.lang.CloneNotSupportedException

Method to add two quantities together.

Parameters:

addend - the quantity to add to this. Provided that the two quantities are parallel, the addend will first be normalized to be in the same units as this.

Returns:

if parallel, the sum of this and the normalized addend, in the units of this.

Throws:

JQuantityException - if units are not parallel.

InvalidOperandException - operands are not compatible for the quotient operation.

java.lang.CloneNotSupportedException

productJQuantity

JQuantity productJQuantity(JQuantity that,
                           boolean standardize)

Method to multiply two Quantities together.

Parameters:

that - the multiplicand, i.e. the quantity which is to be multiplied by this.

standardize - true if you want the result in the standard units for the combined system.

Returns:

the product of this and the multiplicand, in the combined (sum) units.

quotientJQuantity

JQuantity quotientJQuantity(JQuantity that)

Method to divide two Quantities.

Parameters:

that - the divisor.

Returns:

the quotient of this divided by that, in the combined (difference) units.

getSystem

public SystemFlag getSystem()

Specified by:

getSystem in interface Measurable

Returns:

the system flag for the units of this quantity.

factored

public Divisible factored(double factor)

Description copied from interface: Divisible

Method to yield the quotient of this divided by factor, and return it as the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

factored in interface Divisible

Parameters:

factor - the scale factor.

Returns:

the quotient of this divided by factor.

convertUnits

public JQuantity convertUnits(Measurable newUnits)

convertUnits

protected JQuantity convertUnits(SystemFlag system)

standardizeUnits

protected JQuantity standardizeUnits(SystemFlag system)