   Copyright (C)  2000    Daniel A. Atkinson
   Copyright (C)  2004    Ivano Primi  <ivano.primi@tin.it>    

   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
   notice and this notice are preserved.

******************************************************************************

                   HIGH PRECISION ARITHMETIC (abbr. HPA) LIBRARY

                                    Summary

                 The extended precision library implements a high
                 precision floating point arithmetic together with a
                 comprehensive set of support functions. The general
                 areas covered by these functions include:

                     o Extended Precision Arithmetic
                     o Extended Precision Math Library
                     o Applications of High Precision Computation

                 The math library support includes evaluation of
                 trigonometric, inverse trigonometric, hyperbolic,
                 logarithm, and exponential functions at the same
                 precision as the floating point math itself.
		 Maybe in future HPA will support also high precision complex 
                 arithmetic and will include an Extended Precision 
		 Complex Math Library.


** History **

The HPA library comes from a branch of the source code of the CCMath library,
which is a work by Daniel A. Atkinson.
Actually, I just took the source code in the 'xarm' section
of the CCMath library, I modified a little part of it to make
it work with recent versions (3.x) of GCC even when the code is compiled
with the optimization flags on and I added a few functions
(xtoflt(), flttox(), print_xpr(), asprint_xpr(), xtoa() and bxprint())
which I find useful. Moreover, I discovered and patched a potential
buffer overflow. At end, I added the makefiles to compile the library
on a GNU/Linux(R) or Unix(R) system.
But the hard work was done by Daniel A. Atkinson, which was also very
kind to release the code of the CCMath Library under GNU Lesser 
General Public License. This made possible that I could modify and 
redistribute it under the same terms. So, a really big THANKS to Daniel !!
Unfortunately, I was not able to contact him personally, 
so if you know him and you can say him "Thanks" from me, please do it !


** License **

The HPA (abbreviation of HIGH PRECISION ARITHMETIC Library) is
copyrighted by Ivano Primi (ivprimi@libero.it) and
Daniel A. Atkinson (the author of the original code). 
As it is for the source code of the CCMath Library, the source code
of the HPA library is released under the terms of the GNU Lesser General 
Public License, as published by the Free Software Foundation; 
either version 2.1 of the License, or (at your option) any later version.

The HPA library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

You can contact me by paper mail writing to the next address

	Ivano Primi
	via Colle Cannetacce 50/A
	C.A.P. 00038 - Valmontone (ROMA)
	Italy                                                         .

If you prefer the electronic mail you can write to the address

	ivprimi@libero.it                                             .


** Installation instructions            **

Please read the file INSTALL to know how building and installing the
HPA library.


** Using HPA library in a C/C++ program **

The complete list of the functions which compose the HPA library
is in the header file "xpre.h".
So, to use them you have to add this line to the begin
of your source files:

	#include <xpre.h>

The HPA library defines its own numeric type, called 'xpr'.
The size of a variable of 'xpr' type is given by  (2 x XDIM + 2) bytes,
where  XDIM is a constant defined in the file "xpre.h".
The HPA library provides several routines acting on 'xpr'
arguments. Between them there are functions allowing for
conversions from and to the types 'double', 'float' and 'string'
(i.e. char*). 
I will not describe here what are the routines supplied by the library
and what they do. In fact, you can find their descriptions and
other useful information in the manual of the HPA library 
(see the file doc/manual).
Now I will only concentrate on how compiling and building a program
which makes use of the HPA library.
Together with the HPA library is installed a little and simple
program called 'hpaconf'. 
You can use it to quickly compile and build your programs.
If PREFIX is the root directory chosen to install the HPA library
(the default value for PREFIX is /usr/local), then 'hpaconf'
should be installed inside PREFIX/bin. You can know where 'hpaconf'
is by launching the command

	which hpaconf

on your console or terminal.
In the following I will suppose that the directory PREFIX/bin
is included in your PATH environment variable (This is surely
true if the command 'which' was able to find 'hpaconf').  

'hpaconf' recognizes four options:

	-v      to return the version of HPA installed on your system

	-c      to return the flags needed to compile using HPA

	-l	to return the flags to link  against HPA

	-n	to print a newline at the end of the output.

The option -v cannot be used together with the options -c and -l,
but it may be used together with -n:

	hpaconf -v 	prints onto the standard output (console) the version
			of HPA installed on your system

	hpaconf -v -n

	or

	hpaconf -n -v   (order does not matter) behaves exactly the same
			but also prints a newline to force the following
			output to be written on the next line.


The options -c and -l cannot be used together with -v, but they can be used
both at the same time and they can be accompanied by the option -n. Of course,
order does not matter.

	hpaconf -c	prints onto the standard output the flags
			needed to compile using HPA

	hpaconf -l	prints onto the standard output the flags
			needed to link  against HPA

	hpaconf -c -l	

	or

	hpaconf -l -c	prints both the flags to compile using HPA
			and the flags to link  against HPA.

If the -n option is added, then the information printed is followed
by a newline. Why 'hpaconf' is so useful ?
I will give you an example. To compile the source
file 'example.c' you should tell the compiler where looking for
the header files of HPA and for the library itself; to do this
it is sufficient to specify the related paths with the options
-I and -L (at least if you are using GCC/G++ as C/C++ compiler).
However, in this way you are constrained to remember the path
where HPA was installed and this is quite uncomfortable.
With 'hpaconf' you can simply use the command

	cc -c $(hpaconf -c) example.c 

or

	cc -c `hpaconf -c` example.c	.

to compile the file 'example.c' and obtain the object file 'example.o'.
Actually, the previous one is the right form of the command 
for a shell sh compatible, like ash, bash or ksh. 
If you are using another shell, probably the
right form to obtain the expansion of the command 'hpaconf -c'
will be another one (see the manual of your preferred shell for this).
On GNU/Linux bash is the default shell for all users. If this is
not true for your machine, then ask your system administrator :) 
Once you have obtained the object file 'example.o', you may do the linkage
by using the command (for a shell sh-compatible):

	cc example.o $(hpaconf -l) -o example

or

	cc example.o `hpaconf -l` -o example	.

If you want, you may also compile and build at the same time by using
(Do i need to repeat the next one is the right form only for
 a shell sh-compatible ?)

	cc example.c $(hpaconf -c -l) -o example

or

	cc example.c `hpaconf -c -l` -o example	.


which will compile 'example.c' and build the program 'example'.
Naturally, compiling and building at the same time is only
possible when the source code of your program is all contained in one
file.
