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    }