package Multprec_Natural_Numbers is

-- DESCRIPTION :
--   This package allows to manipulate natural numbers of arbitrary length.

-- DATA STRUCTURES :

  type Array_of_Naturals is array ( natural range <> ) of natural;
  type Natural_Number is private;

-- CREATORS :

  function Create ( n : natural ) return Array_of_Naturals;

  -- DESCRIPTION :
  --   Returns the representation of the natural number as coefficient vector.

  function Create ( n : natural ) return Natural_Number;

  -- DESCRIPTION :
  --   Returns the representation of n as a natural number.

  function Create ( n : Array_of_Naturals ) return Natural_Number;

  -- DESCRIPTION :
  --   Creates a number from the coefficients in n.

  -- REQUIRED : n'range = 0..n'last and n(i) < Base, for i in n'range.

  function Create ( n : Natural_Number ) return natural;

  -- DESCRIPTION :
  --   Returns the representation of n as a standard natural.

  -- REQUIRED : n < Base.

-- SELECTORS :

  function Base return natural;

  -- DESCRIPTION :
  --   Returns the base of the number representation.

  function Exponent return natural;

  -- DESCRIPTION :
  --   Returns the exponent: the number of decimal places in the base.

  function Empty ( n : Natural_Number ) return boolean;

  -- DESCRIPTION :
  --   Returns true if the number has not been created yet, or when it has
  --   been destroyed by the operation Clear; otherwise false is returned.
  --   An empty number is considered as zero.

  function Size ( n : Natural_Number ) return natural;

  -- DESCRIPTION :
  --   Returns the index of the last entry in the coefficient representation.

  function Decimal_Places ( n : natural ) return natural;

  -- DESCRIPTION :
  --   Returns the number of decimal places n occupies, Decimal_Places(0) = 0.

  function Decimal_Places ( n : Natural_Number ) return natural;

  -- DESCRIPTION :
  --   Returns the number of decimal places n occupies, Decimal_Places(0) = 0.
  --   Since n can be arbitrarily large, also the number of return should
  --   have no constraints on its size.  However, the current implementation
  --   would not support the manipulation of numbers whose size causes this
  --   function to crash.

  function Coefficient ( n : Natural_Number; i : natural ) return natural;

  -- DESCRIPTION :
  --   Returns the ith entry in the coefficient representation.

  function Coefficients ( n : Natural_Number ) return Array_of_Naturals;

  -- DESCRIPTION :
  --   Returns the coefficient representation of n, of range 0..Size(n).
  --   The number n equals then the sum of Coefficient(n,i)*Base**i,
  --   for i in 0..Size(n).

-- COMPARISON AND COPYING :

  function Equal ( n1 : Natural_Number; n2 : natural ) return boolean;
  function Equal ( n1,n2 : Natural_Number ) return boolean;

  -- DESCRIPTION :
  --   Returns true when both numbers n1 and n2 are equal, false otherwise.

  function "<" ( n1 : Natural_Number; n2 : natural ) return boolean;
  function "<" ( n1 : natural; n2 : Natural_Number ) return boolean;
  function "<" ( n1,n2 : Natural_Number ) return boolean;

  -- DESCRIPTION :
  --   Returns true if n1 < n2, false otherwise.

  function ">" ( n1 : Natural_Number; n2 : natural ) return boolean;
  function ">" ( n1 : natural; n2 : Natural_Number ) return boolean;
  function ">" ( n1,n2 : Natural_Number ) return boolean;

  -- DESCRIPTION :
  --   Returns true if n1 > n2, false otherwise.

  procedure Copy ( n1 : in natural; n2 : in out Natural_Number );
  procedure Copy ( n1 : in Natural_Number; n2 : in out Natural_Number );

  -- DESCRIPTION :
  --   Clears n2 and makes a copy of n1 to be equal to n2.
  --   Note that n2 := n1 leads to data sharing.

-- ARITHMETIC OPERATIONS as functions (no data sharing) :
--   Note that n1 >= n2 is required for subtraction, and n2 /= 0 for division.
--   The unary "-" operations have been added to make it ring-like.

  function "+" ( n1 : Natural_Number; n2 : natural ) return Natural_Number;
  function "+" ( n1 : natural; n2 : Natural_Number ) return Natural_Number;
  function "+" ( n1,n2 : Natural_Number ) return Natural_Number;

  function "-" ( n1 : Natural_Number; n2 : natural ) return Natural_Number;
  function "-" ( n1 : natural; n2 : Natural_Number ) return Natural_Number;
  function "-" ( n1,n2 : Natural_Number ) return Natural_Number;

  function "+" ( n : Natural_Number ) return Natural_Number;   -- copies n
  function "-" ( n : Natural_Number ) return Natural_Number;   -- copies n

  function "*" ( n1 : Natural_Number; n2 : natural ) return Natural_Number;
  function "*" ( n1 : natural; n2 : Natural_Number ) return Natural_Number;
  function "*" ( n1,n2 : Natural_Number ) return Natural_Number;

  function "**" ( n1 : Natural_Number; n2 : natural ) return Natural_Number;
  function "**" ( n1 : natural; n2 : Natural_Number ) return Natural_Number;
  function "**" ( n1,n2 : Natural_Number ) return Natural_Number;

  function "/" ( n1 : Natural_Number; n2 : natural ) return Natural_Number;
  function "/" ( n1 : natural; n2 : Natural_Number ) return natural;
  function "/" ( n1,n2 : Natural_Number ) return Natural_Number;

  function Rmd ( n1 : Natural_Number; n2 : natural ) return natural;
  function Rmd ( n1 : natural; n2 : Natural_Number ) return natural;
  function Rmd ( n1,n2 : Natural_Number ) return Natural_Number;

-- ARITHMETIC OPERATIONS as procedures for memory management :

  procedure Add ( n1 : in out Natural_Number; n2 : in natural );    -- "+"
  procedure Add ( n1 : in out Natural_Number; n2 : in Natural_Number );

  procedure Sub ( n1 : in out Natural_Number; n2 : in natural );    -- "-"
  procedure Sub ( n1 : in out Natural_Number; n2 : in Natural_Number );
  procedure Min ( n : in out Natural_Number );

  procedure Mul ( n1 : in out Natural_Number; n2 : in natural );    -- "*"
  procedure Mul ( n1 : in out Natural_Number; n2 : in Natural_Number );

  procedure Div ( n1 : in out Natural_Number; n2 : in natural );    -- "/"
  procedure Div ( n1 : in out Natural_Number; n2 : in Natural_Number );

  procedure Div ( n1 : in Natural_Number; n2 : in natural;  -- n1 = n2*q+r
                  q : out Natural_Number; r : out natural );
  procedure Div ( n1 : in out Natural_Number; n2 : in natural;
                  r : out natural );
  procedure Div ( n1,n2 : in Natural_Number; q,r : out Natural_Number );
  procedure Div ( n1 : in out Natural_Number; n2 : in Natural_Number;
                  r : out Natural_Number );

-- DESTRUCTOR :

  procedure Clear ( n : in out Natural_Number );

  -- DESCRIPTION :
  --   Deallocation of the memory space.  Empty(n) is true on return.

private
 
  type Natural_Number_Rep;
  type Natural_Number is access Natural_Number_Rep;

end Multprec_Natural_Numbers;