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.