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

\markright{\BF{xdouble}}
\begin{lidia_man}

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

\NAME
\BF{xdouble} \DOTFILL   double+double precision arithmetic
\label{xdouble_class}

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

\ABSTRACT
\BF{xdouble} is a class for (double+double) arithmetic over
\MATH{\R}. It supports mainly the same functions as 
the built-in type double according to IEEE (see \cite{IEE87}). 
Several conversion routines have been added.

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

\DESCRIPTION
An xdouble \MATH{x} is represented by two doubles \MATH{lo, hi},
where \MATH{|lo| < |hi|}. The addition of \MATH{lo} and \MATH{hi} 
will give you the value of \MATH{x}

\begin{center}
\MATH{x = lo + hi}
\end{center}

A complete description of the representation,
the algorithms for the basic operations (\TT{+, -, *, /})
and the more sophisticated algorithms 
of \BF{xdouble} can be found in the book of T.J. Decker,
S. Linnaimaa and D. Priest (see \cite{TDek},\cite{Linna},\cite{DPri}).

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

\CONS
\fcode{ct}{xdouble}{}
{ 
initializes with 0.}


\fcode{ct}{xdouble}{double \MATH{hi}, double \MATH{lo=0.0}}
{
initializes with \MATH{hi+lo}. }


\fcode{ct}{xdouble}{const xdouble \&}
{
initializes with an xdouble.}

\fcode{ct}{xdouble}{char *}
{
string conversion.}


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

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

\ASGN
Let \MATH{a} be of type \BF{xdouble}. The operator \TT{=} is
overloaded for xdouble and any other built-in type. 
The follwing routines convert an xdouble into a built-in type and return the converted 
element.  No overflow check is done. \\

\fcode{double}{double\_xdbl}{const xdouble \&}
{ convert an \BF{xdouble} to a \BF{double}.}

\fcode{unsigned long}{ulong\_xdbl}{const xdouble \&}
{ convert an \BF{xdouble} to an \BF{unsigned long}.}

\fcode{long}{long\_xdbl}{const xdouble \&}
{ convert an \BF{xdouble} to a \BF{long}.}

\fcode{unsigned int}{uint\_xdbl}{const xdouble \&}
{ convert an \BF{xdouble} to an \BF{unsigned int}.}

\fcode{int}{int\_xdbl}{const xdouble \&}
{ convert an \BF{xdouble} to an \BF{int}.}

\fcode{unsigned short}{ushort\_xdbl}{const xdouble \&}
{ convert an \BF{xdouble} to an \BF{unsigned short}.}

\fcode{short}{short\_xdbl}{const xdouble \&}
{ convert an \BF{xdouble} to a \BF{short}.}

\fcode{unsigned char}{uchar\_xdbl}{const xdouble \&}
{ convert an \BF{xdouble} to an \BF{unsigned char}.}

\fcode{char}{char\_xdbl}{const xdouble \&}
{ convert an \BF{xdouble} to a \BF{char}.}

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

\ACCS
Let \MATH{a} be of type \BF{xdouble}.


\fcode{double}{a.h}{}
{
returns the hi part of \MATH{a}.}

\fcode{double}{a.l}{}
{
returns the lo part of \MATH{a}.}


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

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

\begin{center}
\TT{(unary) -}\\
\TT{(binary) +, -, *, /}\\
\TT{(binary with assignment) +=, -=, *=, /=}
\end{center}

\fcode{xdouble}{sqr}{const xdouble \& a}
{
returns \MATH{a^2}.}

\fcode{xdouble}{cub}{const xdouble \& a}
{
returns \MATH{a^3}.}

\fcode{xdouble}{sqrt}{const xdouble \& a}{
returns \MATH{\SQRT{a}}, where \MATH{a >= 0}. If \MATH{a < 0},
the \TT{lidia\_error\_handler} will be invoked.}

\fcode{xdouble}{pow}{const xdouble \& a\k const xdouble \& b}
{
returns \MATH{a^b}, where \MATH{b > 0}. If \MATH{b \LEQ 0},
the \TT{lidia\_error\_handler} will be invoked.}

\fcode{xdouble}{powint}{const xdouble \& a\k long b}
{
returns \MATH{a^b}, where \MATH{b > 0}. If \MATH{b \LEQ 0},
the \TT{lidia\_error\_handler} will be invoked.}


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

\COMP
Let \MATH{a} be of type \BF{xdouble}.  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 C.




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

\BASIC
Let \MATH{a} be of type \BF{xdouble}.


\fcode{int}{sign}{const xdouble \& a}
{
returns 1 if \MATH{a > 0}, \MATH{0} if \MATH{a = 0} and \MATH{1}
otherwise.}


\fcode{xdouble}{fabs}{const xdouble \& a}
{
returns \MATH{|a|}.}

\fcode{xdouble}{ceil}{const xdouble \& a}
{
returns \MATH{\LCEIL a \RCEIL}, i.e. \MATH{c} is the smallest
integer which is greater than or equal to \MATH{a}.}

\fcode{xdouble}{floor}{const xdouble \& a}
{
returns \MATH{\LFLOOR a \RFLOOR}, i.e. \MATH{c} is the largest
integer which is less than or equal to \MATH{a}.}

