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

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.