com.rubecula.jquantity
Class MutableNumber

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

All Implemented Interfaces:

Arithmetical, Arithmutable, Auditable, java.lang.Cloneable, java.lang.Comparable, Fuzzy, Identifiable, Millable, Mutable, Nameable, Presentable, java.io.Serializable

Direct Known Subclasses:

DivisibleMutable, WholeNumber

public abstract class MutableNumber

extends BaseNumber

implements Nameable, Arithmutable

Abstract class from which to derive other concrete classes of mutable numbers.

Objects of this class can be given identifiers, are changeable under standard arithmetic operators, and can be cloned and presented.
Although objects of this class are constructed mutable, individual instances can be made immutable via the method setConstant(). This allows "constant" values to be created for the class which will be protected against mutation.

Version:

$Revision: 1.17 $ // TODO There is an issue concerning Mutable numbers being referenced and then modified. We have now fixed the situations where "constants" were being modified. However, consider the following scenario: a (mutable) number is used as the denominator of a Rational; the Rational is then normalized; the orginal number has now been changed (at least potentially). This issue is resolved provided care is taken when using constructors of objects (the factory methods valueOf generally create constant instances).

Author:

Robin Hillyard

See Also:

Serialized Form

Field Summary

private boolean	_Constant This instance field signifies if this instance of MutableNumber has been designated a constant.
private java.lang.String	_Identifier The string which will be used to identify this object in audit trails and for debugging.
static BaseNumber	$__1 The constant value: -1
static BaseNumber	$0 The constant value: 0
static BaseNumber	$1 The constant value: 1
static BaseNumber	$10 The constant value: 10
static BaseNumber	$2 The constant value: 2
static BaseNumber	$3 The constant value: 3
private static int	$ADD
private static int	$MULTIPLY
private static int	$RAISETOPOWER

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

MutableNumber()

Method Summary

protected void	assertMutable() This method tests whether this particular instance is mutable, i.e. it has not been designated a constant.
java.lang.Object	clone() Creates and returns a copy of this object.
java.lang.String	defaultIdentifier()
protected abstract void	factor(Integral divisor) MUTATING METHOD: Replaces value with (this / divisor).
protected BaseNumber	factored(Integral factor) Method to divide this exactly by factor and return the quotient as the result.
void	forcePositive() MUTATING Instance method to force the value to be positive, i.e.
java.lang.String	getIdentifier() Method to get the specific identifier for an object.
java.lang.String	getIdentifier(boolean acceptDefault) Method to get the specific identifier for an object.
boolean	isLong() Method to determine if a value is integral and within range of long.
boolean	isMutable() This method indicates whether this particular instance is mutable, i.e. it has not been designated a constant.
private BaseNumber	opDyadic(int operator, BaseNumber operand) Method to operate on this number and operand according to operator.
private BaseNumber	opDyadicNoRecurse(int operator, BaseNumber operand) Method to add addend to this and return their sum as the result.
protected BaseNumber	product(BaseNumber multiplicand) Method to multiply multiplicand to this and return their product as the result.
Mutable	setConstant() This method sets this instance to be a constant, i.e. immutable.
void	setIdentifier(java.lang.String identifier) Method to set a specific identifier to an object.
protected void	setIdentifierPost(java.lang.String suffix) Method to form a new identifier for an object by appending string and wrapping.
protected void	setIdentifierPre(java.lang.String prefix) Method to form a new identifier for an object by prepending string and wrapping.
protected void	setIdentifierPrePost(java.lang.String prefix, java.lang.String suffix) Method to form a new identifier for an object by prepending one string, appending another then wrapping.
protected BaseNumber	sum(BaseNumber addend) Method to add addend to this and return their sum as the result.
protected void	test(java.io.PrintStream out, long check, java.lang.String label) Convenience method for auditing/checking a MutableNumber against a long.
Integral	toIntegral() Method to present a MutableNumber as an Integral number.

Methods inherited from class com.rubecula.jquantity.BaseNumber

