Interface MyNumber

All Known Subinterfaces:

MyIntegralNumber

interface MyNumber

A mutable number.

[Note on "compatibility": (You may skip this section on first reading.)

Given the level of abstraction enforced by the MyNumber interface, is it reasonable to expect a class's MyNumber-accepting methods to be able to handle arbitrary MyNumbers? For example...

   MyNumber  m = new MyInteger(2);
   MyNumber  n = new MyObscureInteger(3);

   m.plus(n);  // ...what should happen?

Doesn't it seem a bit unfair to expect the author MyInteger to know how to deal with MyObscureInteger? [Especially since the latter class might not have even existed when MyInteger was written.]

To give MyInteger's author a way out of this fix, we introduce a notion of "compatibility" between MyNumber classes... Suppose that N1 and N2 are two classes that both implement MyNumber. If N1's MyNumber-accepting methods can always handle instances of N2, and likewise if N2's MyNumber-accepting methods can always handle instances of N1, then N1 and N2 are said to be "compatible." Also, as you might expect, if n1 is an instance of class N1 and n2 is an instance of class N2, then "n1 is compatible with n2" is equivalent to saying "N1 is compatible with N2."

At a minimum, a class N that implements MyNumber must be compatible with itself. In fact, N is typically the only class that is compatible with N.

Thus, the author of MyInteger can simply proclaim, "MyInteger is compatible only with itself!" He is then free to ignore MyObscureInteger, since the behavior of the m.plus(n) line above is officially undefined...]

[If Java supported a ThisType mechanism, we could cleanly sidestep the entire "compatibility" morass. With ThisType at our disposal, we could simply say...

   public void plus(ThisType n);
   public ThisType squareOf();
   // etc.

...since ThisType essentially means "the same class as this."]

[Note that the compatibility issue is not peculiar to MyNumber; the same basic problem surfaces in the standard java.lang.Comparable interface, for example.]

[What methods might you add to MyNumber, if you were interested in requiring all MyNumbers to be compatible?]

Method Summary

java.lang.Object	clone() Returns a new MyNumber object that initially equals this.
MyNumber	createCompatible(int i) Returns a new MyNumber object that initially holds the value i.
boolean	equals(java.lang.Object o) Tests whether o and this are equal.
boolean	lessThan(MyNumber n) Returns true if this is smaller than n.
void	minus() Replaces this with -this.
void	plus(MyNumber n) Replaces this with this + n.
MyNumber	squareOf() Returns a new object holding the square of the value of this.
void	times(MyNumber n) Replaces this with this * n.
java.lang.String	toString() Retrieves the decimal representation of the stored integer.

Method Detail

lessThan

public boolean lessThan(MyNumber n)

Returns true if this is smaller than n.

[The behavior of the lessThan method is undefined if n is not compatible with this.]

Parameters:

n - the number to compare against this

Returns:

true if this is less than n; false otherwise

plus

public void plus(MyNumber n)

Replaces this with this + n.

[The behavior of the plus method is undefined if n is not compatible with this.]

Parameters:

n - the number to be added to this

times

public void times(MyNumber n)

Replaces this with this * n.

[The behavior of the times method is undefined if n is not compatible with this.]

Parameters:

n - the number by which this is to be scaled

minus

public void minus()

Replaces this with -this.

squareOf

public MyNumber squareOf()

Returns a new object holding the square of the value of this.

[The returned object is guaranteed to be an instance of this's class.]

Returns:

a new MyNumber object (of the same class as this) that initially stores the square of this object's integer value.

createCompatible

public MyNumber createCompatible(int i)

Returns a new MyNumber object that initially holds the value i.

[The returned object is guaranteed to be an instance of this's class.]

Example:

   // construct n...
   MyNumber n   = new MyInteger(3);

   // increment n...
   MyNumber one = n.createCompatible(1);  // ...one is a MyInteger.
   n.plus(one);

[The behavior of the createCompatible method is undefined if i is too large (or too small) to be handled by this's variety of number.]

Returns:

a new MyNumber (of the same class as this) that takes i as its initial stored value

clone

public java.lang.Object clone()

Returns a new MyNumber object that initially equals this.

[The returned object is guaranteed to be an instance of this's class.]

Overrides:

clone in class java.lang.Object

Returns:

a new MyNumber (of the same class as this) that takes this's integer value as its initial stored value

equals

public boolean equals(java.lang.Object o)

Tests whether o and this are equal.

Overrides:

equals in class java.lang.Object

Parameters:

o - the object to compare against this

Returns:

true if (1) o is a MyNumber that is compatible with this and (2) o and this currently store the same integer value; false otherwise

toString

public java.lang.String toString()

Retrieves the decimal representation of the stored integer.

Overrides:

toString in class java.lang.Object

Returns:

a String that represents the stored integer, in decimal