ocaml/otherlibs/num/README

The "libnum" library implements exact-precision arithmetic on
big integers and on rationals.

This library is derived from Valerie Menissie-Morain's implementation
of rational arithmetic for Caml V3.1 (INRIA).  Xavier Leroy (INRIA)
did the Caml Light port.  Victor Manuel Gulias Fernandez did the
initial Caml Special Light port.  Pierre Weis did most of the
maintenance and bug fixing.

Initially, the low-level big integer operations were provided by the
BigNum package developed by Bernard Serpette, Jean Vuillemin and
Jean-Claude Herve (INRIA and Digital PRL).  License issues forced us to
replace the BigNum package.  The current implementation of low-level
big integer operations is due to Xavier Leroy.

This library is documented in "The CAML Numbers Reference Manual" by
Valerie Menissier-Morain, technical report 141, INRIA, july 1992,
available at ftp://ftp.inria.fr/INRIA/publication/RT/RT-0141.ps.gz


USAGE:

To use the bignum library from your programs, just do

    ocamlc <options> nums.cma <.cmo and .ml files>
or
    ocamlopt <options> nums.cmxa <.cmx and .ml files>

for the linking phase.

If you'd like to have the bignum functions available at toplevel, do

    ocamlmktop -o ocamltopnum <options> nums.cma <.cmo and .ml files>
    ./ocamltopnum

As an example, try:

        open Num;;
        let rec fact n =
          if n = 0 then Int 1 else mult_num (num_of_int n) (fact(n-1));;
        string_of_num(fact 1000);;


PROCESSOR-SPECIFIC OPTIMIZATIONS:

When compiled with GCC, the low-level primitives use "inline extended asm"
to exploit useful features of the target processor (additions and
subtractions with carry; double-width multiplication, division).
Here are the processors for which such optimizations are available:
  IA32 (x86)       (carry, dwmult, dwdiv, 64-bit ops with SSE2 if available)
  AMD64 (Opteron)  (carry, dwmult, dwdiv)
  PowerPC          (carry, dwmult)
  Alpha            (dwmult)
  SPARC            (carry, dwmult, dwdiv)
  MIPS             (dwmult)