\fcode{xdouble}{rint}{const xdouble \& a}
{
returns \MATH{\LFLOOR a + 1/2 \RFLOOR}, i.e. \MATH{c} is the
nearest integer to \MATH{a}.}

\fcode{xdouble}{trunc}{const xdouble \& a}
{
returns \MATH{\TT{sign}(a) * \LFLOOR |a| \RFLOOR}.}

\fcode{xdouble}{exp}{const xdouble \& a}
{
returns \MATH{e^a}.}

\fcode{xdouble}{log}{const xdouble \& a}
{
returns \MATH{log(a)} (natural logarithm to base \MATH{e} =
2.718...), where \MATH{a > 0}. If \MATH{a \LEQ 0} the
\TT{lidia\_error\_handler} will be invoked.}

\fcode{xdouble}{log10}{const xdouble \& a}
{
returns \MATH{log(a)} (logarithm to base 10), 
where \MATH{a > 0}. If \MATH{a \LEQ 0} the
\TT{lidia\_error\_handler} will be invoked.}


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

\STITLE{(Inverse) Trigonometric Functions}
Note that the arguments of the trigonometrical functions are
supposed to be given as radiants.


\fcode{xdouble}{sin}{const xdouble \& a}
{
returns \MATH{\TT{sin}(a)}.}


\fcode{xdouble}{cos}{const xdouble \& a}
{
returns \MATH{\TT{cos}(a)}.}

\fcode{xdouble}{tan}{const xdouble \& a}
{
returns \MATH{\TT{tan}(a)} if \MATH{a \NEQ (2k+1)\;\pi/2}, \MATH{k \IN \Z}.
Otherwise the \TT{lidia\_error\_handler} will be invoked.}

\fcode{xdouble}{asin}{const xdouble \& a}
{
returns \MATH{\TT{arcsin}(a)} if \MATH{a \IN [ -1, 1 ]}.
Otherwise the \TT{lidia\_error\_handler} will be invoked.}

\fcode{xdouble}{acos}{const xdouble \& a}
{
returns \MATH{\TT{arccos}(a)} if \MATH{a \IN [ -1, 1 ]}.
Otherwise the \TT{lidia\_error\_handler} will be invoked.}

\fcode{xdouble}{atan}{const xdouble \& a}
{
returns \MATH{\TT{arctan}(a)}.}

\fcode{xdouble}{atan2}{const xdouble \& a\k const xdouble \& b}
{
returns \MATH{\TT{arctan}(a / b)} in the range of \MATH{[ -\pi, \pi [},
i.e. atan2(a, b) calculates the argument (respectively phase) of \MATH{a, b}.}


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

\STITLE{(Inverse) Hyperbolic Trigonometric Functions}
\fcode{xdouble}{sinh}{const xdouble \& a}
{
returns \MATH{\TT{sinh}(a)}.}


\fcode{xdouble}{cosh}{const xdouble \& a}
{
returns \MATH{\TT{cosh}(a)}.}


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

\STITLE{Constants}
Useful Constants. \\

\fcode{xdouble}{Log2}{}{
\MATH{ln~2 = 0.6931471805599453094172321214581765680755} }
\fcode{xdouble}{Log10}{}{
\MATH{ln~10 = 2.302585092994045684017991454684364207601} }
\fcode{xdouble}{Pi}{}{
\MATH{ \pi = 3.1415926535897932384626433832795028841972} }
\fcode{xdouble}{TwoPi}{}{
\MATH{ 2 \pi = 6.2831853071795864769252867665590057683943} }
\fcode{xdouble}{Pion2}{}{
\MATH{\FRAC{\pi}{2} = 1.5707963267948966192313216916397514420985} }
\fcode{xdouble}{Pion4}{}{
\MATH{\FRAC{\pi}{4} = 0.7853981633974483096156608458198757210493} }

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

\IO
Let \MATH{a} be of type \BF{xdouble}.

\BF{istream} operator \TT{>>} and \BF{ostream} operator \TT{<<}
are overloaded. 

\fcode{void}{string\_to\_xdouble}{char * s\k xdouble \& a}
{
converts the string \MATH{s} to an \BF{xdouble} \MATH{a}.}


\fcode{void}{xdouble\_to\_string}{const xdouble \& a\k char * s}
{
converts the \BF{xdouble} \MATH{a} to a string \MATH{s}.
The number of characters allocated for \MATH{s} must be at least
42 to carry the digits of \MATH{a}. }

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

\SEEALSO
\BF{bigfloat}.

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

\NOTES
Optimization may cause problems with an FPU having more than 64 bits.


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

\EXAMPLES
The  following  program  calculates an approximate to the number \MATH{\SQRT{\pi}} .


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

 int main()
 {
   xdouble x = sqrt(xdouble::Pi);
   cout << "\n sqrt(pi) = " << x << flush;
   return 0;
 }

\end{verbatim}

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

\AUTHOR
Original Code by Keith Briggs. \\
Ported to {\LiDIA} by Werner Backes and Thomas Papanikolaou


\end{lidia_man}

