com.rubecula.jquantity
Class JQuantity

java.lang.Object
  |
  +--java.lang.Number
        |
        +--com.rubecula.jquantity.BaseNumber
              |
              +--com.rubecula.jquantity.JQuantity

All Implemented Interfaces:

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

public class JQuantity

extends BaseNumber

implements Measurable, java.lang.Cloneable

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

Author:

Robin Hillyard

See Also:

Serialized Form

Field Summary

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, Units 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.
(package private) Units	createUnits(java.lang.String name) Create a new unit from this quantity and call it by name.
double	doubleValue() Method to implement java.lang.Number.
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.
protected Units	getUnit() Accessor method to get the unit represented by this JQuantity.
int	intValue()
JQuantity	inverse() Method to yield the reciprocal of this and return it as the result.
boolean	isInfinite() Method to implement Arithmetical.
boolean	isInSystem(int sysIndex) Method to determine if this Measurable is in a certain system of units.
boolean	isInteger() Method to implement Arithmetical.
boolean	isNumber() Method to determine if this is dimensionless (i.e.
boolean	isParallel(Measurable that) Method to determine if this Measurable is parallel to that Measurable.
boolean	isUnity() Method to implement Arithmetical.
long	longValue()
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(Units 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) Method to multiply two Quantities together.
JQuantity	quotient(BaseNumber divisor) Method to divide this by multiplicand and return the quotient as the result.
protected BaseNumber	scaled(long scale) Method to multiply this quantity by an integral scale factor.
int	signum() Method to implement Arithmetical.
protected BaseNumber	sum(BaseNumber addend) Method to determine the sum of a quantity with a base number.

Methods inherited from class com.rubecula.jquantity.BaseNumber

abs, audit, audit, bestModel, BestModel, Characteristic, compareTo, difference, getBound, getBoundAbs, getModel, impartFuzziness, isEqual, isExact, isUncertain, isZero, present, test, test, toString, valueOfLog10, Wrap

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

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

Constructor Detail

JQuantity

public JQuantity(BaseNumber number,
                 Units 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(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:

NumberPresentation(String).

Method Detail

main

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

Main method for testing purposes.

Parameters:

args - command line arguments.

clone

public java.lang.Object clone()

Creates and returns a copy of this JQuantity.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this instance.

Throws:

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

See Also:

Cloneable

inverse

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

Returns:

the reciprocal of this.

quotient

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

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 Auditable

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 java.lang.Number

Returns:

Note likely loss of precision.

floatValue

public float floatValue()

Method to implement java.lang.Number.

Specified by:

floatValue in class java.lang.Number

Returns:

Note likely loss of precision.

intValue

public int intValue()

Specified by:

intValue in class java.lang.Number

Returns:

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

longValue

public long longValue()

Specified by:

longValue in class java.lang.Number

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.

isInSystem

public boolean isInSystem(int sysIndex)

Method to determine if this Measurable is in a certain system of units.

Parameters:

sysIndex - the index of the units system.

Returns:

true of this Measurable belongs to System defined by sysIndex.

flatten

public BaseUnit flatten()

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

Returns:

the equivalent FlatUnit.

Throws:

JQuantityException

isNumber

public boolean isNumber()

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

Returns:

true if not in any System.

isParallel

public boolean isParallel(Measurable that)

Method to determine if this Measurable is parallel to that 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(Units 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 Units getUnit()

Accessor method to get the unit represented by this JQuantity.

Returns:

the value of the field _Units.

createUnits

final Units createUnits(java.lang.String name)

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

Parameters:

name - the name of the new Unit

Returns:

the new unit.

productJQuantity

JQuantity productJQuantity(JQuantity that)

Method to multiply two Quantities together.

Parameters:

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

Returns:

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