001 /** An interface for any class that supports various numeric operations.<p>
002 *
003 * There are many possible implementations of this interface. For
004 * example, java.math.BigInteger happens to implement it (and more),
005 * since I took care to borrow the method names from BigInteger.
006 * But in this assignment, you will give an alternative implementation
007 * that uses Russian dolls instead.<p>
008 *
009 * This interface is declared as extending Comparable, meaning that
010 * it supports the compareTo method. So Russian dolls will be instances
011 * of Comparable as well as Numeric and RussianDoll. This means that
012 * you could call the static method java.util.Arrays.sort in order to sort
013 * an array of Russian dolls.<p>
014 *
015 * The interface provides an (abstract) method {@link Numeric#longValue}
016 * for converting instances of Numeric to ordinary Java longs. (We
017 * use long rather than int because that's what BigInteger does.) Of
018 * course we'd like a static method for converting in the other
019 * direction, too. Static methods can't actually be declared in a
020 * Java interface (there is no such thing as an abstract static
021 * method, since static methods have no dynamic method lookup and
022 * can't be overridden). Nonetheless, any non-abstract class Foo that
023 * implements the Numeric interface really <i>should</i> define a
024 * static method as follows:<p>
025 * <pre>
026 * /** Construct a representation of a Java long.
027 * * @param val The long to represent.
028 * * @throws ClassCastException If the long cannot
029 * * be represented by the implementing class. For
030 * * example, RussianDoll cannot represent negative numbers.
031 * * /
032 * public static Foo valueOf(long val) {
033 * ... probably call a constructor for Foo ...
034 * }
035 * </pre>
036 *
037 * @author Jason Eisner
038 * @version 1.0, 2003-02-07
039 */
040
041 public interface Numeric extends Comparable {
042
043 // ************* TYPE CONVERSIONS ************
044
045 /** @return The ordinary Java long that this represents.
046 * @throws ClassCastException If the number that this
047 * represents is not expressible as a Java long (e.g.,
048 * it is too big, too small, a fraction, etc.).
049 */
050 public long longValue();
051
052 // ************* COMPARISON METHODS ************
053
054 /** @param o The object to compare to.
055 * @return True If this has the same numeric value as o, otherwise false.
056 * @throws ClassCastException If o cannot be cast to the same type as this.
057 */
058 public boolean equals(Object o);
059
060 /** @param o The object to compare to.
061 * @return -1, 0, or 1 according to whether this is less than, equal to, or greater than o.
062 * @throws ClassCastException If o's type prevents it from being compared to this.
063 */
064 public int compareTo(Object o);
065
066 // ************* ARITHMETIC METHODS ************
067
068 /** @return The sum (this + val).
069 * @throws ClassCastException if the types of this and val are incompatible.
070 */
071 public Numeric add(Numeric val);
072
073 /** @return The difference (this - val).
074 * @throws ClassCastException if the types of this and val are incompatible.
075 */
076 public Numeric subtract(Numeric val);
077
078 /** @return The product (this * val).
079 * @throws ClassCastException if the types of this and val are incompatible.
080 */
081 public Numeric multiply(Numeric val);
082
083 /** @return Returns an array of two Numerics, containing
084 * the integer quotient (this / val, rounded down)
085 * and the remainder (this % val).
086 * @throws ClassCastException if the types of this and val are incompatible.
087 * @throws ArithmeticException in case of division by zero.
088 */
089 public Numeric[] divideAndRemainder(Numeric val);
090 }