\manpage {real} {} {Real Numbers} 
 
\definition

An instance $x$ of the data type $real$ is an algebraic real number.
There are many ways to construct a $real$:
either by conversion from $double$, $integer$ or $rational$
or by applying one of the arithmetic operators $+, -, *, /$ or $\sqrt{} $ to
$real$ numbers.
One may test the sign of a $real$ number or compare two $real$ numbers by
any of the comparison relations $=, \neq, < , \leq, >$ and $\geq$.
The outcome of such a test is {\em exact}.
There is also a non--standard version of the sign function: the call
$x.sign(integer\ q)$ computes the sign of $x$ under the precondition
that $|x|\leq 2^{-q}$ implies $x = 0$.
This version of the sign function allows the user to assist the data type in the
computation of the sign of $x$, cf. the example below.

One can ask for $double$ approximations of a real number $x$.
The calls $x.todouble()$ and $x.get\_double\_error()$ return $double$s $xnum$ and
$xerr$ such that $|xnum - x |\leq  |xnum |* xerr$.
Note that $xerr = \infty$ is possible.
There are also several functions to compute more accurate approximations of
$real$s.
The call $x.get\_precision()$ returns an $integer$ $xerr$ such that the internal
approximation $x\_num$ satisfies $|xnum - x |\leq 2^{-xerr}$.
The user may set a bound on $xerr$.
More precisely, after the call $x.improve(integer\ q)$ the data type guarantees
$xerr \leq 2^{-q}$.

 
\creation x

 
\create { }
   {
introduces a variable \var\ of type $real$ and initializes it to zero.
 }
 
 
\create {(double\ y)}
   {
introduces a variable \var\ of type $real$ and initializes it to the 
value of $y$.
 }
 
 
\create {(int\ n)}
   {
introduces a variable \var\ of type $real$ and initializes it to the 
value of $n$.
 }
 
 
\create {(integer\ a)}
   {
introduces a variable \var\ of type $real$ and initializes it to the 
value of $a$.
 }
 
 
\create {(rational\ q)}
   {
introduces a variable \var\ of type $real$ and initializes it to the 
value of $q$
 }
 
 
\operations 1.5 5
 

The arithmetic operations $+,\ -,\ *,\ /,\ +=,\
-=,\ *=,\ /=,\ -$(unary), the comparison operations $<,\ <=,\ >,\ 
>=,\ ==,\ !=$ and the stream operations all are available.

 
\op  real sqrt {( real)}
           {  squareroot operation.
 }
 
 
\op  int sign {()}
           {  returns $-1$ if (the exact value of) \var\ $< 0$, $1$ if \var\
   $> 0$, and $0$ if \var\ $= 0$.
 }
 
 
\op  int sign {( integer\ a)}
           {  as above. Precondition: if $|\mbox{\var} |\leq 2^{-a}$
   then $\mbox{\var} = 0$.
 }
 
 
\op  void improve {( integer\ a)}
           {  (re-)computes the approximation of \var\ such that its final quality
    is bounded by $a$, i.e., \var.$get\_precision() \geq a$ after the
    call \var.$improve(a)$.
 }
 
 
\op  void compute\_in {(long\ k)}
           {  (re-)computes the approximation of \var; each numerical operation
   is carried out with $k$ binary places.
 }
 
 
\op  void compute\_up\_to {(long\ k)}
           {  (re-)computes an approximation of \var\ such that the error of the
    approximation lies in the $k$-th binary place.
 }
 
 
\op  double todouble {()}
           {  returns the current double approximation of \var.
 }
 
 
\op  double get\_double\_error {()}
           {  returns the quality of the current double approximation of \var,
    i.e., $|x- x.todouble() |\leq
    x.get\_double\_error() *  |x.todouble() |$.
 }
 
 
\op  integer get\_precision {()}
           {  returns the quality of the current internal approximation $\var.num$
   of \var, i.e., $|x - x.num |\leq 2^{-x.get\_precision()}$.\\
 }
 
 

\smallskip
{\bf Non-member functions}
\smallskip 
 
\func  real fabs {(real\&\ x)}
           {  absolute value of x.
 }
 
 
\func  real sq {( real\ x)}
           {  square of x.
 }
 
 
\func  real hypot {( real\ x, \  real\ y)}
           {  euclidean distance of vector (x,y) to the origin.
 }
 
 
\func  real powi {( real\ x, int\ n)}
           {  n-th power of x.
 }
 
 
\implementation

A \name\ is represented by the expression which defines it and a $double$
approximation $\hat{x}$ together with a relative error bound
$\epsilon_{x}$.
The arithmetic operators $+, -, *, /, \sqrt{}$ take constant time.
When the sign of a \name\ number needs to be determined, the data type first
computes a number $q$, if not already given as an argument to $sign$, such that
$|\mbox{\var} |\leq  q$ implies $x = 0$.
The bound $q$ is computed as described in \cite{Mignotte:Buch}.
The data type then computes an internal approximation $xnum$ for \var\ with
error bound $xerr \leq q$.
The sign of $xnum$ is then returned as the sign of \var.

Two shortcuts are used to speed up the computation of the sign.
Firstly, if the $double$ approximation already suffices to determine the sign,
then no further approximation is computed at all.
Secondly, the internal approximation is first computed only with small
precision.
The precision is then doubled until either the sign can be decided (i.e.,
if $xerr < |xnum |$) or the full precision $q$ is reached.\\

 
\example
Examples can be found in  \cite{BMS:ESA}.

 
