| 1 |
This module wraps the MPFR library functions. |
| 2 |
|
| 3 |
The MPFR library is a C library for multiple-precision floating-point |
| 4 |
computations with exact rounding (also called correct rounding). It |
| 5 |
is based on the GMP multiple-precision C library. |
| 6 |
|
| 7 |
The main goal of MPFR is to provide a library for multiple-precision |
| 8 |
floating-point computation which is both efficient and has a |
| 9 |
well-defined semantics. It copies the good ideas from the |
| 10 |
ANSI/IEEE-754 standard for double-precision floating-point |
| 11 |
arithmetic (53-bit mantissa). |
| 12 |
|
| 13 |
It also offers a wide range of trig, log, and other functions, and |
| 14 |
constants. |
| 15 |
|
| 16 |
MPFR, like GMP, is free. It is distributed under the |
| 17 |
GNU Lesser General Public License (GNU Lesser GPL). |
| 18 |
|
| 19 |
Because this module wraps the MPFR functions, it requires that both |
| 20 |
the GMP C library and the MPFR C library have been installed. |
| 21 |
|
| 22 |
For the GMP library see: |
| 23 |
https://gmplib.org |
| 24 |
|
| 25 |
For the MPFR library see: |
| 26 |
https://www.mpfr.org |
| 27 |
|
| 28 |
Minimum required version of gmp is gmp-4.2.0. |
| 29 |
Minimum required version of mpfr is mpfr-3.0.0. |
| 30 |
You'll get errors if you try to build Math::MPFR against an |
| 31 |
insufficiently recent version of the mpfr library. |
| 32 |
Some features of Math::MPFR require later versions of the gmp and mpfr |
| 33 |
libraries. If the versions are not sufficiently recent, then those |
| 34 |
features will not be available. |
| 35 |
|
| 36 |
To build this module you need perl 5.6.0 or later. I'm not sure of all |
| 37 |
the requirements to get it to build with earlier versions of perl, but |
| 38 |
it's definite that the XS code relating to operator overloading will |
| 39 |
not compile with perl versions prior to 5.6. |
| 40 |
|
| 41 |
Build in the usual way: |
| 42 |
|
| 43 |
perl Makefile.PL |
| 44 |
make |
| 45 |
make test |
| 46 |
make install |
| 47 |
make realclean (must be run before re-building.) |
| 48 |
|
| 49 |
When building this module, the GMP and MPFR libraries will need to be |
| 50 |
accessible. If those files are in a location where your compiler does |
| 51 |
not find them by default, then instead of running 'perl Makefile.PL', |
| 52 |
you'll need to run: |
| 53 |
|
| 54 |
perl Makefile.pl INC="-I/path/to/gmp_includes -I/path/to/mpfr_includes" |
| 55 |
LIBS="-L/path/to/mpfr_lib -lmpfr -L/path/to/gmp_lib -lgmp" |
| 56 |
|
| 57 |
Other commandline args you may want to provide to 'perl Makefile.PL' are |
| 58 |
D64=1 (for _Decimal64 support), D128=1 (for _Decimal128 support) and |
| 59 |
F128=1 (for __float128 support). |
| 60 |
See the Decimal64/128 and Float128 sections (below). |
| 61 |
There are also some commandline args that provide some debugging of nvtoa() and doubletoa(). |
| 62 |
See the Debug section below. |
| 63 |
|
| 64 |
======== |
| 65 |
Checklib |
| 66 |
======== |
| 67 |
|
| 68 |
During the running of the Makefile.PL a check is run to ensure that the |
| 69 |
gmp and mpfr libraries can be found when needed. |
| 70 |
This check can be skipped by: |
| 71 |
a) providing CHECK=0 as a Makefile.PL commmand line argument |
| 72 |
or |
| 73 |
b) by uncommenting the line (about line 19) that begins with: |
| 74 |
#$checklib = 0; |
| 75 |
|
| 76 |
================================== |
| 77 |
64-bit-int and long double support |
| 78 |
================================== |
| 79 |
|
| 80 |
If your perl's Config reports that 'ivsize' is greater than or |
| 81 |
equal to 8 && 'ivtype' is not 'long', then Math::MPFR will, by default, |
| 82 |
be built with access to the Rmpfr_*_uj and Rmpfr_*_sj functions. Else, |
| 83 |
access to those functions is, by default, denied. |
| 84 |
|
| 85 |
Similarly, if your perl's Config reports that 'nvsize' is greater than |
| 86 |
8 then Math::MPFR will be built with access to the Rmpfr_*_ld functions. |
| 87 |
|
| 88 |
I am contactable by email at sisyphus at(@) cpan dot (.) org. |
| 89 |
|
| 90 |
=================================== |
| 91 |
Decimal64 and Decimal128 conversion |
| 92 |
=================================== |
| 93 |
|
| 94 |
The functions Rmpfr_set_DECIMAL64 and Rmpfr_get_DECIMAL64 allow |
| 95 |
conversion between Math::Decimal64 (_Decimal64) and Math::MPFR (mpfr_t) |
| 96 |
objects. |
| 97 |
For this feature to be available you firstly need a compiler that has |
| 98 |
the _Decimal64 data type. |
| 99 |
You'll also need to have a recent version of the mpfr library that has |
| 100 |
been built with _Decimal64 support (ie that was configured with |
| 101 |
'--enable-decimal-float'). |
| 102 |
|
| 103 |
This should all be detected and enabled automatically whenever these |
| 104 |
conditions are met. |
| 105 |
|
| 106 |
To utilise mpfr's _Decimal64 functionality you also need to install |
| 107 |
Math::Decimal64. |
| 108 |
|
| 109 |
If you wish you can avoid _Decimal64 support by providing D64=0 as an |
| 110 |
argument to the Makefile.PL - ie run 'perl Makefile.PL D64=0'; |
| 111 |
You can ensure _Decimal64 support by providing the argument D64=1. |
| 112 |
|
| 113 |
Note that forcing 'D64=1' will not work unless the conditions |
| 114 |
mentioned earlier in this section are met. |
| 115 |
|
| 116 |
The above holds true also for the Math::Decimal128 and the _Decimal128 |
| 117 |
type. Just replace all occurrences of "64" with "128". |
| 118 |
|
| 119 |
========================================================= |
| 120 |
Conversion between Math::Float128 and Math::MPFR objects |
| 121 |
========================================================= |
| 122 |
|
| 123 |
If 'perl -V:nvtype' reports __float128, see also the section |
| 124 |
'Conversion between __float128 NV and Math::MPFR objects', below. |
| 125 |
This section deals only with conversion between Math::Float128 and |
| 126 |
Math::MPFR objects - and if your nvtype is __float128 there's |
| 127 |
probably nothing to be gained by calling on Math::Float128. |
| 128 |
|
| 129 |
The functions Rmpfr_set_FLOAT128 and Rmpfr_get_FLOAT128 allow |
| 130 |
conversion between Math::Float128 (__float128) and Math::MPFR (mpfr_t) |
| 131 |
objects. |
| 132 |
For this feature to be available you firstly need a compiler that has |
| 133 |
the __float128 data type. |
| 134 |
You'll also need to have a recent version (4.0.0 or later) of the mpfr |
| 135 |
library that has been built with __float128 support (ie that was |
| 136 |
configured with'--enable-float128'). |
| 137 |
|
| 138 |
This should all be detected and enabled automatically whenever these |
| 139 |
conditions are met. |
| 140 |
|
| 141 |
To utilise mpfr's __float128 functionality in this way you also need |
| 142 |
to install Math::Float128. |
| 143 |
|
| 144 |
If you wish you can avoid Math::Float128 support by providing F128=0 |
| 145 |
as an argument to the Makefile.PL - ie run 'perl Makefile.PL F128=0'; |
| 146 |
You can ensure Math::Float128 support by providing the argument F128=1. |
| 147 |
|
| 148 |
You can aternatively override the automated procedure by |
| 149 |
uncommenting one of a number of lines of code near the start of the |
| 150 |
Makefile.PL. (The comments in the Makefile.PL are a clear statement |
| 151 |
of what's required for this.) |
| 152 |
|
| 153 |
Note that forcing inclusion of Math::Float128 support will not work |
| 154 |
unless the conditions mentioned earlier in this section are met. |
| 155 |
|
| 156 |
========================================================== |
| 157 |
Conversion between Math::LongDouble and Math::MPFR objects |
| 158 |
========================================================== |
| 159 |
|
| 160 |
There are 2 functions provided for conversion between Math::LongDouble |
| 161 |
and Math::MPFR objects: |
| 162 |
|
| 163 |
Rmpfr_set_LD (assign the value of a Math::LongDouble object to a |
| 164 |
Math::MPFR object) |
| 165 |
Rmpfr_get_LD (assign the value of a Math::MPFR object to a |
| 166 |
Math::Long Double object) |
| 167 |
|
| 168 |
If your perl's nvtype is long double, just use Rmpfr_set_ld and |
| 169 |
Rmpfr_get_ld instead. |
| 170 |
Math::LongDouble provides 'long double' support for perls whose |
| 171 |
nvtype is other than 'long double'. |
| 172 |
|
| 173 |
======================================================= |
| 174 |
Conversion between __float128 NV and Math::MPFR objects |
| 175 |
======================================================= |
| 176 |
|
| 177 |
To determine your nvtype, run 'perl -V:nvtype'. |
| 178 |
As of perl-5.21.4 it is possible to build perl with an nvtype of |
| 179 |
__float128. This is achieved by specifying -Dusequadmath as a |
| 180 |
Configure arg .... but, it will not work for all architectures |
| 181 |
and compilers. |
| 182 |
|
| 183 |
If $Config{nvtype} specifies '__float128' && if your mpfr library |
| 184 |
(need 4.0.0 or later) was built with --enable-float128 then you |
| 185 |
can pass your __float128 NV values to and from Math::MPFR using |
| 186 |
the Rmpfr_set_float128() and Rmpfr_get_float128() functions. |
| 187 |
And the overloaded operations will also accept the __float128 NV |
| 188 |
arguments as one would want. |
| 189 |
|
| 190 |
This should all be detected and enabled automatically whenever these |
| 191 |
conditions are met. |
| 192 |
NOTE: Even if the mpfr library was not built with __float128 support |
| 193 |
and the conditions are therefore not met, you can still pass |
| 194 |
and receive __float128 values to/from Math::MPFR by instead |
| 195 |
using the functions Rmpfr_get_NV and Rmpfr_set_NV - but that |
| 196 |
happens only if your nvtype is __float128. |
| 197 |
|
| 198 |
If you wish you can avoid __float128 support by providing F128=0 as |
| 199 |
an argument to the Makefile.PL - ie run 'perl Makefile.PL F128=0'; |
| 200 |
You can ensure __float128 support by providing the argument F128=1. |
| 201 |
|
| 202 |
Note that forcing inclusion of __float128 support will not work |
| 203 |
unless the conditions mentioned earlier in this section are met. |
| 204 |
|
| 205 |
===== |
| 206 |
Debug |
| 207 |
===== |
| 208 |
|
| 209 |
If the Makefile.PL is given an argument that matches /NVTOA_DEBUG/i |
| 210 |
then intermediate values in nvtoa() will be printed to STDERR. |
| 211 |
In general, this will produce unwelcome clutter, but the option to |
| 212 |
build Math::MPFR with -DNVTOA_DEBUG is there, if it's ever useful. |
| 213 |
|
| 214 |
If the Makefile.PL is given an argument that matches /DTOA_ASSERT/i |
| 215 |
then some assertion checks are run at various points in doubletoa(). |
| 216 |
If the assertion fails, then the program croaks with the relevant |
| 217 |
diagnostic message. |
| 218 |
|
| 219 |
When doubletoa() fails to determine the value of $nv, and falls |
| 220 |
back to returning sprintf("%.16e", $nv), then the default |
| 221 |
behaviour is to increase $Math::MPFR::doubletoa_fallback by 1. |
| 222 |
If you wish to ignore such events, simply provide the Makefie.PL |
| 223 |
with the argument FB=0 . |
| 224 |
See the doubletoa() documentation in MPFR.pod. |
| 225 |
|
| 226 |
=============================== |
| 227 |
MS WINDOWS (Visual Studio 2019) |
| 228 |
=============================== |
| 229 |
|
| 230 |
I don't know how to build the gmp and mpfr libraries using Visual Studio |
| 231 |
2019, so when building this module with Visual Studio 2019 I build |
| 232 |
against gmp and mpfr libraries that were built using MinGW-w64. |
| 233 |
|
| 234 |
Building with Visual Studio 2019 against *dynamic* gmp/mpfr libraries |
| 235 |
that were built using a MinGW-w64 compiler is not recommended, as strange |
| 236 |
results can then arise when calling mpfr functions that take a FILE* |
| 237 |
argument. |
| 238 |
|
| 239 |
If building with Visual Studio 2019 against static gmp/mpfr libs that were |
| 240 |
built using a MinGW-w64 compiler I first make a copy of the gmp and mpfr |
| 241 |
libraries (libgmp.a and libmpfr.a) along with copies of the following |
| 242 |
MinGW-w64 library files: |
| 243 |
libgcc.a |
| 244 |
libgcc_s.a |
| 245 |
libmingwex.a |
| 246 |
libmingw32.a |
| 247 |
|
| 248 |
For each of the 6 copied files, I leave the filename unchanged (though the |
| 249 |
"lib" at the begining of the name is optional), and change the file |
| 250 |
extension to ".lib". |
| 251 |
In making those copies, I've left them in the same directory as the |
| 252 |
original, but I assume (untested) that the copies could be moved to any |
| 253 |
location of your choice. |
| 254 |
|
| 255 |
Then build this module by cd'ing to the top level Math::MPFR source folder |
| 256 |
and running: |
| 257 |
|
| 258 |
perl Makefile.PL CHECK=0 INC="-IC:/path/to/gmp_header" LIBS="-LC:/path/to/libgcc -lgcc -LC:/path/to/libgcc_s -lgcc_s -LC:/path/to/standard_libs -lmingwex -lmingw32 -LC:/path/to/libgmp -lmpfr -lgmp" |
| 259 |
nmake test |
| 260 |
nmake install |
| 261 |
|
| 262 |
NOTES |
| 263 |
The given example "perl Makefile.PL ..." command assumes: |
| 264 |
1) that both mpfr.h and gmp.h are in C:/path/to/gmp_header; |
| 265 |
2) that libmingwex and libmingw32 libraries are in the same location; |
| 266 |
3) that libmpfr.lib and libgmp.lib are in C:/path/to/libgmp. |
| 267 |
Modify as necessary. |
| 268 |
|