abs, bestModel, BestModel, byteValue, characteristic, Characteristic, difference, doubleValue, floatValue, getBound, getBoundAbs, getModel, impartFuzziness, intValue, isEqual, isExact, isUncertain, isZero, longValue, minus, pow, scaled, shortValue, valueOf, 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.jquantity.Arithmutable

add, multiply, negate, raiseToPower, scale

Methods inherited from interface com.rubecula.jquantity.Arithmetical

isInfinite, isInteger, isUnity, signum

Methods inherited from interface com.rubecula.util.Auditable

audit, audit, audit

Methods inherited from interface com.rubecula.util.Presentable

makePresentableInstance, present

Field Detail

$0

public static final BaseNumber $0

The constant value: 0

$1

public static final BaseNumber $1

The constant value: 1

$2

public static final BaseNumber $2

The constant value: 2

$3

public static final BaseNumber $3

The constant value: 3

$10

public static final BaseNumber $10

The constant value: 10

$__1

public static final BaseNumber $__1

The constant value: -1

$ADD

private static final int $ADD

See Also:

Constant Field Values

$MULTIPLY

private static final int $MULTIPLY

See Also:

Constant Field Values

$RAISETOPOWER

private static final int $RAISETOPOWER

See Also:

Constant Field Values

_Identifier

private java.lang.String _Identifier

The string which will be used to identify this object in audit trails and for debugging.

_Constant

private boolean _Constant

This instance field signifies if this instance of MutableNumber has been designated a constant.

Constructor Detail

MutableNumber

public MutableNumber()

Method Detail

clone

public java.lang.Object clone()

Creates and returns a copy of this object.

Returns:

a clone of this instance.

Throws:

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

See Also:

Cloneable

sum

protected BaseNumber sum(BaseNumber addend)
                  throws InvalidOperandException

Method to add addend to this and return their sum 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.
IF this.sum(addend) cannot be evaluated; AND IF addend is an instance of this (and therefore also of MutableNumber); THEN we can try to evaluate addend.sum(this).
The actual implementation of the sum is performed using method opDyadicNoRecurse(int, BaseNumber) with arguments $ADD and addend.

Specified by:

sum in class BaseNumber

Parameters:

addend - the number to add to this.

Returns:

the sum of this and addend.

Throws:

InvalidOperandException - operands are not compatible for the sum operation.

product

protected BaseNumber product(BaseNumber multiplicand)
                      throws InvalidOperandException

Method to multiply multiplicand to this and return their product 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.
IF this.product(multiplicand) cannot be evaluated; AND IF multiplicand is an instance of this (and therefore also of MutableNumber); THEN we can try to evaluate multiplicand.product(this).
The actual implementation of the sum is performed using method opDyadicNoRecurse(int, BaseNumber), which in turn utilizes Arithmutable.multiply(BaseNumber).

// TODO Ideally, a potentially precise mutable number such as a Rational should not allow multiplication by an Approximation. Only the other way around should be allowed, as the result would then always be an Approximation, which is as it should be.

Specified by:

product in class BaseNumber

Parameters:

multiplicand - the number to add to this.

Returns:

the product of this and multiplicand.

Throws:

InvalidOperandException - operands are not compatible for the product operation.

opDyadic

private BaseNumber opDyadic(int operator,
                            BaseNumber operand)
                     throws InvalidOperandException

Method to operate on this number and operand according to operator. The logic is quite complex: If this is an instance of operand's class, then invoke this.opDyadicNoRecurse(operator,operand); else if operand is an instance of this' class, then invoke operand.opDyadicNoRecurse(operator,this) (i.e. reverse the order); else we just try this.opDyadicNoRecurse(operator,operand). In the event that this last invocation throws an InvalidOperandException, we give it one last shot in reverse: operand.opDyadicNoRecurse(operator,this). If this throws an exception it just gets passed up.

Parameters:

operator - in integer representing the operator: $ADD or $MULTIPLY.

operand - the number to add to this.

Returns:

the result of applying operator to this and operand.

Throws:

InvalidOperandException - operands are not compatible for the operation.

See Also:

opDyadicNoRecurse(int, BaseNumber)

opDyadicNoRecurse

