%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  bigrational.tex      LiDIA documentation
%%
%%  This file contains the documentation of the class bigrational
%%  
%%  Copyright (c) 1995 by the LiDIA Group 
%%
%%  Authors: Thomas Papanikolaou
%%  

\begin{lidia_man}
\markright{\BF{bigrational}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME
\BF{bigrational}   \DOTFILL  multiprecision  rational  arithmetic

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT
\BF{bigrational}  is  a  class  for doing multiprecision rational
arithmetic.  It   supports  for  example  arithmetic  operations,
comparisons, and exponentiation.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION
A \BF{bigrational} consists of a pair of two \BF{bigints}
\MATH{(num, den)}, the nu\-me\-ra\-tor \BF{num} and the
denominator \BF{den}. The \BF{bigrational} \MATH{(num, den)}
represents the rational number \MATH{\FRAC{num}{den}}. The
numerator num and the denominator den of a
\BF{bigrational} are always coprime; the denominator den
is positive. Arithmetic is done using the algorithms described in \cite {knuth}. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\CONS
\fcode{ct}{bigrational}{}
{
numerator \MATH{= 0}, denominator \MATH{= 1}.}

\fcode{ct}{bigrational}{int \MATH{i}}
{
numerator \MATH{= i}, denominator \MATH{= 1}.}

\fcode{ct}{bigrational}{long \MATH{l}}
{
numerator \MATH{= l}, denominator \MATH{= 1}.}

\fcode{ct}{bigrational}{unsigned long \MATH{ul}}
{
numerator \MATH{= ul}, denominator \MATH{= 1}.}

\fcode{ct}{bigrational}{double \MATH{d}}
{
numerator \MATH{= (bigint)d}, denominator \MATH{= 1}.}

\fcode{ct}{bigrational}{const bigint \& \MATH{b}}
{
numerator \MATH{= (bigint)b}, denominator \MATH{= 1}.}

\fcode{ct}{bigrational}{const bigint \& \MATH{n}\k const bigint \& \MATH{d}}
{
numerator \MATH{= n}, denominator \MATH{= d}.}

\fcode{ct}{bigrational}{const bigrational \& \MATH{b}}
{
numerator \MATH{= numerator(b)}, denominator \MATH{= denominator(d)}.}

\fcode{dt}{\SIM bigrational}{}
{
deletes the bigrational object.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\TYPE
Before assigning a \BF{bigrational} to a \BF{bigint} it
is often useful to check whether precision is lost, i.e. if the 
denominator is not equal to one.\vspace*{1ex} 


\fcode{bool}{is\_bigint}{const bigrational \& a}
{
returns \TRUE\ if the denominator of \MATH{a} is one, \FALSE,
otherwise.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ASGN
Let \MATH{a} be of type \BF{bigrational}.  The operator \TT{=} is
overloaded. For efficiency reasons, the following functions are
also implemented:\vspace*{1ex}

\fcode{void}{a.assign\_zero}{}
{
\MATH{a = 0}.}


\fcode{void}{a.assign\_one}{}
{
\MATH{a = 1}.}


\fcode{void}{a.assign}{const bigrational \& b}
{
\MATH{a = b}.}


\fcode{void}{a.assign}{const bigint \&n, const bigint \&d}
{
 \MATH{a = \FRAC{n}{d}}.}


\fcode{double}{dbl}{const bigrational \& a}
{
returns the value of \MATH{a} as a double approximation.}


\cfcode{bool}{a.intify}{int \& i}
{
performs the assignment \MATH{i = \LFLOOR a.num /
a.den\RFLOOR} provided that this assignment can be
done without overflow. In that case the function returns \FALSE,
otherwise it returns \TRUE\ and lets the value of \MATH{i}
unchanged.}


\cfcode{bool}{a.longify}{long \& i}
{
performs the assignment \MATH{i = \LFLOOR a.num /
a.den\RFLOOR} provided that this assignment can be
done without overflow. In that case the function returns \FALSE,
otherwise it returns \TRUE\ and lets the value of \MATH{i}
unchanged.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ACCS
\cfcode{bigint}{a.numerator}{}
{
returns the numerator of \MATH{a}.}


\fcode{bigint}{numerator}{const bigrational \& a}
{
returns the numerator of \MATH{a}.}


\cfcode{bigint}{a.denominator}{}
{
returns the denominator of \MATH{a}.}


\fcode{bigint}{denominator}{const bigrational \& a}
{
returns the denominator of \MATH{a}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ARTH
The following operators are overloaded and can be used in exactly
the same way as in the programming language C:

\begin{center}
\TT{(unary) -, ++, --}\\
\TT{(binary) +, -, *, /,  >>, <<}\\
\TT{(bin.~with assignment) +=, -=, *=, /=, >>=, <<=}
\end{center}

To avoid copying all operators also exist as functions.\vspace*{1ex}


\fcode{void}{add}{bigrational \& c\k const bigrational \& a\k const bigrational \& b}
{
\MATH{c = a + b}.}


\fcode{void}{add}{bigrational \& c\k const bigrational \& a\k long i}
{
\MATH{c = a + i}.}


\fcode{void}{add}{bigrational \& c\k long i\k const bigrational \& a}
{
\MATH{c = i + a}.}


\fcode{void}{subtract}{bigrational \& c\k const bigrational \& a\k const bigrational \& b}
{
\MATH{c = a - b}.}


\fcode{void}{subtract}{bigrational \& c\k const bigrational \& a\k long i}
{
\MATH{c = a - i}.}


\fcode{void}{subtract}{bigrational \& c\k long i\k const bigrational \& a}
{
\MATH{c = i - a}.}


\fcode{void}{multiply}{bigrational \& c\k const bigrational \& a\k const bigrational \& b}
{
\MATH{c = a * b}.}


\fcode{void}{multiply}{bigrational \& c\k const bigrational \& a\k long i}
{
\MATH{c = a * i}.}


\fcode{void}{multiply}{bigrational \& c\k long i\k const bigrational \& a}
{
\MATH{c = i * a}.}


\fcode{void}{divide}{bigrational \& c\k const bigrational \& a\k const bigrational \& b}
{
\MATH{c = a / b}, if \MATH{b \NEQ 0}. Otherwise the \TT{lidia\_error\_handler}
will be invoked.}


\fcode{void}{divide}{bigrational \& c\k const bigrational \& a\k long i}
{
\MATH{c = a / i}, if \MATH{i \NEQ 0}. Otherwise the \TT{lidia\_error\_handler} 
will be invoked.}


\fcode{void}{divide}{bigrational \& c\k long i\k const bigrational \& a}
{
\MATH{c = i / a}, if \MATH{a \NEQ 0}. Otherwise the \TT{lidia\_error\_handler} 
will be invoked.}


\fcode{void}{a.negate}{}
{
\MATH{a = -a}.}


\fcode{void}{negate}{bigrational \& a\k const bigrational \& b}
{
\MATH{a = -b}.}


\fcode{void}{a.multiply\_by\_2}{}
{
\MATH{a = 2 * a} (done by shifting).}


\fcode{void}{a.divide\_by\_2}{}
{
\MATH{a = a / 2} (done by shifting).}


\fcode{void}{a.invert}{}
{
\MATH{a = 1 / a}, if \MATH{a \NEQ 0}. Otherwise the \TT{lidia\_error\_handler} 
will be invoked.}


\fcode{void}{invert}{bigrational \& a\k const bigrational \& b}
{
\MATH{a = 1 / b}, if \MATH{b \NEQ 0}. Otherwise the \TT{lidia\_error\_handler} 
will be invoked.}


\fcode{bigrational}{inverse}{const bigrational \& a}
{
returns \MATH{1 / a}, if \MATH{a \NEQ 0}. Otherwise the \TT{lidia\_error\_handler} 
will be invoked.}


\fcode{void}{inc}{bigrational \& a}
{
\MATH{a = a + 1}.}


\fcode{void}{dec}{bigrational \& a}
{
\MATH{a = a - 1}.}


\fcode{void}{square}{bigrational \& c\k const bigrational \& a}
{
\MATH{c = a^2}.}


\fcode{void}{power}{bigrational \& c\k const bigrational \& a\k const bigint \& i}
{
\MATH{c = a^i}.}


\fcode{void}{power}{bigrational \& c\k const bigrational \& a\k long i}
{
\MATH{c = a^i}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SHFT
\fcode{void}{shift\_left}{bigrational \& c\k const bigrational \&  a\k long i}
{
\MATH{c = a * 2^i}.}


\fcode{void}{shift\_right}{bigrational \& c\k const bigrational \&  a\k long i}
{
\MATH{c = a / 2^i}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\COMP 
The binary operators \TT{==}, \TT{!=}, \TT{>=}, \TT{<=}, \TT{>},
\TT{<} and the unary operator \TT{!} (comparison with zero) are
overloaded and can be used in exactly the same way as in the
programming language C. Let \MATH{a} be of
type \BF{bigrational}.\vspace*{1ex}



\cfcode{bool}{a.is\_positive}{}
{
returns \TRUE\ if \MATH{a > 0}, \FALSE\ otherwise.}


\cfcode{bool}{a.is\_negative}{}
{
returns \TRUE\ if \MATH{a < 0}, \FALSE\ otherwise.}


\cfcode{bool}{a.is\_zero}{}
{
returns \TRUE\ if \MATH{a = 0}, \FALSE\ otherwise.}


\cfcode{bool}{a.is\_ge\_zero}{}
{
returns \TRUE\ if \MATH{a \GEQ 0}, \FALSE\ otherwise.}


\cfcode{bool}{a.is\_gt\_zero}{}
{
returns \TRUE\ if \MATH{a > 0}, \FALSE\ otherwise.}


\cfcode{bool}{a.is\_le\_zero}{}
{
returns \TRUE\ if \MATH{a \LEQ 0}, \FALSE\ otherwise.}


\cfcode{bool}{a.is\_lt\_zero}{}
{
returns \TRUE\ if \MATH{a < 0}, \FALSE\ otherwise.}


\cfcode{bool}{a.is\_one}{}
{
returns \TRUE\ if \MATH{a = 1}, \FALSE\ otherwise.}


\cfcode{int}{a.compare}{const bigrational \& b}
{
returns \TT{sign}\MATH{(a - b)}.}


\cfcode{int}{a.abs\_compare}{const bigrational \& b}
{
returns \TT{sign}\MATH{(|a| - |b|)}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\BASIC
\cfcode{int}{a.sign}{}
{
returns -1, 0, 1 if \MATH{a <, =, > 0} respectively.}


\fcode{bigrational}{abs}{const bigrational \& a}
{
returns \MATH{|a|}.}


\fcode{bigint}{ceiling}{const bigrational \& a}
{
returns the least integer \MATH{b} with \MATH{b \GEQ a}.}


\fcode{bigint}{floor}{const bigrational \& a}
{
returns the greatest integer \MATH{b} with \MATH{b \LEQ a}.}


\fcode{bigint}{round}{const bigrational \& a}
{
returns the nearest integer to \MATH{a}.}


\fcode{bigint}{truncate}{const bigrational \& a}
{
returns the integer part \MATH{b} of \MATH{a}, i.e.
\MATH{b = \FRAC{ \LFLOOR a \RFLOOR + \LCEIL a \RCEIL -1}{2}}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\IO
Let \MATH{a} be of type \BF{bigrational}. \BF{istream}
operator \TT{>>} and \BF{ostream} operator \TT{<<} are overloaded.
Furthermore, you can use the following member functions for
writing to and reading from a file in binary or ASCII format,
respectively. Input and output of a \BF{bigrational} have the
following format:

\centerline{num / den}

(without blanks).  Note that you have to manage by yourself that 
successive \BF{bigrational}s have to be separated by blanks. 


\fcode{int}{string\_to\_bigrational}{char *s\k const char *t\k bigrational \& a}
{
converts the strings \MATH{s} and \MATH{t} to \BF{bigint}s \MATH{s', t'} and sets
\MATH{a = s'/t'}, returns the total number of
converted characters.}


\fcode{int}{bigrational\_to\_string}{const bigrational \& a\k char *s\k char *t}
{
converts the denominator of \MATH{a} to string \MATH{s}, the numerator
of \MATH{a} to string \MATH{t} and returns the number of used characters.}


\fcode{int}{a.read\_from\_file}{FILE *fp}
{
reads \MATH{a} from \MATH{f\!p} using fread.}


\fcode{int}{a.write\_to\_file}{FILE *fp}
{
writes \MATH{a} to \MATH{f\!p} using fwrite.}


\fcode{int}{a.scan\_from\_file}{FILE *fp}
{
scans \MATH{a} from \MATH{f\!p} using fscanf.}


\fcode{int}{a.print\_to\_file}{FILE *fp}
{
prints \MATH{a} to \MATH{f\!p} using fprintf.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
\BF{bigint}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\EXAMPLES
\begin{verbatim}
 #include <LiDIA/bigrational.h>

 int main()
 {

    bigrational a, b, c;

    cout << "Please enter a : "; cin >> a ; 

    cout << "Please enter b : "; cin >> b ;

    cout << "\n";

    c = a + b;

    cout << "a + b = " << c << "\n";

 } 

\end{verbatim}

For further reference please refer to\\
\TT{LiDIA/src/simple\_classes/bigrational\_appl.c}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
Volker M\"uller, Thomas Papanikolaou


\end{lidia_man}


























































