# The num library: arbitrary-precision rational arithmetic

The `num` library (distributed in `contrib/libnum`) implements exact-precision rational arithmetic. It is built upon the state-of-the-art BigNum arbitrary-precision integer arithmetic package, and therefore achieves very high performance.

The functions provided in this library are fully documented in The CAML Numbers Reference Manual by Valérie Ménissier-Morain, technical report 141, INRIA, july 1992 (available by anonymous FTP from `ftp.inria.fr`, directory `INRIA/publications/RT`, file `RT-0141.ps.Z`). A summary of the functions is given below.

Programs that use the `num` library must be linked in ``custom runtime'' mode, as follows:

            camlc -custom other options nums.zo other files -lnums

For interactive use of the `num` library, run `camllight camlnum`.

Mac:
  This library is not available.

PC:
  This library is available by default in the standard runtime system and in the toplevel system. Programs that use this library can be linked normally, without the `-custom` option.

## `num`: operations on numbers

  Numbers (type `num`) are arbitrary-precision rational numbers, plus the special elements `1/0` (infinity) and `0/0` (undefined).

    type num = Int of int | Big_int of big_int | Ratio of ratio

  The type of numbers.

    value normalize_num : num -> num
    value numerator_num : num -> num
    value denominator_num : num -> num

### Arithmetic operations

    value prefix +/ : num -> num -> num
    value add_num : num -> num -> num

  Addition

    value minus_num : num -> num

  Unary negation.

    value prefix -/ : num -> num -> num
    value sub_num : num -> num -> num

  Subtraction

    value prefix */ : num -> num -> num
    value mult_num : num -> num -> num

  Multiplication

    value square_num : num -> num

  Squaring

    value prefix // : num -> num -> num
    value div_num : num -> num -> num

  Division

    value quo_num : num -> num -> num
    value mod_num : num -> num -> num

  Euclidean division: quotient and remainder

    value prefix **/ : num -> num -> num
    value power_num : num -> num -> num

  Exponentiation

    value is_integer_num : num -> bool

  Test if a number is an integer

    value integer_num : num -> num
    value floor_num : num -> num
    value round_num : num -> num
    value ceiling_num : num -> num

  Approximate a number by an integer. `floor_num n` returns the largest integer smaller or equal to `n`. `ceiling_num n` returns the smallest integer bigger or equal to `n`. `integer_num n` returns the integer closest to `n`. In case of ties, rounds towards zero. `round_num n` returns the integer closest to `n`. In case of ties, rounds off zero.

    value sign_num : num -> int

  Return `-1`, `0` or `1` according to the sign of the argument.

    value prefix =/ : num -> num -> bool
    value prefix </ : num -> num -> bool
    value prefix >/ : num -> num -> bool
    value prefix <=/ : num -> num -> bool
    value prefix >=/ : num -> num -> bool
    value prefix <>/ : num -> num -> bool
    value eq_num : num -> num -> bool
    value lt_num : num -> num -> bool
    value le_num : num -> num -> bool
    value gt_num : num -> num -> bool
    value ge_num : num -> num -> bool

  Usual comparisons between numbers

    value compare_num : num -> num -> int

  Return `-1`, `0` or `1` if the first argument is less than, equal to, or greater than the second argument.

    value max_num : num -> num -> num
    value min_num : num -> num -> num

  Return the greater (resp. the smaller) of the two arguments.

    value abs_num : num -> num

  Absolute value.

    value succ_num: num -> num

  `succ n` is `n+1`

    value pred_num: num -> num

  `pred n` is `n-1`

    value incr_num: num ref -> unit

  `incr r` is `r:=!r+1`, where `r` is a reference to a number.

    value decr_num: num ref -> unit

  `decr r` is `r:=!r-1`, where `r` is a reference to a number.

### Coercions with strings

    value string_of_num : num -> string

  Convert a number to a string, using fractional notation.

    value approx_num_fix : int -> num -> string
    value approx_num_exp : int -> num -> string

  Approximate a number by a decimal. The first argument is the required precision. The second argument is the number to approximate. `approx_fix` uses decimal notation; the first argument is the number of digits after the decimal point. `approx_exp` uses scientific (exponential) notation; the first argument is the number of digits in the mantissa.

    value num_of_string : string -> num

  Convert a string to a number.

### Coercions between numerical types

    value int_of_num : num -> int
    value num_of_int : int -> num
    value nat_of_num : num -> nat__nat
    value num_of_nat : nat__nat -> num
    value num_of_big_int : big_int -> num
    value big_int_of_num : num -> big_int
    value ratio_of_num : num -> ratio
    value num_of_ratio : ratio -> num
    value float_of_num : num -> float
    value num_of_float : float -> num
    value sys_print_num : int -> string -> num -> string -> unit
    value print_num : num -> unit

## `arith_status`: flags that control rational arithmetic

    value arith_status: unit -> unit

  Print the current status of the arithmetic flags.

    value get_error_when_null_denominator : unit -> bool
    value set_error_when_null_denominator : bool -> unit

  Get or set the flag `null_denominator`. When on, attempting to create a rational with a null denominator raises an exception. When off, rationals with null denominators are accepted. Initially: on.

    value get_normalize_ratio : unit -> bool
    value set_normalize_ratio : bool -> unit

  Get or set the flag `normalize_ratio`. When on, rational numbers are normalized after each operation. When off, rational numbers are not normalized until printed. Initially: off.

    value get_normalize_ratio_when_printing : unit -> bool
    value set_normalize_ratio_when_printing : bool -> unit

  Get or set the flag `normalize_ratio_when_printing`. When on, rational numbers are normalized before being printed. When off, rational numbers are printed as is, without normalization. Initially: on.

    value get_approx_printing : unit -> bool
    value set_approx_printing : bool -> unit

  Get or set the flag `approx_printing`. When on, rational numbers are printed as a decimal approximation. When off, rational numbers are printed as a fraction. Initially: off.

    value get_floating_precision : unit -> int
    value set_floating_precision : int -> unit

  Get or set the parameter `floating_precision`. This parameter is the number of digits displayed when `approx_printing` is on. Initially: 12.