private BaseNumber opDyadicNoRecurse(int operator,
                                     BaseNumber operand)
                              throws InvalidOperandException

Method to add addend to this and return their sum 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.
If this method fails on account of an invalid operand, then the exception is returned - it does not retry in any way.

Parameters:

operator - in integer representing the operator: $ADD or $MULTIPLY

operand - the number to operate on this.

Returns:

the result of applying operator to this and operand.

Throws:

InvalidOperandException - operands are not compatible for the operation.

isLong

public boolean isLong()

Method to determine if a value is integral and within range of long.

Returns:

true if isInteger() and if abs(value) < Long.MAX_VALUE.

forcePositive

public void forcePositive()

MUTATING Instance method to force the value to be positive, i.e. this = abs (this). // TODO We cannot update the estimate here, since MutableNumber doesn't implement Estimable. I suppose we could do it if result is instanceof Estimable.

Specified by:

forcePositive in interface Arithmutable

toIntegral

public Integral toIntegral()

Method to present a MutableNumber as an Integral number. If this is already of class Integral then just return this, else created a Manifest from the long value.

Returns:

an instance of Integral with value equivalent to this.

setIdentifier

public void setIdentifier(java.lang.String identifier)

Method to set a specific identifier to an object.

Specified by:

setIdentifier in interface Nameable

Parameters:

identifier - the identifier to associate with the object

getIdentifier

public java.lang.String getIdentifier()

Method to get the specific identifier for an object.

Specified by:

getIdentifier in interface Identifiable

Returns:

the defined identifier, else null

getIdentifier

public java.lang.String getIdentifier(boolean acceptDefault)

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

Parameters:

acceptDefault - true if caller is willing to accept a generated identifier.

Returns:

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

defaultIdentifier

public java.lang.String defaultIdentifier()

factor

protected abstract void factor(Integral divisor)

MUTATING METHOD: Replaces value with (this / divisor).
This method allows for division by a non-Divisible divisor. In some implementations, an exception will be thrown if the quotient cannot be expressed (for example it is non-integral for a WholeNumber).

Parameters:

divisor - value by which this WholeNumber is to be divided.

factored

protected BaseNumber factored(Integral factor)

Method to divide this exactly by factor 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:

factor - the number to divide into this.

Returns:

the exact quotient of this divided by factor. If factor doesn't divide exactly into this, an exception will be thrown.

See Also:

// TODO We cannot update the estimate here, since MutableNumber doesn't implement Estimable. I suppose we could do it if result is instanceof Estimable.

setIdentifierPost

protected void setIdentifierPost(java.lang.String suffix)

Method to form a new identifier for an object by appending string and wrapping.

Parameters:

suffix - the identifier to append to object identifier

setIdentifierPre

protected void setIdentifierPre(java.lang.String prefix)

Method to form a new identifier for an object by prepending string and wrapping.

Parameters:

prefix - the identifier to prepend to object identifier

setIdentifierPrePost

protected void setIdentifierPrePost(java.lang.String prefix,
                                    java.lang.String suffix)

Method to form a new identifier for an object by prepending one string, appending another then wrapping.

Parameters:

prefix - the identifier to prepend to object identifier

suffix - the identifier to append to object identifier

test

protected void test(java.io.PrintStream out,
                    long check,
                    java.lang.String label)

Convenience method for auditing/checking a MutableNumber against a long.

Parameters:

out - the output stream.

check - the number to compare against.

label - the label to print with the audit trals.

setConstant

public Mutable setConstant()

This method sets this instance to be a constant, i.e. immutable. Future calls to the isMutable() method will yield false.

Specified by:

setConstant in interface Mutable

Returns:

as a convenience this method returns itself.

isMutable

public boolean isMutable()

This method indicates whether this particular instance is mutable, i.e. it has not been designated a constant.

Specified by:

isMutable in interface Mutable

Returns:

true if this instance can be mutated, otherwise false (it is constant).

assertMutable

protected void assertMutable()

This method tests whether this particular instance is mutable, i.e. it has not been designated a constant. If it is not mutable, an RuntimeException is thrown. // TODO instead generate an assertion exception (or some other kind of runtime exception).