package prbnmcn-basic-structures

  1. Overview
  2. Docs
package prbnmcn-basic-structures
Legend:
Library
Module
Module type
Parameter
Class
Class type
include module type of struct include Q end

Types

type t = Q.t = {
  1. num : Z.t;
    (*

    Numerator.

    *)
  2. 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 integers, / separated integer ratios (with optional sign), decimal point and scientific notations 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 = Q.kind =
  1. | ZERO
    (*

    0

    *)
  2. | INF
    (*

    infinity, i.e. 1/0

    *)
  3. | MINF
    (*

    minus infinity, i.e. -1/0

    *)
  4. | UNDEF
    (*

    undefined, i.e., 0/0

    *)
  5. | 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. Unlike compare, this follows IEEE semantics: 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. leq undef undef returns false.

val geq : t -> t -> bool

Greater than or equal. leq undef undef returns false.

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, base-10, /-separated rational.

val to_float : t -> float

Converts to a floating-point number, using the current floating-point rounding mode. With the default rounding mode, the result is the floating-point number closest to the given rational; ties break to even mantissa.

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 : Stdlib.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 : Stdlib.Buffer.t -> t -> unit

To be used as %a format printer in Printf.bprintf.

val pp_print : Stdlib.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.

val (=) : t -> t -> bool

Same as equal.

  • since 1.8
val (<) : t -> t -> bool

Same as lt.

  • since 1.8
val (>) : t -> t -> bool

Same as gt.

  • since 1.8
val (<=) : t -> t -> bool

Same as leq.

  • since 1.8
val (>=) : t -> t -> bool

Same as geq.

  • since 1.8
val (<>) : t -> t -> bool

a <> b is equivalent to not (equal a b).

  • since 1.8
val hash : 'a -> int
val pp : Stdlib.Format.formatter -> t -> unit
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct