# [rational.h] Type: Rational

## contents

#include "standard.h"
#include "integer.h"

## The Type

       [rational] implements the algebraic operations for rationals.
       A rational number is represented by its numerator and denominator.
       NF: gcd(Z,N)=1 /\ N>0

Rational | Abstract rational type

## Basics

       In the following functions the integer and rational operands won't be
       consumed and the resulting integer or rational have to be released.

    Rational Rat_cons(Integer Z, Integer N)
| constructs a rational from numerator 'Z' and denominator 'N'
    Rational Rat_copy(Rational a)
| copies rational 'a'
    void Rat_free(Rational a)
| frees rational 'a'
    Rational Rat_Int_to(Integer a)
| constructs a rational from numerator 'a' ( a/1 )
    Rational Rat_Int_div(Integer a, Integer b)
| divides integer 'a' thru integer 'b' giving a rational
    void Rat_des(Rational r, Integer* z, Integer* n)
| destructs rational 'r' to numerator 'z' and denominator 'n'
    Integer Rat_nom(Rational r)
| copies numerator of rational 'r'
    Integer Rat_den(Rational r)
| copies denominator of rational 'r'
    void showRat(Rational r)
| prints rational 'r' to stdout; for debugging

## Comparison

    c_bool Rat_is0(Rational r)
| r == 0 ?
    int Rat_cmp(Rational a, Rational b)
| a < b ? -1 : a == b ? 0 : 1
    c_bool Rat_eq(Rational a, Rational b)
| a == b ?
    c_bool Rat_ne(Rational a, Rational b)
| a != b ?
    c_bool Rat_lt(Rational a, Rational b)
| a < b ?
    c_bool Rat_le(Rational a, Rational b)
| a <= b ?
    c_bool Rat_gt(Rational a, Rational b)
| a > b ?
    c_bool Rat_ge(Rational a, Rational b)
| a >= b ?

## Arithmetic

    int Rat_sgn(Rational r)
| signum of rational 'r' (0,-1,1)
    Rational Rat_abs(Rational r)
| absolute value |r|
    Rational Rat_neg(Rational r)
| negation -r
    Rational Rat_inv(Rational r)
| inverse 1 / r ( r != 0 )
    Rational Rat_add(Rational a, Rational b)
| addition a + b
    Rational Rat_sub(Rational a, Rational b)
| substraction a - b
    Rational Rat_mlt(Rational a, Rational b)
| multiplication a * b
    Rational Rat_quo(Rational a, Rational b)
| division a / b

## Conversion

Q --> Z

    Integer Rat_floor(Rational r)
| greatest Integer z with z <= r
    Integer Rat_ceiling(Rational r)
| smallest Integer z with z >= r
    Integer Rat_round(Rational r)
| rounding

Q --> Q

    Rational Rat_fix_floor(Rational r, int b, long n)
| Rational(floor(r * b ^ n), b ^n)
    Rational Rat_fix_ceiling(Rational r, int b, long n)
| Rational(ceiling(r * b ^ n), b ^n)
    Rational Rat_fix_round(Rational r, int b, long n)
| Rational(round(r * b ^ n), b ^n)

Q <--> String

    c_string Rat_to_Str(Rational r, int Base, int Digits)
| converts rational 'r' into a string; allocs memory
    Rational Rat_Str_to(c_string s, int Base)
| converts string 's' into a rational; not consuming 's' assuming 'Rat_Str_ok(s,Base)'
    c_bool Rat_s_ok(c_string s, int Base)
| whether string 's' represents a fix point numeral

## Xaron Support

    void Rat_references(Rational x, StdCPtr (*act)(StdCPtr r))
| performs 'act' on all pointer references in rational 'x' ( garbage collection service for xaron )