com.rubecula.jquantity
Class BaseNumber

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

All Implemented Interfaces:

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

Direct Known Subclasses:

Approximation, JQuantity, Manifest, MutableNumber

public abstract class BaseNumber

extends java.lang.Number

implements Presentable, Arithmetical, Auditable, java.lang.Comparable, Fuzzy

Abstract numerical class from which to derive other concrete classes. Objects of this class can be characterized as to their value, can be "audited", that is to say viewed in detail, and can be compared with other objects. Objects of this class "may be" fuzzy - that is they support the Fuzzy interface. Instances of this class can also be "presented", resulting in an instance of Presentation (which in turn can be rendered as a string).

Version:

$Revision: 1.13 $

Author:

Robin Hillyard

See Also:

Serialized Form

Field Summary

Fields inherited from interface com.rubecula.jquantity.Fuzzy

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

Constructor Summary

BaseNumber()

Method Summary

protected BaseNumber	abs() Method to yield this or a copy with the sign changed, depending whether the value is positive or negative.
java.lang.String	audit() Method to return a detailed (unlabeled) string from an object for debugging purposes.
void	audit(java.io.PrintStream out, java.lang.String label) Method to output detailed string from an object for debugging purposes.
int	bestModel(Fuzzy that) Method to help in combining distribution models.
protected static int	BestModel(int modelX, int modelY) Class method to help in combining distribution models.
(package private) static int	Characteristic(double x) Method to yield the characteristic of value x (whether positive or negative).
int	compareTo(java.lang.Object that) This method is the default compareTo method for any objects in the JQuantity package.
protected BaseNumber	difference(BaseNumber subtrahend) Method to yield the difference of this less a BaseNumber (subtrahend).
double	getBound() Method to get the relative bound of this non-fuzzy value;
double	getBoundAbs() Method to get the absolute bound of this non-fuzzy value;
int	getModel() Method to get the error distribution model of this non-fuzzy value.
Presentation	impartFuzziness(NumberPresentation presentation) Method to impart a NumberPresentation presentation with appropriate fuzzy information and ensure that the resulting string value is properly rounded.
boolean	isEqual(BaseNumber other) Method to determine effect equality with another BaseNumber.
boolean	isExact() Method to return true for this non-fuzzy instance.
boolean	isUncertain() Method to determine if this object is of uncertain value due to fuzziness.
boolean	isZero() Method to make standard test against zero.
protected abstract BaseNumber	minus() Method to yield a copy of this but with the sign changed.
protected abstract BaseNumber	pow(int power) Method to raise this to the power power return the result.
Presentation	present() Convert this Presentable object into a Presentation with default attributes.
protected abstract BaseNumber	product(BaseNumber multiplicand) Method to multiply multiplicand by this and return their product as the result.
protected abstract BaseNumber	scaled(long factor) Method to multiply multiplicand by this and return their product as the result.
protected abstract BaseNumber	sum(BaseNumber addend) Method to add addend to this and return their sum as the result.
protected void	test(java.io.PrintStream out, BaseNumber check)
protected void	test(java.io.PrintStream out, BaseNumber check, java.lang.String label)
java.lang.String	toString() This is the default toString method for all BaseNumbers.
(package private) static double	valueOfLog10(double x)
protected static java.lang.String	Wrap(java.lang.String string) Class method to wrap a string in "<" and ">".

Methods inherited from class java.lang.Number

byteValue, doubleValue, floatValue, intValue, longValue, shortValue

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.rubecula.util.Presentable

makePresentableInstance, present

Methods inherited from interface com.rubecula.jquantity.Arithmetical

isInfinite, isInteger, isUnity, signum

Methods inherited from interface com.rubecula.util.Auditable

audit, getIdentifier

Constructor Detail

BaseNumber

public BaseNumber()

Method Detail

Wrap

protected static java.lang.String Wrap(java.lang.String string)

Class method to wrap a string in "<" and ">". Note: this method relates to the Auditable class and would be defined there if that was legal.

