/** An interface for any class that supports various numeric operations.<p>
 *
 * There are many possible implementations of this interface.  For
 * example, java.math.BigInteger happens to implement it (and more),
 * since I took care to borrow the method names from BigInteger.
 * But in this assignment, you will give an alternative implementation
 * that uses Russian dolls instead.<p>
 * 
 * This interface is declared as extending Comparable, meaning that
 * it supports the compareTo method.  So Russian dolls will be instances
 * of Comparable as well as Numeric and RussianDoll.  This means that 
 * you could call the static method java.util.Arrays.sort in order to sort 
 * an array of Russian dolls.<p>
 *
 * The interface provides an (abstract) method {@link Numeric#longValue}
 * for converting instances of Numeric to ordinary Java longs.  (We
 * use long rather than int because that's what BigInteger does.)  Of
 * course we'd like a static method for converting in the other
 * direction, too.  Static methods can't actually be declared in a
 * Java interface (there is no such thing as an abstract static
 * method, since static methods have no dynamic method lookup and
 * can't be overridden).  Nonetheless, any non-abstract class Foo that
 * implements the Numeric interface really <i>should</i> define a
 * static method as follows:<p>
 * <pre>
 * /** Construct an instance of this class that represents a Java long.
 *  * @param val The long to represent.  
 *  * @throws ClassCastException If the long cannot
 *  *         be represented by this implementing class.  For 
 *  *         example, RussianDoll cannot represent negative numbers.
 *  * /
 * public static Foo valueOf(long val) {
 *    ... probably call a constructor for Foo ...
 * }
 * </pre>
 * 
 * @author Jason Eisner
 * @version 1.0, 2003-02-07 
 */

public interface Numeric extends Comparable {

  // ************* TYPE CONVERSIONS ************

  /** @return The ordinary Java long that this represents.  
   *  @throws ClassCastException If the number that this 
   *          represents is not expressible as a Java long (e.g., 
   *          it is too big, too small, a fraction, etc.).
   */
  public long longValue();

  // ************* COMPARISON METHODS ************

  /** @param o The object to compare to.
   * @return True If this has the same numeric value as o, otherwise false.
   * @throws ClassCastException If o cannot be cast to the same type as this.
   */
  public boolean equals(Object o);

  /** @param o The object to compare to.
   * @return -1, 0, or 1 according to whether this is less than, equal to, or greater than o.
   * @throws ClassCastException If o's type prevents it from being compared to this.
   */
  public int compareTo(Object o);
  
  // ************* ARITHMETIC METHODS ************

  /** @return The sum (this + val). 
   * @throws ClassCastException if the types of this and val are incompatible.
   */
  public Numeric add(Numeric val);

  /** @return The difference (this - val). 
   * @throws ClassCastException if the types of this and val are incompatible.
   */
  public Numeric subtract(Numeric val);

  /** @return The product (this * val). 
   * @throws ClassCastException if the types of this and val are incompatible.
   */
  public Numeric multiply(Numeric val);

  /** @return Returns an array of two Numerics, containing
   * the integer quotient (this / val, rounded down)
   * and the remainder (this % val).
   * @throws ClassCastException if the types of this and val are incompatible.
   * @throws ArithmeticException in case of division by zero.
   */
  public Numeric[] divideAndRemainder(Numeric val);
}