Previous  Up  Next

Module Q

module Q: sig .. end
Rationals.

This modules builds arbitrary precision rationals on top of arbitrary integers from module Z.

This file is part of the Zarith library http://forge.ocamlcore.org/projects/zarith . It is distributed under LGPL 2 licensing, with static linking exception. See the LICENSE file included in the distribution.

Copyright (c) 2010-2011 Antoine Miné, Abstraction project. Abstraction is part of the LIENS (Laboratoire d'Informatique de l'ENS), a joint laboratory by: CNRS (Centre national de la recherche scientifique, France), ENS (École normale supérieure, Paris, France), INRIA Rocquencourt (Institut national de recherche en informatique, France).


Types


type t = {
   num : Z.t; (*
Numerator.
*)
   den : Z.t; (*
Denominator, >= 0
*)
}
A rational is represented as a pair numerator/denominator, reduced to have a non-negative denominator and no common factor. This form is canonical (enabling polymorphic equality and hashing). The representation allows three special numbers: inf (1/0), -inf (-1/0) and undef (0/0).

Construction


val make : Z.t -> Z.t -> t
make num den constructs a new rational equal to num/den. It takes care of putting the rational in canonical form.
val zero : t
val one : t
val minus_one : t
0, 1, -1.
val inf : t
1/0.
val minus_inf : t
-1/0.
val undef : t
0/0.
val of_bigint : Z.t -> t
val of_int : int -> t
val of_int32 : int32 -> t
val of_int64 : int64 -> t
val of_nativeint : nativeint -> t
Conversions from various integer types.
val of_ints : int -> int -> t
Conversion from an int numerator and an int denominator.
val of_float : float -> t
Conversion from a float. The conversion is exact, and maps NaN to undef.
val of_string : string -> t
Converts a string to a rational. Plain decimals, and / separated decimal ratios (with optional sign) are understood. Additionally, the special inf, -inf, and undef are recognized (they can also be typeset respectively as 1/0, -1/0, 0/0).

Inspection


val num : t -> Z.t
Get the numerator.
val den : t -> Z.t
Get the denominator.

Testing


type kind =
| ZERO (*
0
*)
| INF (*
infinity, i.e. 1/0
*)
| MINF (*
minus infinity, i.e. -1/0
*)
| UNDEF (*
undefined, i.e., 0/0
*)
| NZERO (*
well-defined, non-infinity, non-zero number
*)
Rationals can be categorized into different kinds, depending mainly on whether the numerator and/or denominator is null.
val classify : t -> kind
Determines the kind of a rational.
val is_real : t -> bool
Whether the argument is non-infinity and non-undefined.
val sign : t -> int
Returns 1 if the argument is positive (including inf), -1 if it is negative (including -inf), and 0 if it is null or undefined.
val compare : t -> t -> int
compare x y compares x to y and returns 1 if x is strictly greater that y, -1 if it is strictly smaller, and 0 if they are equal. This is a total ordering. Infinities are ordered in the natural way, while undefined is considered the smallest of all: undef = undef < -inf <= -inf < x < inf <= inf. This is consistent with OCaml's handling of floating-point infinities and NaN.

OCaml's polymorphic comparison will NOT return a result consistent with the ordering of rationals.

val equal : t -> t -> bool
Equality testing. This is consistent with compare; in particular, undef=undef.
val min : t -> t -> t
Returns the smallest of its arguments.
val max : t -> t -> t
Returns the largest of its arguments.
val leq : t -> t -> bool
Less than or equal.
val geq : t -> t -> bool
Greater than or equal.
val lt : t -> t -> bool
Less than (not equal).
val gt : t -> t -> bool
Greater than (not equal).

Conversions


val to_bigint : t -> Z.t
val to_int : t -> int
val to_int32 : t -> int32
val to_int64 : t -> int64
val to_nativeint : t -> nativeint
Convert to integer by truncation. Raises a Divide_by_zero if the argument is an infinity or undefined. Raises a Z.Overflow if the result does not fit in the destination type.
val to_string : t -> string
Converts to human-readable, decimal, /-separated rational.

Arithmetic operations



In all operations, the result is undef if one argument is undef. Other operations can return undef: such as inf-inf, inf*0, 0/0.
val neg : t -> t
Negation.
val abs : t -> t
Absolute value.
val add : t -> t -> t
Addition.
val sub : t -> t -> t
Subtraction. We have sub x y = add x (neg y).
val mul : t -> t -> t
Multiplication.
val inv : t -> t
Inverse. Note that inv 0 is defined, and equals inf.
val div : t -> t -> t
Division. We have div x y = mul x (inv y), and inv x = div one x.
val mul_2exp : t -> int -> t
mul_2exp x n multiplies x by 2 to the power of n.
val div_2exp : t -> int -> t
div_2exp x n divides x by 2 to the power of n.

Printing


val print : t -> unit
Prints the argument on the standard output.
val output : Pervasives.out_channel -> t -> unit
Prints the argument on the specified channel. Also intended to be used as %a format printer in Printf.printf.
val sprint : unit -> t -> string
To be used as %a format printer in Printf.sprintf.
val bprint : Buffer.t -> t -> unit
To be used as %a format printer in Printf.bprintf.
val pp_print : Format.formatter -> t -> unit
Prints the argument on the specified formatter. Also intended to be used as %a format printer in Format.printf.

Prefix and infix operators



Classic prefix and infix int operators are redefined on t.
val (~-) : t -> t
Negation neg.
val (~+) : t -> t
Identity.
val (+) : t -> t -> t
Addition add.
val (-) : t -> t -> t
Subtraction sub.
val ( * ) : t -> t -> t
Multiplication mul.
val (/) : t -> t -> t
Division div.
val (lsl) : t -> int -> t
Multiplication by a power of two mul_2exp.
val (asr) : t -> int -> t
Division by a power of two shift_right.
val (~$) : int -> t
Conversion from int.
val (//) : int -> int -> t
Creates a rational from two ints.
val (~$$) : Z.t -> t
Conversion from Z.t.
val (///) : Z.t -> Z.t -> t
Creates a rational from two Z.t.