INTERFACE MPInt;
(* 
   This interface defines the signatures (in Modula-3) of procedures
   to manipulate multiple precision integer. It's based on the package 
   GNU Multiple Precision (GMP) implemented in C. 
   
   The structure of a big integer defined in the module MPZ is 
   
         (******** representation of a (big) integer ******)
    <--------------------------- nl ---------------------------->
    |Number Sign|   Least   |           |           |   Most    |
    |-1 => Neg. |Significant|           |           |Significant|
    | 0 => Zero |   Limb    |           |           |   Limb    |
    |+1 => Pos. |           |           |           |           |
    |___________|___________|___________|___________|___________|
          ^          ^                                    ^
          |          |                                    |
          0          nn                               is zero iff z=0 

   Created in Jun 04, 1997 by Marcus Vinicius A. Andrade
   Rewritten on Dec 08, 1997 by Marcus Vinicius A. Andrade
*)

IMPORT MPZ;

TYPE T = REF MPZ.T;
     SizeT = MPZ.SizeT;
     Sign  = MPZ.Sign;
     BaseT = MPZ.BaseT;
     
     Pair     = RECORD 
                  n,m : T       (* m/n is an approximation to a real NUMBER *)
                END;  

VAR DecDig : ARRAY [0..9] OF T; (* is initialized with decimal digits 0,1,.., 9  *)

PROCEDURE NumDigits(READONLY x : T) : SizeT;
  (* 
    Returns the number of limbs used by "x", it does not consider 
    leading zeros. If "x=0" then returns 0.  *)

PROCEDURE IsZero(READONLY x : T) : BOOLEAN;
  (* 
    Returns TRUE iff x=0, that is, if the signal of "x" is MP_ZERO *) 

PROCEDURE GetSign(READONLY x : T) : Sign;
  (* 
    Returns the sign of "z", that is, 
            -1 if z < 0;  
             0 if z = 0;
            +1 if z > 0.        *)

PROCEDURE Create(s : SizeT) : T;
  (* 
    Allocates memory space for a number whose size is established by "s"
    and sets it to zero. *)

PROCEDURE Copy(z : T) : T; 
  (* 
    Returns a copy of "x".  *)

PROCEDURE Neg(x : T) : T;
  (* 
    Returns the addictive inverse of "x", that is, "-z".  *)

PROCEDURE Abs(x : T) : T;
  (* 
    Returns the absolute value of "x".  *)

PROCEDURE Comp(x,y : T) : Sign;
  (* 
    Returns the value of (x-y)/|x-y|, that is,
           -1 if x < y,
            0 if x = y,
           +1 otherwise.        *)

PROCEDURE Add(x,y : T) : T;
  (* 
    Returns the number corresponding to "x+y"  *)

PROCEDURE Sub(x,y : T) : T;
  (* 
    Returns the number corresponding to "x-y"  *)

PROCEDURE Mult(x,y : T) : T;
  (*
    Returns the number corresponding to "x*y"  *)

PROCEDURE DivRem(x,y : T; VAR q,r : T); 
  (* 
     Computes q=x DIV y and r=x MOD y. Returns the signal of the
     quocient q.
     The values of q and r are such that x=yq + r and 0 <= r < |y|.
     If y=0 then termines abnormally 
     If y>0 then returns FLOOR(x/y)
     If y<0 then returns CEIL(x/y), 
     where / is the real numbers division.                    *)

PROCEDURE Div(x,y : T) : T; 
  (* 
    Returns the number corresponding to x DIV y where DIV is the
    integer numbers division.  Besides, 
               if y=0 then termines abnormally 
               if y>0 then returns FLOOR(x/y) 
               if y<0 then returns CEIL(x/y).  *)

PROCEDURE Mod(x,y : T) : T; 
  (* 
    Returns the number corresponding to x MOD y.  *)

PROCEDURE GCD(x,y : T) : T;
  (* 
    Returns the Greatest Commom Divisor of x and y. *)

PROCEDURE Sqrt(x : T; VAR r: T) : T; 
  (* 
    Returns the (floor of) square root of "x" and writes the 
    ramainder at "r".                                             *)
    
PROCEDURE IsPerfectSquare(x: T) : BOOLEAN;
  (* 
    Returns true if there exists an integer "y" such that "x=y^2" *)

PROCEDURE ToString(x : T; base : BaseT:=10) : TEXT;
  (* 
    Returns the string that represents the number "x" in the specified
    base base. Assumes that 2 <= base <= 16.  *)

PROCEDURE FromString(s : TEXT; base : BaseT:=10) : T;
  (* 
    Creates and returns a number whose value is given by the string
    "str" in the specified base. The string may contain leading spaces
    (that will be ignored), followed by an optional sign, followed by
    a series of digits. Assumes that 2 <= base <= 16.  *)

PROCEDURE FromInteger(i : INTEGER) : T;
  (* 
    Creates and returns a number whose value is given by the integer
    number i.  *)

PROCEDURE ToInteger(x : T) : INTEGER;
  (* 
    Returns the integer number corresponding to the value of the first
    digit in the number "x".  Note: it is the unique integer congruent
    to z mod 2^(31) *)

PROCEDURE Float(x : T) : LONGREAL;
  (* 
     Returns a longreal "y" equivalent to "x".                   *)

PROCEDURE Trunc(x : LONGREAL) : T;
  (* 
     Returns the "integer" part of "x".                          *)

PROCEDURE Floor(x : LONGREAL) : T;
  (* 
     Returns the greatest "integer" not exceeding.               *)

PROCEDURE Ceiling(x : LONGREAL) : T;
  (* 
     Returns the least "integer" not exceeding.                  *)

PROCEDURE Round(x : LONGREAL) : T;
  (* 
     Returns an "integer" approximation to "x".                  *)

PROCEDURE FromLongReal(x : LONGREAL; eps : LONGREAL) : Pair;
  (*
    Returns a pair [n,m] such that "ABS(x - m/n) <= eps.         *) 

PROCEDURE Random(l : INTEGER) : T;
  (*
    Returns a random number with ABS(l) digits. IF l < 0, it'll 
    generate a negative number, if l=0, generates "zero".        *)

END MPInt.