HELP RATIO                                      Robert Duncan, July 1990

Rational numbers.


    CONTENTS - (Use <ENTER> g to access required sections)

 -- The Ratio Module
 -- The Ratio Type
 -- Functions on Ratios


-- The Ratio Module ---------------------------------------------------

signature Ratio
structure Ratio : Ratio
    The structure -Ratio- is an autoloadable library module defining the
    type  of  rational  numbers.  It  is  described  by  the   following
    signature:

        signature Ratio = sig

            eqtype ratio

            exception Ratio

            val ratio       : int * int -> ratio
            val unratio     : ratio -> int * int

            val numerator   : ratio -> int
            val denominator : ratio -> int

            val zero        : ratio
            val one         : ratio

            val floor       : ratio -> int
            val round       : ratio -> int
            val intof       : ratio -> int
            val fracof      : ratio -> ratio
            val real        : ratio -> real

            val ~           : ratio -> ratio
            val +           : ratio * ratio -> ratio
            val -           : ratio * ratio -> ratio
            val *           : ratio * ratio -> ratio
            val /           : ratio * ratio -> ratio

            val abs         : ratio -> ratio
            val sign        : ratio -> ratio

            val <           : ratio * ratio -> bool
            val <=          : ratio * ratio -> bool
            val >           : ratio * ratio -> bool
            val >=          : ratio * ratio -> bool

            val max         : ratio -> ratio -> ratio
            val min         : ratio -> ratio -> ratio

        end


-- The Ratio Type -----------------------------------------------------

eqtype ratio
    The type of rational numbers.  Conceptually, a rational number  is a
    pair of integers: the numerator and denominator. In fact, the  ratio
    construction  function  -ratio-  normalises  the  representation  by
    dividing through  the numerator  and denominator  by their  greatest
    common divisor. Thus there is a unique representation for any  ratio
    value. Furthermore, whenever the denominator  of a ratio reduces  to
    1, the number is mapped onto its integer equivalent, so there is  no
    storage overhead involved in manipulating integer values as  ratios.
    There is  no limit  on  the size  of a  ratio,  but a  ratio  with a
    denominator of 0 is invalid.


-- Functions on Ratios ------------------------------------------------

Many of  the variable  names in  this  module shadow  the names  of  the
standard numeric operations,  so you  should be careful  of opening  the
structure at top level.


exception Ratio
val ratio (n : int, m : int) : ratio
val unratio (r : ratio) : int * int
    Convert between  ratios  and  integer pairs.  The  function  -ratio-
    returns a rational  number with numerator  -n- and denominator  -m-;
    the exception  -Ratio-  is  raised  if -m-  is  zero.  The  function
    -unratio- decomposes  a ratio  into  its numerator  and  denominator
    parts.

    The function

        ratio o unratio

    is the identity function on ratios, but

        unratio o ratio

    is not an identity function  because of the normalisation  performed
    by the -ratio- constructor (see above).


val numerator (r : ratio) : int
val denominator (r : ratio) : int
    Return the numerator and denominator parts of the ratio -r-.


val zero : ratio
val one : ratio
    Useful constants:

        val zero = ratio(0, 1)
        val one  = ratio(1, 1)


val floor (r : ratio) : int
    Returns the largest integer not greater than the ratio -r-.


val round (r : ratio) : int
    Rounds the ratio -r- to an integer.


val intof (r : ratio) : int
    Truncates the ratio -r- to an integer.


val fracof (r : ratio) : ratio
    Returns the fractional part of the ratio -r-.


val real (r : ratio) : real
    Returns the  real  value  equal  to the  ratio  -r-.  The  exception
    -Overflow- is raised if the result is out of range.


val ~ (r : ratio) : ratio
val (r1 : ratio) + (r2 : ratio) : ratio
val (r1 : ratio) - (r2 : ratio) : ratio
val (r1 : ratio) * (r2 : ratio) : ratio
val (r1 : ratio) / (r2 : ratio) : ratio
    Standard arithmetic operators  on rational numbers.  As there is  no
    limit to the size of a  ratio these operations cannot overflow,  but
    the exception -Div- will be raised on an attempt to divide by zero.


val abs (r : ratio) : ratio
    Returns the absolute value of the ratio -r-.


val sign (r : ratio) : ratio
    Returns the sign of the ratio -r-: 1 for positive, 0 for zero and ~1
    for negative.


val (r1 : ratio) <  (r2 : ratio) : bool
val (r1 : ratio) <= (r2 : ratio) : bool
val (r1 : ratio) >  (r2 : ratio) : bool
val (r1 : ratio) >= (r2 : ratio) : bool
    Standard ordering relations on rational numbers.


val max (r1 : ratio) (r2 : ratio) : ratio
    Returns the greater of the ratios -r1- and -r2-.


val min (r1 : ratio) (r2 : ratio) : ratio
    Returns the lesser of the ratios -r1- and -r2-.


--- C.all/pml/help/ratio
--- Copyright University of Sussex 1991. All rights reserved. ----------