Parameters:

string - the string to be wrapped.

Returns:

string wrapped in "<>".

BestModel

protected static int BestModel(int modelX,
                               int modelY)

Class method to help in combining distribution models. Note: this method would be defined in the Fuzzy interface itself if that was legal.

Parameters:

modelX - the first model to combine.

modelY - the second model to combine.

Returns:

the best model combined from modelX and modelY.

minus

protected abstract BaseNumber minus()

Method to yield a copy of this but with the sign changed.
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.

Note that this method is parallel but not congruent with the method of the same name defined in the Integral interface.

Returns:

negative version of this.

sum

protected abstract 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.

Parameters:

addend - the number to add to this.

Returns:

the sum of this and addend.

Throws:

InvalidOperandException - if the operands are incompatible.

difference

protected BaseNumber difference(BaseNumber subtrahend)
                         throws InvalidOperandException

Method to yield the difference of this less a BaseNumber (subtrahend).
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:

subtrahend - the number to subtract from this.

Returns:

the difference of this less subtrahend.

Throws:

InvalidOperandException - if the operands are incompatible.

product

protected abstract BaseNumber product(BaseNumber multiplicand)
                               throws InvalidOperandException

Method to multiply multiplicand by 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.

Parameters:

multiplicand - the number to multiply by this.

Returns:

the product of this and multiplicand.

Throws:

InvalidOperandException - if the operands are incompatible.

scaled

protected abstract BaseNumber scaled(long factor)

Method to multiply multiplicand by 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.

Parameters:

factor - the number to multiply by this.

Returns:

the product of this and multiplicand.

pow

protected abstract BaseNumber pow(int power)

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.

Parameters:

power - the exponent for this.

Returns:

the value of this raised to the power power.

compareTo

public int compareTo(java.lang.Object that)

This method is the default compareTo method for any objects in the JQuantity package. If it is invoked, then there was no method declared which matched the objects more precisely. Each subclass (A) of BaseNumber is expected to declare a method of signature int compareTo(A). Furthermore, any subclass (A) of a class (B) which is itself a subclass of BaseNumber should provide a public constructor with signature: A(B).

So why is this method necessary at all? Surely polymporphism takes care of all this stuff? Well, not quite. First of all, the jquantity package is complex because it involves so many apparently unrelated classes and interfaces, which nevertheless are directly comparable (for example, Manifest and WholeNumber). Second, there is always the danger of coding infinite recursions in the individual compareTo(Object) methods. Thirdly, there is the fact that it is impossible in general to ensure that the "that" object is in any sense more primitive than the "this" object. Frequently, it will be the other way around, in which case the comparison must be reversed.

There are four possibilities for the relationship between the classes of this and that:

1. this isa that-class and that isa this-class, i.e. the classes are the same;
2. this isa that-class (but not that isa this-class);
3. that isa this-class (but not this isa that-class);
4. neither this isa that-class nor that isa this-class.

For case 1, it is expected for any subclass (A) of BaseNumber that there is defined a method int compareTo(A). In case 2, it may be possible to widen that into this-class and then perform the comparison. In case 3, it may be possible to compare the objects in the opposite ordering: i.e. to evaluate
- that.compareTo(this). In case 4, there is nothing to be done - no comparison is valid, unless explicitly provided for in this-class - or if that implements an interface such that there is defined in this-class a method int compareTo(interface).

Note also that extenders of this class should implement int compareTo(A) in such a way that if the objects to be compared are equal (in the sense of this.equals(that)) then 0 should be returned without further ado. Also note that since the methods isEqual(that) typically invoke compareTo, a compareTo method must not invoke isEqual.

The following is the standard javadoc for the compareTo(Object) method as defined in the Comparable interface:
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.

The implementor must ensure sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception iff y.compareTo(x) throws an exception.)

The implementor must also ensure that the relation is transitive: (x.compareTo(y)>0 && y.compareTo(z)>0) implies x.compareTo(z)>0.

Finally, the implementer must ensure that x.compareTo(y)==0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.

It is strongly recommended, but not strictly required that (x.compareTo(y)==0) == (x.equals(y)). Generally speaking, any class that implements the Comparable interface and violates this condition should clearly indicate this fact. The recommended language is "Note: this class has a natural ordering that is inconsistent with equals."

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

that - 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.RuntimeException - if the specified object's type prevents it from being compared to this Object.

present

public Presentation present()
                     throws PresentationException

Convert this Presentable object into a Presentation with default attributes.

Returns:

an appropriate instance of Presentation.

Throws:

PresentationException - if this object cannot be presented with given attributes.

getBoundAbs

public double getBoundAbs()

Method to get the absolute bound of this non-fuzzy value;

Returns:

0 double

getBound

public double getBound()

Method to get the relative bound of this non-fuzzy value;

Specified by:

getBound in interface Fuzzy

Returns:

0 double

getModel

public int getModel()

Method to get the error distribution model of this non-fuzzy value.

Specified by:

getModel in interface Fuzzy

Returns:

Fuzzy.$DistNone

isExact

public boolean isExact()

Method to return true for this non-fuzzy instance.

Specified by:

isExact in interface Fuzzy

Returns:

true boolean: always

audit

public java.lang.String audit()

Method to return a detailed (unlabeled) string from an object for debugging purposes.

Specified by:

audit in interface Auditable

Returns:

the detailed string.

audit

public void audit(java.io.PrintStream out,
                  java.lang.String label)

Method to output detailed string from an object for debugging purposes.

Specified by:

audit in interface Auditable

Parameters:

out - the output stream.

label - the label to attach to the output (may be null).

toString

public java.lang.String toString()

This is the default toString method for all BaseNumbers. Specific classes will override as appropriate.

Overrides:

toString in class java.lang.Object

Returns:

a String representing this BaseNumber

impartFuzziness

public Presentation impartFuzziness(NumberPresentation presentation)
                             throws PresentationException

Method to impart a NumberPresentation presentation with appropriate fuzzy information and ensure that the resulting string value is properly rounded.

Parameters:

presentation - the unfuzzy NumberPresentation.

Returns:

if this exact, then return presentation; else return a copy of presentation, with fuzzy information set appropriately.

Throws:

PresentationException

isUncertain

public boolean isUncertain()

Method to determine if this object is of uncertain value due to fuzziness.

Returns:

false if isExact(); else true if this is zero and bounds are non-zero; else true if the relative bounds are either NaN or greater/equal to 1.

abs

protected final BaseNumber abs()

Method to yield this or a copy with the sign changed, depending whether the value is positive or negative.

Returns:

this or a negative version of this.

isZero

public final boolean isZero()

Method to make standard test against zero.

Returns:

if this is an exact number, then signnum()==0; else isUncertain().

isEqual

public final boolean isEqual(BaseNumber other)

Method to determine effect equality with another BaseNumber. This is NOT as strict a test of equality as the equals method inherited from Object. Indeed, for fuzzy objects, equality means that the arithmetical difference is not significant, given the error bounds of the two objects.
Important Note for implementers: do not invoke this method from a compareTo(Object) method otherwise an infinite recursion will surely result.

Parameters:

other - the number to compare.

Returns:

true if the arithmetical difference between this and other is not significant.

bestModel

public final int bestModel(Fuzzy that)

Method to help in combining distribution models.

Parameters:

that - the other model source.

Returns:

the value of the best model from Fuzzy.$DistUniform, etc.

Characteristic

static int Characteristic(double x)

Method to yield the characteristic of value x (whether positive or negative).

Parameters:

x - the value whose characteristic is required.

Returns:

if (x from 1.0->9.999) then 0; else if (x from 0.1->0.9999) then -1; and other numbers as appropriate.

valueOfLog10

static double valueOfLog10(double x)

test

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

test

protected final void test(java.io.PrintStream out,
                          BaseNumber check)