(*!m2pim*) (* Copyright (c) 2017 Modula-2 Software Foundation. *)

DEFINITION MODULE CardMath;

(* Cardinal Math library *)


(* Math operations *)

(* --------------------------------------------------------------------------
 * function abs(i)
 * --------------------------------------------------------------------------
 * Returns the absolute CARDINAL value of INTEGER i
 * ----------------------------------------------------------------------- *)

PROCEDURE abs ( i : INTEGER ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function pow2(n)
 * --------------------------------------------------------------------------
 * Returns the power of 2 for argument n
 * ----------------------------------------------------------------------- *)

PROCEDURE pow2 ( n : CARDINAL ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function log2(n)
 * --------------------------------------------------------------------------
 * Returns the integral part of the logarithm of 2 for argument n
 * ----------------------------------------------------------------------- *)

PROCEDURE log2 ( n : CARDINAL ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function pow10(n)
 * --------------------------------------------------------------------------
 * Returns the power of 10 for argument n
 * ----------------------------------------------------------------------- *)

PROCEDURE pow10 ( n : CARDINAL ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function log10(n)
 * --------------------------------------------------------------------------
 * Returns the integral part of the logarithm of 10 for argument n
 * ----------------------------------------------------------------------- *)

PROCEDURE log10 ( n : CARDINAL ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function maxDecimalDigits(n)
 * --------------------------------------------------------------------------
 * Returns the number of decimal digits of the largest unsigned integer that
 * can be encoded in base-2 using n number of 8-bit octets for 1 <= n <= 16.
 * ----------------------------------------------------------------------- *)

TYPE Card1To16 = CARDINAL [1..16]; (* max 128 bits *)

PROCEDURE maxDecimalDigits ( octets : Card1To16 ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function twosComplement(n)
 * --------------------------------------------------------------------------
 * Returns the two's complement of n
 * ----------------------------------------------------------------------- *)

PROCEDURE twosComplement ( n : CARDINAL ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function addWouldOverflow(n, m)
 * --------------------------------------------------------------------------
 * Returns TRUE if operation n + m overflows, else FALSE.
 * ----------------------------------------------------------------------- *)

PROCEDURE addWouldOverflow ( n, m : CARDINAL ) : BOOLEAN;


(* Bit operations *)

(* --------------------------------------------------------------------------
 * function shl(n, shiftFactor)
 * --------------------------------------------------------------------------
 * Returns the value of n, shifted left by shiftFactor.
 * ----------------------------------------------------------------------- *)

PROCEDURE shl ( n, shiftFactor : CARDINAL ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function shr(n, shiftFactor)
 * --------------------------------------------------------------------------
 * Returns the value of n, shifted right by shiftFactor.
 * ----------------------------------------------------------------------- *)

PROCEDURE shr ( n, shiftFactor : CARDINAL ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function reqBits(n)
 * --------------------------------------------------------------------------
 * Returns the minimum number of bits required to represent n.
 * ----------------------------------------------------------------------- *)

PROCEDURE reqBits ( n : CARDINAL ) : CARDINAL;


(* --------------------------------------------------------------------------
 * function MSB(n)
 * --------------------------------------------------------------------------
 * Returns TRUE if the most significant bit of n is set, else FALSE.
 * ----------------------------------------------------------------------- *)

PROCEDURE MSB ( n : CARDINAL ) : BOOLEAN;


(* --------------------------------------------------------------------------
 * procedure SetMSB(n)
 * --------------------------------------------------------------------------
 * Sets the most significant bit of n.
 * ----------------------------------------------------------------------- *)

PROCEDURE SetMSB ( VAR n : CARDINAL );


(* --------------------------------------------------------------------------
 * procedure ClearMSB(n)
 * --------------------------------------------------------------------------
 * Clears the most significant bit of n.
 * ----------------------------------------------------------------------- *)

PROCEDURE ClearMSB ( VAR n : CARDINAL );


(* --------------------------------------------------------------------------
 * procedure ClearHighestNBits(value, n)
 * --------------------------------------------------------------------------
 * Clears bits [MSB..MSB-n] of value.
 * ----------------------------------------------------------------------- *)

PROCEDURE ClearHighestNBits ( VAR value : CARDINAL; n : CARDINAL );


END CardMath.