2521 lines
112 KiB
Plaintext
2521 lines
112 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
Math::MPFR - perl interface to the MPFR (floating point) library.
|
|
|
|
=head1 DEPENDENCIES
|
|
|
|
This module needs the MPFR and GMP C libraries. (Install the
|
|
GMP library first as it is a pre-requisite for MPFR.)
|
|
|
|
The GMP library is available from https://gmplib.org
|
|
The MPFR library is available from https://www.mpfr.org/
|
|
|
|
Documentation for current mpfr functions can be found at:
|
|
www.mpfr.org/mpfr-current/mpfr.html#Function-and-Type-Index
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
A bigfloat module utilising the MPFR library. Basically
|
|
this module simply wraps the 'mpfr' floating point functions
|
|
provided by that library.
|
|
Operator overloading is also available.
|
|
The following documentation heavily plagiarises the mpfr
|
|
documentation.
|
|
See also the Math::MPFR test suite for some examples of usage.
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
use Math::MPFR qw(:mpfr);
|
|
|
|
# '@' can be used to separate mantissa from exponent. For bases
|
|
# that are <= 10, 'e' or 'E' can also be used.
|
|
# Use single quotes for string assignment if you're using '@' as
|
|
# the separator. If you must use double quotes, you'll have to
|
|
# escape the '@'.
|
|
|
|
my $str = '.123542@2'; # mantissa = (.)123452
|
|
# exponent = 2
|
|
#Alternatively:
|
|
# my $str = ".123542\@2";
|
|
# or:
|
|
# my $str = '12.3542';
|
|
# or:
|
|
# my $str = '1.23542e1';
|
|
# or:
|
|
# my $str = '1.23542E1';
|
|
|
|
my $base = 10;
|
|
my $rnd = MPFR_RNDZ; # See 'ROUNDING MODE'
|
|
|
|
# Create an Math::MPFR object that holds an initial
|
|
# value of $str (in base $base) and has the default
|
|
# precision. $bn1 is the number. $nok will either be 0
|
|
# indicating that the string was a valid number string, or
|
|
# -1, indicating that the string contained at least one
|
|
# invalid numeric character.
|
|
# See 'COMBINED INITIALISATION AND ASSIGNMENT', below.
|
|
my ($bn1, $nok) = Rmpfr_init_set_str($str, $base, $rnd);
|
|
|
|
# Or use the new() constructor - also documented below
|
|
# in 'COMBINED INITIALISATION AND ASSIGNMENT'.
|
|
# my $bn1 = Math::MPFR->new($str);
|
|
|
|
# Create another Math::MPFR object with precision
|
|
# of 100 bits and an initial value of NaN.
|
|
my $bn2 = Rmpfr_init2(100);
|
|
|
|
# Assign the value -2314.451 to $bn1.
|
|
Rmpfr_set_d($bn2, -2314.451, MPFR_RNDN);
|
|
|
|
# Create another Math::MPFR object that holds
|
|
# an initial value of NaN and has the default precision.
|
|
my $bn3 = Rmpfr_init();
|
|
|
|
# Or using instead the new() constructor:
|
|
# my $bn3 = Math::MPFR->new();
|
|
|
|
# Perform some operations ... see 'FUNCTIONS' below.
|
|
# see 'OPERATOR OVERLOADING' below for docs re
|
|
# operator overloading
|
|
|
|
.
|
|
.
|
|
|
|
# print out the value held by $bn1 (in octal):
|
|
print Rmpfr_get_str($bn1, 8, 0, $rnd), "\n";
|
|
|
|
# print out the value held by $bn1 (in decimal):
|
|
print Rmpfr_get_str($bn1, 10, 0, $rnd), "\n";
|
|
# or just make use of overloading :
|
|
print $bn1, "\n"; # is base 10, and uses 'e' rather than '@'.
|
|
|
|
# print out the value held by $bn1 (in base 16) using the
|
|
# 'TRmpfr_out_str' function. (No newline is printed - unless
|
|
# it's supplied as the optional fifth arg. See the
|
|
# 'TRmpfr_out_str' documentation below.)
|
|
TRmpfr_out_str(*stdout, 16, 0, $bn1, $rnd);
|
|
|
|
=head1 ROUNDING MODE
|
|
|
|
|
|
One of 4 values:
|
|
GMP_RNDN (numeric value = 0): Round to nearest.
|
|
GMP_RNDZ (numeric value = 1): Round towards zero.
|
|
GMP_RNDU (numeric value = 2): Round towards +infinity.
|
|
GMP_RNDD (numeric value = 3): Round towards -infinity.
|
|
|
|
With the release of mpfr-3.0.0, the same rounding values
|
|
are renamed to:
|
|
MPFR_RNDN (numeric value = 0): Round to nearest.
|
|
MPFR_RNDZ (numeric value = 1): Round towards zero.
|
|
MPFR_RNDU (numeric value = 2): Round towards +infinity.
|
|
MPFR_RNDD (numeric value = 3): Round towards -infinity.
|
|
|
|
You can use either the "GMP_*" or the "MPFR_*" renditions.
|
|
|
|
Also available are:
|
|
mpfr-3.0.0 and later:
|
|
MPFR_RNDA (numeric value = 4): Round away from zero.
|
|
mpfr-4.0.0 and later:
|
|
MPFR_RNDF (numeric value = 5): Faithful rounding.
|
|
|
|
These last two rounding modes will cause a fatal error
|
|
if the mpfr library against which Math::MPFR has been
|
|
built is not sufficiently recent.
|
|
|
|
MPFR_RNDF is experimental - the computed value is either
|
|
that corresponding to MPFR_RNDD or that corresponding to
|
|
MPFR_RNDU. In particular when those values are identical,
|
|
i.e., when the result of the corresponding operation is
|
|
exactly representable, that exact result is returned.
|
|
Thus, the computed result can take at most two possible
|
|
values, and in absence of underflow/overflow, the
|
|
corresponding error is strictly less than one ulp (unit in
|
|
the last place) of that result and of the exact result.
|
|
For MPFR_RNDF, the returned value and the inexact flag are
|
|
unspecified, the divide-by-zero flag is as with other
|
|
roundings, and the underflow and overflow flags match what
|
|
would be obtained in the case the computed value is the
|
|
same as with MPFR_RNDD or MPFR_RNDU. The results may not
|
|
be reproducible, and it may not work with all functions.
|
|
Please report bugs.
|
|
|
|
MPFR_RNDN (the 'round to nearest' mode) works as in the
|
|
IEEE P754 standard: in case the number to be rounded
|
|
lies exactly in the middle of two representable
|
|
numbers, it is rounded to the one with the least
|
|
significant bit set to zero. For example, the
|
|
number 5, which is represented by (101) in binary,
|
|
is rounded to (100)=4 with a precision of two bits,
|
|
and not to (110)=6. This rule avoids the "drift"
|
|
phenomenon mentioned by Knuth in volume 2 of
|
|
The Art of Computer Programming (section 4.2.2,
|
|
pages 221-222).
|
|
|
|
Most Math::MPFR functions take as first argument the
|
|
destination variable, as second and following arguments
|
|
the input variables, as last argument a rounding mode,
|
|
and have a return value of type 'int'. If this value
|
|
is zero, it usually means that the value stored in the
|
|
destination variable is the exact result of the
|
|
corresponding mathematical function. If the returned
|
|
value is positive (resp. negative), it usually means
|
|
the value stored in the destination variable is greater
|
|
(resp. lower) than the exact result. For example with
|
|
the 'GMP_RNDU' rounding mode, the returned value is
|
|
usually positive, except when the result is exact, in
|
|
which case it is zero. In the case of an infinite
|
|
result, it is considered as inexact when it was
|
|
obtained by overflow, and exact otherwise. A
|
|
NaN result (Not-a-Number) always corresponds to an
|
|
inexact return value.
|
|
|
|
See also the Rmpfr_round_nearest_away() function in the
|
|
ROUNDING MODE FUNCTIONS section for the mode
|
|
"round to nearest, ties away from zero".
|
|
|
|
=head1 MEMORY MANAGEMENT
|
|
|
|
Objects are created with new() or with the Rmpfr_init*
|
|
functions. All of these functions return an object that has
|
|
been blessed into the package Math::MPFR.
|
|
They will therefore be automatically cleaned up by the
|
|
DESTROY() function whenever they go out of scope.
|
|
|
|
For each Rmpfr_init* function there is a corresponding function
|
|
called Rmpfr_init*_nobless which returns an unblessed object.
|
|
If you create Math::MPFR objects using the '_nobless'
|
|
versions, it will then be up to you to clean up the memory
|
|
associated with these objects by calling Rmpfr_clear($op)
|
|
for each object, or Rmpfr_clears($op1, $op2, ....).
|
|
Alternatively such objects will be cleaned up when the script
|
|
ends.
|
|
Because these objects have not been blessed into the Math::MPFR
|
|
package, the overloaded operators will not work with them.
|
|
|
|
=head1 MIXING GMP OBJECTS WITH MPFR OBJECTS
|
|
|
|
Some of the Math::MPFR functions below take as arguments
|
|
one or more of the GMP types mpz (integer), mpq
|
|
(rational) and mpf (floating point). (Such functions are
|
|
marked as taking mpz/mpq/mpf arguments.)
|
|
For these functions to work you need to have loaded either:
|
|
|
|
1) Math::GMP from CPAN. (This module provides access to mpz
|
|
objects only - NOT mpf and mpq objects.)
|
|
|
|
AND/OR
|
|
|
|
2) Math::GMPz (for mpz types), Math::GMPq (for mpq types)
|
|
and Math::GMPf (for mpf types).
|
|
|
|
You may also be able to use objects from the GMP module
|
|
that ships with the GMP sources. I get occasional
|
|
segfaults when I try to do that, so I've stopped
|
|
recommending it - and don't support the practice.
|
|
|
|
=head1 PASSING __float128 VALUES
|
|
|
|
There are 3 ways to pass __float128 values to/from
|
|
Math::MPFR. Option 1) is the preferred option:
|
|
|
|
1) Build perl (5.21.4 or later) with -Dusequadmath; build the
|
|
mpfr-4.0.0 (or later) library with the configure option
|
|
--enable-float128, and then build Math::MPFR by providing the
|
|
"F128=1" arg to the Makefile.PL (which will define the symbol
|
|
MPFR_WANT_FLOAT128):
|
|
|
|
perl Makefile.PL F128=1
|
|
|
|
Then you can pass your perl's __float128 NV values directly
|
|
to/from Math::MPFR using:
|
|
|
|
Rmpfr_set_float128() or Rmpfr_set_NV() and
|
|
Rmpfr_get_float128() or Rmpfr_get_NV()
|
|
|
|
This will also mean that overloaded operations that receive an
|
|
NV will evaluate that (__float128) NV to its full precision.
|
|
And assigning the NV as Math::MPFR->new($nv) will also work as
|
|
intended.
|
|
|
|
NOTE:
|
|
If you have built perl with -Dusequadmath, but the mpfr
|
|
library was not built with --enable-float128 (or the F128=1
|
|
arg was not given to the Makefile.PL) , then both
|
|
Rmpfr_set_NV() and Rmpfr_get_NV() will still set/get
|
|
__float128 values.
|
|
Also, overloaded operations that receive an NV will still
|
|
evaluate that (__float128) NV to its full precision.
|
|
It's only Rmpfr_set_float128() and Rmpfr_get_float128() that
|
|
will not be available.
|
|
|
|
2) Install Math::Float128, build the mpfr-4.0.0 (or later)
|
|
library with the configure option --enable-float128, and build
|
|
Math::MPFR by providing the "F128=1" arg to the Makefile.pl:
|
|
|
|
perl Makefile.PL F128=1
|
|
|
|
Then you can pass the values of the Math::Float128 objects to
|
|
and from Math::MPFR objects using:
|
|
|
|
Rmpfr_set_FLOAT128() and Rmpfr_get_FLOAT128()
|
|
|
|
3) Convert the __float128 values to a string and pass them to
|
|
and from Math::MPFR using:
|
|
|
|
Rmpfr_set_str() and Rmpfr_get_str()
|
|
|
|
=head1 PASSING _Decimal64 & _Decimal128 VALUES
|
|
|
|
Install Math::Decimal64 and/or Math::Decimal128 and build the mpfr
|
|
library (version 3.1.0 or later for _Decimal64, version 4.1.0 or
|
|
later for _Decimal128) with the --enable-decimal-float option. The
|
|
Math::MPFR build process should detect the _Decimal64/_Decimal128
|
|
availability and include or exclude the support accordingly.
|
|
|
|
If the auto-detection fails to detect the availability, you can
|
|
override it by providing the "D64=1" and/or "D128=1" arg to the
|
|
the Makefile.PL (either of which will define
|
|
MPFR_WANT_DECIMAL_FLOATS):
|
|
|
|
perl Makefile.PL D64=1 D128=1
|
|
|
|
You can then pass _Decimal64/_Decimal128 values between Math::MPFR
|
|
and Math::Decimal64/Math::Decimal128 using:
|
|
|
|
Rmpfr_set_DECIMAL64() and Rmpfr_get_DECIMAL64()
|
|
Rmpfr_set_DECIMAL128() and Rmpfr_get_DECIMAL128()
|
|
|
|
NOTE: It is allowable to pass any or all of "D64=1", "D128=1" and
|
|
"F128=1" args to the Makefile.PL.
|
|
|
|
To force the removal of _Decimal64/Decimal128 support in
|
|
Math::MPFR, simply provide "D64=0" and/or "D128=0" as arguments to
|
|
the Makefile.PL:
|
|
|
|
perl Makefile.PL D64=0 D128=0
|
|
|
|
|
|
=head1 FUNCTIONS
|
|
|
|
These next 3 functions are demonstrated above (in SYNOPSIS):
|
|
$rop = Rmpfr_init();
|
|
$rop = Rmpfr_init2($p);
|
|
$str = Rmpfr_get_str($op, $base, $digits, $rnd); # 1 < $base < 37
|
|
The third argument to Rmpfr_get_str() specifies the number of digits
|
|
required to be output in the mantissa. (Trailing zeroes are removed.)
|
|
If $digits is 0, the number of digits of the mantissa is chosen
|
|
large enough so that re-reading the printed value with the same
|
|
precision, assuming both output and input use rounding to nearest,
|
|
will recover the original value of $op.
|
|
|
|
The following functions are generally wrappers around an mpfr
|
|
function of the same name. eg. Rmpfr_swap() is a wrapper around
|
|
mpfr_swap().
|
|
|
|
"$rop", "$op1", "$op2", etc. are Math::MPFR objects - the
|
|
return value of one of the Rmpfr_init* functions. They are in fact
|
|
references to mpfr structures. The "$op" variables are the operands
|
|
and "$rop" is the variable that stores the result of the operation.
|
|
Generally, $rop, $op1, $op2, etc. can be the same perl variable
|
|
referencing the same mpfr structure, though often they will be
|
|
distinct perl variables referencing distinct mpfr structures.
|
|
Eg something like Rmpfr_add($r1, $r1, $r1, $rnd),
|
|
where $r1 *is* the same reference to the same mpfr structure,
|
|
would add $r1 to itself and store the result in $r1. Alternatively,
|
|
you could (courtesy of operator overloading) simply code it
|
|
as $r1 += $r1 (or even as $r *= 2).
|
|
Otoh, Rmpfr_add($r1, $r2, $r3, $rnd), where each of the arguments
|
|
is a different reference to a different mpfr structure would add
|
|
$r2 to $r3 and store the result in $r1. Alternatively it could be
|
|
coded as $r1 = $r2 + $r3.
|
|
|
|
"$ui" means any integer that will fit into a C 'unsigned long int',
|
|
|
|
"$si" means any integer that will fit into a C 'signed long int'.
|
|
|
|
"$uj" means any integer that will fit into a C 'uintmax_t'. Don't
|
|
use any of these functions unless your perl's UV is at least as big
|
|
as a 'uintmax_t'.
|
|
|
|
"$sj" means any integer that will fit into a C 'intmax_t'. Don't
|
|
use any of these functions unless your perl's IV is at least as big
|
|
as an 'intmax_t'.
|
|
|
|
"$double" is a C double and "$float" is a C float ... but both will
|
|
be represented in Perl as an NV.
|
|
|
|
"$ld" means a long double. Don't use these functions if the precision
|
|
of your Perl's NV is less than the precision of a 'long double'.
|
|
|
|
"$f128" means a __float128. Don't use these functions unless your
|
|
Perl's NV is a __float128 && mpfr has been configured with
|
|
'--enable-float128'. (Note that versions of mpfr prior to 4.0.0
|
|
cannot be configured with '--enable-float128'.)
|
|
|
|
"$bool" means a value (usually a 'signed long int') in which
|
|
the only interest is whether it evaluates as false or true.
|
|
|
|
"$str" simply means a string of symbols that represent a number,
|
|
eg '1234567890987654321234567E7' or 'zsa34760sdfgq123r5@11'.
|
|
Valid bases for MPFR numbers are 2 to 62.
|
|
|
|
"$rnd" is simply one of the 5 rounding mode values (discussed above).
|
|
|
|
"$p" is the (signed int) value for precision.
|
|
|
|
##############
|
|
|
|
ROUNDING MODE FUNCTIONS
|
|
|
|
Rmpfr_set_default_rounding_mode($rnd);
|
|
Sets the default rounding mode to $rnd (where $rnd can be one of
|
|
MPFR_RNDN, MPFR_RNDU, MPFR_RNDZ, MPFR_RNDD and MPFR_RNDA.
|
|
Note that MPFR_RNDA is available only if Math::MPFR has been built
|
|
against mpfr-3.0.0 or later.
|
|
The default rounding mode is to nearest initially (MPFR_RNDN).
|
|
The default rounding mode is the rounding mode that is used in
|
|
in overloaded operations.
|
|
|
|
$si = Rmpfr_get_default_rounding_mode();
|
|
Returns the numeric value (0, 1, 2, 3 or 4) of the
|
|
current default rounding mode. This will initially be 0.
|
|
|
|
$si = Rmpfr_prec_round($rop, $p, $rnd);
|
|
Rounds $rop according to $rnd with precision $p, which may be
|
|
different from that of $rop. If $p is greater or equal to the
|
|
precision of $rop, then new space is allocated for the mantissa,
|
|
and it is filled with zeroes. Otherwise, the mantissa is rounded
|
|
to precision $p with the given direction. In both cases, the
|
|
precision of $rop is changed to $p. The returned value is zero
|
|
when the result is exact, positive when it is greater than the
|
|
original value of $rop, and negative when it is smaller. The
|
|
precision $p can be any integer between RMPFR_PREC_MIN and
|
|
RMPFR_PREC_MAX.
|
|
|
|
$si = Rmpfr_round_nearest_away(\&function, $rop, @input_args);
|
|
This is a perl implementation (and not a wrapping) of
|
|
the mpfr_round_nearest_away macro introduced in
|
|
mpfr-4.0.0. You can use this function so long as
|
|
Math::MPFR has been built against mpfr-3.0.0 or later.
|
|
This rounding is defined in the same way as MPFR_RNDN,
|
|
except in case of tie, where the value away from zero is
|
|
returned.
|
|
The first arg is a reference to the perl subroutine you
|
|
wish to call, and the remaining args are the args that
|
|
the subroutine usually takes (minus the rounding arg).
|
|
For example:
|
|
|
|
$ret = Rmpfr_round_nearest_away(\&Rmpfr_add, $rop,
|
|
$op1, $op2);
|
|
|
|
$ret = Rmpfr_round_nearest_away(\&Rmpfr_strtofr, $rop,
|
|
'1e-200', 10);
|
|
|
|
$ret = Rmpfr_round_nearest_away(\&Rmpfr_prec_round,
|
|
$rop, $prec);
|
|
|
|
The "function" being called must be one that returns the
|
|
ternary int (-ve for "less than", 0 for "exact", and +ve for
|
|
"greater than").
|
|
|
|
Unlike the more efficient rndna(), this function requires that
|
|
Rmpfr_get_emin() is greater than Rmpfr_get_emin_min().
|
|
If you're not concerned about correct rounding (nearest away) of
|
|
the value +/- 0.25 * (2 ** Rmpfr_get_emin()) then you can instead
|
|
use the rndna function (immediately below).
|
|
|
|
|
|
$si = rndna(\&function, $rop, @input_args);
|
|
A more efficient version of the (above) Rmpfr_round_nearest_away
|
|
function. However, it will not correctly deal with the value
|
|
+/- 0.25 * (2 ** Rmpfr_get_emin()).
|
|
Unlike Rmpfr_round_nearest_away(), this function allows that
|
|
Rmpfr_get_emin() == Rmpfr_get_emin_min().
|
|
|
|
##############
|
|
|
|
INITIALIZATION
|
|
|
|
A variable should be initialized once only.
|
|
|
|
First read the section 'MEMORY MANAGEMENT' (above).
|
|
|
|
Rmpfr_set_default_prec($p);
|
|
Set the default precision to be *exactly* $p bits. The
|
|
precision of a variable means the number of bits used to store its
|
|
mantissa. All subsequent calls to 'mpfr_init' will use this
|
|
precision, but previously initialized variables are unaffected.
|
|
This default precision is set to 53 bits initially. The precision
|
|
can be any integer between RMPFR_PREC_MIN and RMPFR_PREC_MAX.
|
|
|
|
$ui = Rmpfr_get_default_prec();
|
|
Returns the default MPFR precision in bits.
|
|
|
|
$rop = Math::MPFR->new();
|
|
$rop = Math::MPFR::new();
|
|
$rop = new Math::MPFR();
|
|
$rop = Rmpfr_init();
|
|
$rop = Rmpfr_init_nobless();
|
|
Initialize $rop, and set its value to NaN. The precision
|
|
of $rop is the default precision, which can be changed
|
|
by a call to 'Rmpfr_set_default_prec'.
|
|
|
|
$rop = Rmpfr_init2($p);
|
|
$rop = Rmpfr_init2_nobless($p);
|
|
Initialize $rop, set its precision to be *exactly* $p bits,
|
|
and set its value to NaN. To change the precision of a
|
|
variable which has already been initialized,
|
|
use 'Rmpfr_set_prec' instead. The precision $p can be
|
|
any integer between RMPFR_PREC_MIN and RMPFR_PREC_MAX.
|
|
|
|
@rops = Rmpfr_inits($how_many);
|
|
@rops = Rmpfr_inits_nobless($how_many);
|
|
Returns an array of $how_many Math::MPFR objects - initialized,
|
|
with a value of NaN, and with default precision.
|
|
(These functions do not wrap mpfr_inits.)
|
|
|
|
@rops = Rmpfr_inits2($p, $how_many);
|
|
@rops = Rmpfr_inits2_nobless($p, $how_many);
|
|
Returns an array of $how_many Math::MPFR objects - initialized,
|
|
with a value of NaN, and with precision of $p.
|
|
(These functions do not wrap mpfr_inits2.)
|
|
|
|
|
|
Rmpfr_set_prec($op, $p);
|
|
Reset the precision of $op to be *exactly* $p bits.
|
|
The previous value stored in $op is lost. The precision
|
|
$p can be any integer between RMPFR_PREC_MIN and
|
|
RMPFR_PREC_MAX. If you want to keep the previous
|
|
value stored in $op, use 'Rmpfr_prec_round' instead.
|
|
|
|
$si = Rmpfr_get_prec($op);
|
|
Return the precision actually used for assignments of $op,
|
|
i.e. the number of bits used to store its mantissa.
|
|
|
|
Rmpfr_set_prec_raw($rop, $p);
|
|
Reset the precision of $rop to be *exactly* $p bits. The only
|
|
difference with 'mpfr_set_prec' is that $p is assumed to be small
|
|
enough so that the mantissa fits into the current allocated
|
|
memory space for $rop. Otherwise an error will occur.
|
|
|
|
$min_prec = Rmpfr_min_prec($op);
|
|
(This function is implemented only when Math::MPFR is built
|
|
against mpfr-3.0.0 or later. The mpfr_min_prec function was
|
|
not present in earlier versions of mpfr.)
|
|
$min_prec is set to the minimal number of bits required to store
|
|
the significand of $op, and 0 for special values, including 0.
|
|
(Warning: the returned value can be less than RMPFR_PREC_MIN.)
|
|
|
|
$minimum_precision = RMPFR_PREC_MIN;
|
|
$maximum_precision = RMPFR_PREC_MAX;
|
|
Returns the minimum/maximum precision for Math::MPFR objects
|
|
allowed by the mpfr library being used.
|
|
|
|
##########
|
|
|
|
ASSIGNMENT
|
|
|
|
$si = Rmpfr_set($rop, $op, $rnd);
|
|
$si = Rmpfr_set_ui($rop, $ui, $rnd);
|
|
$si = Rmpfr_set_si($rop, $si, $rnd);
|
|
$si = Rmpfr_set_sj($rop, $sj, $rnd);
|
|
$si = Rmpfr_set_uj($rop, $uj, $rnd);
|
|
$si = Rmpfr_set_d($rop, $double, $rnd);
|
|
$si = Rmpfr_set_ld($rop, $ld, $rnd); # long double
|
|
$si = Rmpfr_set_NV($rop, $nv, $rnd); # double/long double/__float128,
|
|
# depending upon perl's nvtype.
|
|
$si = Rmpfr_set_LD($rop, $LD, $rnd); # $LD is a Math::LongDouble object
|
|
$si = Rmpfr_set_z($rop, $z, $rnd); # $z is a mpz object.
|
|
$si = Rmpfr_set_q($rop, $q, $rnd); # $q is a mpq object.
|
|
$si = Rmpfr_set_f($rop, $f, $rnd); # $f is a mpf object.
|
|
$si = Rmpfr_set_flt($rop, $float, $rnd); # mpfr-3.0.0 and later only
|
|
$si = Rmpfr_set_float128($rop, $f128, $rnd);# nvtype is __float128
|
|
# && mpfr-4.0.0 or later
|
|
# && mpfr lib built with
|
|
# --enable-float128 &&
|
|
# F128=1 cmd line arg
|
|
# given to Makefile.PL
|
|
$si = Rmpfr_set_DECIMAL64($rop, $D64, $rnd) # mpfr-3.1.0 or later &&
|
|
# mpfr lib built with
|
|
# --enable-decimal-float
|
|
# && D64=1 arg given to
|
|
# Makefile.PL. $D64 is a
|
|
# Math::Decimal64 object
|
|
$si = Rmpfr_set_DECIMAL128($rop, $D128, $rnd) # mpfr-3.1.0 or later &&
|
|
# mpfr lib built with
|
|
# --enable-decimal-float
|
|
# && D128=1 arg given to
|
|
# Makefile.PL. $D128 is a
|
|
# Math::Decimal128 object
|
|
$si = Rmpfr_set_FLOAT128($rop, $F128, $rnd);# mpfr-4.0.0 and later
|
|
# && mpfr lib built with
|
|
# --enable-float128 &&
|
|
# F128=1 cmd line arg
|
|
# given to Makefile.PL.
|
|
# $F128 is a
|
|
# Math::Float128 object.
|
|
Set the value of $rop from 2nd arg, rounded to the precision of
|
|
$rop towards the given direction $rnd. Please note that even a
|
|
'long int' may have to be rounded if the destination precision
|
|
is less than the machine word width. The return value is zero
|
|
when $rop==2nd arg, positive when $rop>2nd arg, and negative when
|
|
$rop<2nd arg. For 'mpfr_set_d', be careful that the input
|
|
number $double may not be exactly representable as a double-precision
|
|
number (this happens for 0.1 for instance), in which case it is
|
|
first rounded by the C compiler to a double-precision number,
|
|
and then only to a mpfr floating-point number.
|
|
|
|
$si = Rmpfr_set_ui_2exp($rop, $ui, $exp, $rnd);
|
|
$si = Rmpfr_set_si_2exp($rop, $si, $exp, $rnd);
|
|
$si = Rmpfr_set_uj_2exp($rop, $sj, $exp, $rnd);
|
|
$si = Rmpfr_set_sj_2exp($rop, $sj, $exp, $rnd);
|
|
$si = Rmpfr_set_z_2exp($rop, $z, $exp, $rnd); # mpfr-3.0.0 & later only
|
|
Set the value of $rop from the 2nd arg multiplied by two to the
|
|
power $exp, rounded towards the given direction $rnd. Note that
|
|
the input 0 is converted to +0. ($z is a GMP mpz object.)
|
|
|
|
$si = Rmpfr_set_str($rop, $str, $base, $rnd);
|
|
Set $rop to the value of $str in base $base (0,2..36 or, if
|
|
Math::MPFR has been built against mpfr-3.0.0 or later, (0,2..62),
|
|
rounded in direction $rnd to the precision of $rop.
|
|
The exponent is read in decimal. This function returns 0 if
|
|
the entire string is a valid number in base $base. otherwise
|
|
it returns -1.
|
|
If -1 is returned:
|
|
1) the non-numeric flag (which was initialised to 0) will be
|
|
incremented. You can query/clear/reset the value of the
|
|
flag with (resp.) nnumflag()/clear_nnum()/set_nnum() - all
|
|
of which are documented below (in "MISCELLANEOUS");
|
|
2) A warning will be emitted if $Math::MPFR::NNW is set to 1
|
|
(default is 0).
|
|
If $base is zero, the base is set according to the following
|
|
rules:
|
|
if the string starts with '0b' or '0B' the base is set to 2;
|
|
if the string starts with '0x' or '0X' the base is set to 16;
|
|
otherwise the base is set to 10.
|
|
The following exponent symbols can be used:
|
|
'@' - can be used for any base;
|
|
'e' or 'E' - can be used only with bases <= 10;
|
|
'p' or 'P' - can be used to introduce binary exponents with
|
|
hexadecimal or binary strings.
|
|
See the MPFR library documentation for more details. See also
|
|
'Rmpfr_inp_str' (below).
|
|
Because of the special significance of the '@' symbol in perl,
|
|
make sure you assign to strings using single quotes, not
|
|
double quotes, when using '@' as the exponent marker. If you
|
|
must use double quotes (which is hard to believe) then you
|
|
need to escape the '@'. ie the following two assignments are
|
|
equivalent:
|
|
Rmpfr_set_str($rop, '.1234@-5', 10, GMP_RNDN);
|
|
Rmpfr_set_str($rop, ".1234\@-5", 10, GMP_RNDN);
|
|
But the following assignment won't do what you want:
|
|
Rmpfr_set_str($rop, ".1234@-5", 10, GMP_RNDN);
|
|
|
|
Rmpfr_strtofr($rop, $str, $base, $rnd);
|
|
Read a floating point number from a string $str in base $base,
|
|
rounded in the direction $rnd. If successful, the result is
|
|
stored in $rop. If $str doesn't start with a valid number then
|
|
$rop is set to zero.
|
|
Parsing follows the standard C 'strtod' function with some
|
|
extensions. Case is ignored. After optional leading whitespace,
|
|
one has a subject sequence consisting of an optional sign ('+' or
|
|
'-'), and either numeric data or special data. The subject
|
|
sequence is defined as the longest initial subsequence of the
|
|
input string, starting with the first non-whitespace character,
|
|
that is of the expected form.
|
|
The form of numeric data is a non-empty sequence of significand
|
|
digits with an optional decimal point, and an optional exponent
|
|
consisting of an exponent prefix followed by an optional sign and
|
|
a non-empty sequence of decimal digits. A significand digit is
|
|
either a decimal digit or a Latin letter (62 possible characters),
|
|
with 'a' = 10, 'b' = 11, ..., 'z' = 36; its value must be strictly
|
|
less than the base. The decimal point can be either the one
|
|
defined by the current locale or the period (the first one is
|
|
accepted for consistency with the C standard and the practice, the
|
|
second one is accepted to allow the programmer to provide MPFR
|
|
numbers from strings in a way that does not depend on the current
|
|
locale). The exponent prefix can be 'e' or 'E' for bases up to
|
|
10, or '@' in any base; it indicates a multiplication by a power
|
|
of the base. In bases 2 and 16, the exponent prefix can also be
|
|
'p' or 'P', in which case it introduces a binary exponent: it
|
|
indicates a multiplication by a power of 2 (there is a difference
|
|
only for base 16). The value of an exponent is always written in
|
|
base 10. In base 2, the significand can start with '0b' or '0B',
|
|
and in base 16, it can start with '0x' or '0X'.
|
|
|
|
If the argument $base is 0, then the base is automatically detected
|
|
as follows. If the significand starts with '0b' or '0B', base 2 is
|
|
assumed. If the significand starts with '0x' or '0X', base 16 is
|
|
assumed. Otherwise base 10 is assumed. Other allowable values for
|
|
$base are 2 to 62.
|
|
|
|
Note: The exponent must contain at least a digit. Otherwise the
|
|
possible exponent prefix and sign are not part of the number
|
|
(which ends with the significand). Similarly, if '0b', '0B', '0x'
|
|
or '0X' is not followed by a binary/hexadecimal digit, then the
|
|
subject sequence stops at the character '0'.
|
|
Special data (for infinities and NaN) can be '@inf@' or
|
|
'@nan@(n-char-sequence)', and if BASE <= 16, it can also be
|
|
'infinity', 'inf', 'nan' or 'nan(n-char-sequence)', all case
|
|
insensitive. A 'n-char-sequence' is a non-empty string containing
|
|
only digits, Latin letters and the underscore (0, 1, 2, ..., 9, a,
|
|
b, ..., z, A, B, ..., Z, _). Note: one has an optional sign for
|
|
all data, even NaN.
|
|
The function returns a usual ternary value.
|
|
|
|
Rmpfr_set_str_binary($rop, $str);
|
|
Removed in Math-MPFR-3.30. Should have been removed long ago.
|
|
Set $rop to the value of the binary number in $str, which has to
|
|
be of the form +/-xxxx.xxxxxxEyy. The exponent is read in decimal,
|
|
but is interpreted as the power of two to be multiplied by the
|
|
mantissa. The mantissa length of $str has to be less or equal to
|
|
the precision of $rop, otherwise an error occurs. If $str starts
|
|
with 'N', it is interpreted as NaN (Not-a-Number); if it starts
|
|
with 'I' after the sign, it is interpreted as infinity, with the
|
|
corresponding sign.
|
|
|
|
Rmpfr_set_inf($rop, $si);
|
|
Rmpfr_set_nan($rop);
|
|
Rmpfr_set_zero($rop, $si); # mpfr-3.0.0 and later only.
|
|
Set the variable $rop to infinity or NaN (Not-a-Number) or zero
|
|
respectively. In 'mpfr_set_inf' and 'mpfr_set_zero', the sign of $rop
|
|
is positive if 2nd arg >= 0. Else the sign is negative.
|
|
|
|
Rmpfr_swap($op1, $op2);
|
|
Swap the values $op1 and $op2 efficiently. Warning: the precisions
|
|
are exchanged too; in case the precisions are different, 'mpfr_swap'
|
|
is thus not equivalent to three 'mpfr_set' calls using a third
|
|
auxiliary variable.
|
|
|
|
################################################
|
|
|
|
COMBINED INITIALIZATION AND ASSIGNMENT
|
|
|
|
NOTE: Do NOT use these functions if $rop has already
|
|
been initialised. Use the Rmpfr_set* functions in the
|
|
section 'ASSIGNMENT' (above).
|
|
|
|
First read the section 'MEMORY MANAGEMENT' (above).
|
|
|
|
$rop = Math::MPFR->new($arg);
|
|
$rop = Math::MPFR::new($arg);
|
|
$rop = new Math::MPFR($arg);
|
|
Returns a Math::MPFR object with the value of $arg, rounded
|
|
in the default rounding direction, with default precision.
|
|
$arg can be either a number (signed integer, unsigned integer,
|
|
signed fraction or unsigned fraction), a string that
|
|
represents a numeric value, or an object (of type Math::GMPf,
|
|
Math::GMPq, Math::GMPz, orMath::GMP) If $arg is a string, an
|
|
optional additional argument that specifies the base of the
|
|
number can be supplied to new(). Legal values for base are 0
|
|
and 2 to 62. If $arg is a string and no additional argument is
|
|
supplied, the base will be deduced.
|
|
See 'Rmpfr_set_str' above for an explanation of how that
|
|
deduction is done.
|
|
|
|
NOTE: If $arg is *both* an NV (floating point value) and PV
|
|
(string), then the value specified by the PV (string) will be
|
|
used. This is probably what you want (less likely so with
|
|
perl-5.18.4 and earlier).
|
|
However, there's no guaranteed way for the new() function to
|
|
correctly tell and it's best to avoid passing such values, or
|
|
to explicitly use the value you want by doing an Rmpfr_init()
|
|
followed by the appropriate 'Rmpfr_set_*' function documented in
|
|
the previous section. Or, if such exists, you could instead call
|
|
the appropriate 'Rmpfr_init_set_*' function documented
|
|
immediately below.
|
|
Note that these functions (below) return a list of 2 values.
|
|
|
|
($rop, $si) = Rmpfr_init_set($op, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_nobless($op, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_ui($ui, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_ui_nobless($ui, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_si($si, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_si_nobless($si, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_d($double, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_d_nobless($double, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_ld($double, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_ld_nobless($double, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_f($f, $rnd); # $f is a mpf object
|
|
($rop, $si) = Rmpfr_init_set_f_nobless($f, $rnd);# $f is a mpf object
|
|
($rop, $si) = Rmpfr_init_set_z($z, $rnd); # $z is a mpz object
|
|
($rop, $si) = Rmpfr_init_set_z_nobless($z, $rnd);# $z is a mpz object
|
|
($rop, $si) = Rmpfr_init_set_q($q, $rnd); # $q is a mpq object
|
|
($rop, $si) = Rmpfr_init_set_q_nobless($q, $rnd);# $q is a mpq object
|
|
Initialize $rop and set its value from the 1st arg, rounded to
|
|
direction $rnd. The precision of $rop will be taken from the
|
|
active default precision, as set by 'Rmpfr_set_default_prec'.
|
|
If $rop = 1st arg, $si is zero. If $rop > 1st arg, $si is positive.
|
|
If $rop < 1st arg, $si is negative.
|
|
|
|
($rop, $si) = Rmpfr_init_set_str($str, $base, $rnd);
|
|
($rop, $si) = Rmpfr_init_set_str_nobless($str, $base, $rnd);
|
|
Initialize $rop and set its value from $str in base $base,
|
|
rounded to direction $rnd. If $str was a valid number, then
|
|
$si will be set to 0. Else it will be set to -1.
|
|
If $si is -1 :
|
|
1) the non-numeric flag (which was initialised to 0) will be
|
|
incremented. You can query/clear/reset the value of the
|
|
flag with (resp.) nnumflag()/clear_nnum()/set_nnum() - all
|
|
of which are documented below (in "MISCELLANEOUS");
|
|
2) A warning will be emitted if $Math::MPFR::NNW is set to 1
|
|
(default is 0).
|
|
See 'Rmpfr_set_str' (above) and 'Rmpfr_inp_str' (below).
|
|
|
|
##########
|
|
|
|
CONVERSION
|
|
|
|
$str = Rmpfr_get_str($op, $base, $digits, $rnd);
|
|
Returns a string of the form, eg, '8.3456712@2'
|
|
which means '834.56712'.
|
|
The third argument to Rmpfr_get_str() specifies the number of digits
|
|
required to be output in the mantissa. (Trailing zeroes are removed.)
|
|
If $digits is 0, the number of digits of the mantissa is chosen
|
|
large enough so that re-reading the printed value with the same
|
|
precision, assuming both output and input use rounding to nearest,
|
|
will recover the original value of $op.
|
|
$str will be set to 'Nan', '-Inf' or 'Inf' whenever $op is
|
|
(respectively) a NaN, a negative infinity or a positive infinity.
|
|
|
|
($str, $si) = Rmpfr_deref2($op, $base, $digits, $rnd);
|
|
Returns the mantissa to $str (as a string of digits, prefixed with
|
|
a minus sign if $op is negative), and returns the exponent to $si.
|
|
There's an implicit decimal point to the left of the first digit in
|
|
$str. The third argument to Rmpfr_deref2() specifies the number of
|
|
digits required to be output in the mantissa.
|
|
If $digits is 0, the number of digits of the mantissa is chosen
|
|
large enough so that re-reading the printed value with the same
|
|
precision, assuming both output and input use rounding to nearest,
|
|
will recover the original value of $op.
|
|
Unlike Rmpfr_get_str() and Rmpfr_integer_string(), $str will be set
|
|
to '@NaN@', '-@Inf@' or '@Inf@' whenever $op is (respectively) a
|
|
NaN, a negative infinity or a positive infinity, as those are the
|
|
strings that the mpfr library assigns.
|
|
|
|
$str = Rmpfr_integer_string($op, $base, $rnd);
|
|
Returns the truncated integer value of $op as a string. (No exponent
|
|
is returned). For example, if $op contains the value 2.3145679e2,
|
|
$str will be set to "231".
|
|
$str will be set to 'Nan', '-Inf' or 'Inf' whenever $op is
|
|
(respectively) a NaN, a negative infinity or a positive infinity.
|
|
(This function is mainly to provide a simple means of getting 'sj'
|
|
and 'uj' values on a 64-bit perl where the MPFR library does not
|
|
support mpfr_get_uj and mpfr_get_sj functions - which may happen,
|
|
for example, with libraries built with Microsoft Compilers.)
|
|
|
|
$bool = Rmpfr_fits_ushort_p($op, $rnd); # fits in unsigned short
|
|
$bool = Rmpfr_fits_sshort_p($op, $rnd); # fits in signed short
|
|
$bool = Rmpfr_fits_uint_p($op, $rnd); # fits in unsigned int
|
|
$bool = Rmpfr_fits_sint_p($op, $rnd); # fits in signed int
|
|
$bool = Rmpfr_fits_ulong_p($op, $rnd); # fits in unsigned long
|
|
$bool = Rmpfr_fits_slong_p($op, $rnd); # fits in signed long
|
|
$bool = Rmpfr_fits_uintmax_p($op, $rnd); # fits in uintmax_t
|
|
$bool = Rmpfr_fits_intmax_p($op, $rnd); # fits in intmax_t
|
|
$bool = Rmpfr_fits_IV_p($op, $rnd); # fits in perl IV
|
|
$bool = Rmpfr_fits_UV_p($op, $rnd); # fits in perl UV
|
|
Return non-zero if $op would fit in the respective data
|
|
type, when rounded to an integer in the direction $rnd.
|
|
|
|
$ui = Rmpfr_get_ui($op, $rnd);
|
|
$si = Rmpfr_get_si($op, $rnd);
|
|
$sj = Rmpfr_get_sj($op, $rnd);
|
|
$uj = Rmpfr_get_uj($op, $rnd);
|
|
$uv = Rmpfr_get_UV($op, $rnd);
|
|
$iv = Rmpfr_get_IV($op, $rnd);
|
|
Convert $op to an 'unsigned long long', a 'signed long', a
|
|
'signed long long', an 'unsigned long long', a 'UV', or an
|
|
'IV' - after rounding it with respect to $rnd.
|
|
If $op is NaN, the result is undefined. If $op is too big
|
|
for the return type, it returns the maximum or the minimum
|
|
of the corresponding C type, depending on the direction of
|
|
the overflow. The flag erange is then also set.
|
|
|
|
$double = Rmpfr_get_d($op, $rnd);
|
|
$ld = Rmpfr_get_ld($op, $rnd);
|
|
$f128 = Rmpfr_get_float128($op, $rnd);# nvtype is __float128
|
|
# && mpfr-4.0.0 or later
|
|
# && mpfr lib built with
|
|
# --enable-float128 &&
|
|
# F128=1 cmd line arg
|
|
# given to Makefile.PL
|
|
$nv = Rmpfr_get_NV($op, $rnd); # double/long double/__float128
|
|
$float = Rmpfr_get_flt($op, $rnd); # mpfr-3.0.0 and later
|
|
Rmpfr_get_LD($LD, $op, $rnd); # $LD is a Math::LongDouble object.
|
|
Rmpfr_get_DECIMAL64($d64, $op, $rnd); # mpfr-3.1.0 or later &&
|
|
# mpfr lib built with
|
|
# --enable-decimal-float
|
|
# && D64=1 arg given to
|
|
# Makefile.PL. $D64 is a
|
|
# Math::Decimal64 object
|
|
Rmpfr_get_FLOAT128($F128, $op, $rnd);# mpfr-4.0.0 and later &&
|
|
# mpfrlib built with
|
|
# --enable-float128 && F128=1
|
|
# arg given to Makefile.PL.
|
|
# $F128 is a Math::Float128
|
|
# object.
|
|
Convert $op to a 'double', a 'long double', a __float128, an 'NV',
|
|
a float, a Math::LongDouble object, a Math::Decimal64 object, or
|
|
a Math::Float128 object using the rounding mode $rnd.
|
|
|
|
$double = Rmpfr_get_d1($op);
|
|
Convert $op to a double, using the default MPFR rounding mode
|
|
(see function 'mpfr_set_default_rounding_mode').
|
|
|
|
$si = Rmpfr_get_z_exp($z, $op); # $z is a mpz object
|
|
$si = Rmpfr_get_z_2exp($z, $op); # $z is a mpz object
|
|
(Identical functions. Use either - 'get_z_exp' might one day
|
|
be removed.)
|
|
Puts the mantissa of $rop into $z, and returns the exponent
|
|
$si such that $rop == $z * (2 ** $ui).
|
|
|
|
$si = Rmpfr_get_z($z, $op, $rnd); # $z is a mpz object.
|
|
Convert $op to an mpz object ($z), after rounding it with respect
|
|
to RND. If built against mpfr-3.0.0 or later, return the usual
|
|
ternary value. (The function returns undef when using mpfr-2.x.x.)
|
|
If $op is NaN or Inf, the result is undefined.
|
|
|
|
$si = Rmpfr_get_f ($f, $op, $rnd); # $f is a Math::GMPf object.
|
|
Convert $op to a 'mpf_t', after rounding it with respect to $rnd.
|
|
When built against mpfr-3.0.0 or later, this function returns the
|
|
usual ternary value. (If $op is NaN or Inf, then the erange flag
|
|
will be set.) When built against earlier versions of mpfr,
|
|
return zero if no error occurred. In particular a non-zero value
|
|
is returned if $op is NaN or Inf. which do not exist in 'mpf'.
|
|
|
|
Rmpfr_get_q ($q, $op); # $q is a Math::GMPq object.
|
|
Convert $op to a rational value. $q will be set to the exact
|
|
value contained in $op - hence no need for a rounding argument.
|
|
If $op is NaN or Inf, then $q is set to zero and the erange flag
|
|
will be set.
|
|
|
|
$d = Rmpfr_get_d_2exp ($exp, $op, $rnd); # $d is NV (double)
|
|
$d = Rmpfr_get_ld_2exp ($exp, $op, $rnd); # $d is NV (long double)
|
|
Set $exp and $d such that 0.5<=abs($d)<1 and $d times 2 raised
|
|
to $exp equals $op rounded to double (resp. long double)
|
|
precision, using the given rounding mode. If $op is zero, then a
|
|
zero of the same sign (or an unsigned zero, if the implementation
|
|
does not have signed zeros) is returned, and $exp is set to 0.
|
|
If $op is NaN or an infinity, then the corresponding double
|
|
precision (resp. long-double precision) value is returned, and
|
|
$exp is undefined.
|
|
|
|
$si1 = Rmpfr_frexp($si2, $rop, $op, $rnd); # mpfr-3.1.0 and later only
|
|
Set $si and $rop such that 0.5<=abs($rop)<1 and $rop * (2 ** $exp)
|
|
equals $op rounded to the precision of $rop, using the given
|
|
rounding mode. If $op is zero, then $rop is set to zero (of the same
|
|
sign) and $exp is set to 0. If $op is NaN or an infinity, then $rop
|
|
is set to the same value and the value of $exp is meaningless (and
|
|
should be ignored).
|
|
|
|
$ui1 = Rmpfr_get_str_ndigits($ui2, $ui3); # new with mpfr-4.1.0
|
|
Note: $ui2 must be in the range 2..62 (inclusive).
|
|
Return the minimal integer $ui1 such that any number of precision
|
|
$ui3 bits, when output with $ui1 digits in radix $ui2 with rounding
|
|
to nearest, can be recovered exactly when read again, still with
|
|
rounding to nearest.
|
|
More precisely, we have $ui1 = 1 + ceil($ui3 * log(2) / log($ui2)),
|
|
with $ui3 decremented by 1 if $ui2 is a power of 2.
|
|
This function wraps mpfr_get_str_ndigits if mpfr version is 4.1.0
|
|
or later. Otherwise it calls Rmpfr_get_str_ndigits_alt, which does
|
|
not require mpfr-4.1.0.
|
|
|
|
$ui1 = Rmpfr_get_str_ndigits_alt($ui2, $ui3);
|
|
Provided as a fallback (though it can also be called separately)
|
|
for Rmpfr_get_str_ndigits when mpfr version is older than 4.1.0.
|
|
Unlike Rmpfr_get_str_ndigits, this function does not require that
|
|
$ui2 is in the range 2..62.
|
|
|
|
##########
|
|
|
|
ARITHMETIC
|
|
|
|
$si = Rmpfr_add($rop, $op1, $op2, $rnd);
|
|
$si = Rmpfr_add_ui($rop, $op, $ui, $rnd);
|
|
$si = Rmpfr_add_si($rop, $op, $si1, $rnd);
|
|
$si = Rmpfr_add_d($rop, $op, $double, $rnd);
|
|
$si = Rmpfr_add_z($rop, $op, $z, $rnd); # $z is a mpz object.
|
|
$si = Rmpfr_add_q($rop, $op, $q, $rnd); # $q is a mpq object.
|
|
Set $rop to 2nd arg + 3rd arg rounded in the direction $rnd.
|
|
The return value is zero if $rop is exactly 2nd arg + 3rd arg,
|
|
positive if $rop is larger than 2nd arg + 3rd arg, and negative
|
|
if $rop is smaller than 2nd arg + 3rd arg.
|
|
|
|
$si = Rmpfr_sum($rop, \@ops, scalar(@ops), $rnd);
|
|
@ops is an array consisting entirely of Math::MPFR objects.
|
|
Set $rop to the sum of all members of @ops, rounded in the direction
|
|
$rnd. $si is zero when the computed value is the exact value, and
|
|
non-zero when this cannot be guaranteed, without giving the direction
|
|
of the error as the other functions do.
|
|
|
|
$si = Rmpfr_sub($rop, $op1, $op2, $rnd);
|
|
$si = Rmpfr_sub_ui($rop, $op, $ui, $rnd);
|
|
$si = Rmpfr_sub_z($rop, $op, $z, $rnd); # $z is a mpz object.
|
|
$si = Rmpfr_z_sub($rop, $z, $op, $rnd); # mpfr-3.1.0 and later only
|
|
$si = Rmpfr_sub_q($rop, $op, $q, $rnd); # $q is a mpq object.
|
|
$si = Rmpfr_ui_sub($rop, $ui, $op, $rnd);
|
|
$si = Rmpfr_si_sub($rop, $si1, $op, $rnd);
|
|
$si = Rmpfr_sub_si($rop, $op, $si1, $rnd);
|
|
$si = Rmpfr_sub_d($rop, $op, $double, $rnd);
|
|
$si = Rmpfr_d_sub($rop, $double, $op, $rnd);
|
|
Set $rop to 2nd arg - 3rd arg rounded in the direction $rnd.
|
|
The return value is zero if $rop is exactly 2nd arg - 3rd arg,
|
|
positive if $rop is larger than 2nd arg - 3rd arg, and negative
|
|
if $rop is smaller than 2nd arg - 3rd arg.
|
|
|
|
$si = Rmpfr_mul($rop, $op1, $op2, $rnd);
|
|
$si = Rmpfr_mul_ui($rop, $op, $ui, $rnd);
|
|
$si = Rmpfr_mul_si($rop, $op, $si1, $rnd);
|
|
$si = Rmpfr_mul_d($rop, $op, $double, $rnd);
|
|
$si = Rmpfr_mul_z($rop, $op, $z, $rnd); # $z is a mpz object.
|
|
$si = Rmpfr_mul_q($rop, $op, $q, $rnd); # $q is a mpq object.
|
|
Set $rop to 2nd arg * 3rd arg rounded in the direction $rnd.
|
|
Return 0 if the result is exact, a positive value if $rop is
|
|
greater than 2nd arg times 3rd arg, a negative value otherwise.
|
|
|
|
$si = Rmpfr_div($rop, $op1, $op2, $rnd);
|
|
$si = Rmpfr_div_ui($rop, $op, $ui, $rnd);
|
|
$si = Rmpfr_ui_div($rop, $ui, $op, $rnd);
|
|
$si = Rmpfr_div_si($rop, $op, $si1, $rnd);
|
|
$si = Rmpfr_si_div($rop, $si1, $op, $rnd);
|
|
$si = Rmpfr_div_d($rop, $op, $double, $rnd);
|
|
$si = Rmpfr_d_div($rop, $double, $op, $rnd);
|
|
$si = Rmpfr_div_z($rop, $op, $z, $rnd); # $z is a mpz object.
|
|
$si = Rmpfr_z_div($rop, $z, $op, $rnd); # $z is a mpz object.
|
|
$si = Rmpfr_div_q($rop, $op, $q, $rnd); # $q is a mpq object.
|
|
$si = Rmpfr_q_div($rop, $q, $op, $rnd); # $q is a mpq object.
|
|
NOTE: The mpfr library does not provide mpfr_z_div and
|
|
mpfr_q_div functions.
|
|
Set $rop to 2nd arg / 3rd arg rounded in the direction $rnd.
|
|
These functions return 0 if the division is exact, a positive
|
|
value when $rop is larger than 2nd arg divided by 3rd arg,
|
|
and a negative value otherwise.
|
|
|
|
$si = Rmpfr_sqr($rop, $op, $rnd);
|
|
Set $rop to the square of $op, rounded in direction $rnd.
|
|
|
|
$si = Rmpfr_sqrt($rop, $op, $rnd);
|
|
$si = Rmpfr_sqrt_ui($rop, $ui, $rnd);
|
|
Set $rop to the square root of the 2nd arg rounded in the
|
|
direction $rnd. Set $rop to NaN if 2nd arg is negative.
|
|
Return 0 if the operation is exact, a non-zero value otherwise.
|
|
|
|
$si = Rmpfr_rec_sqrt($rop, $op, $rnd);
|
|
Set $rop to $op ** (-1 / 2) rounded in the direction $rnd. Set
|
|
$rop to +Inf if $op is 0, and 0 if $op is +Inf. Set $rop to NaN
|
|
if $op is less than zero.
|
|
|
|
$si = Rmpfr_rec_root($rop, $op, $ui, $rnd);
|
|
NOTE: There is no such mpfr function as mpfr_rec_root.
|
|
This function originally provided as a perl implementation by
|
|
Vincent Lefevre - and rewritten by sisyphus as an XSub.
|
|
(See https://sympa.inria.fr/sympa/arc/mpfr/2016-12/msg00032.html)
|
|
|
|
Set $rop to $op ** (-1 / $ui) rounded in the direction $rnd.
|
|
|
|
May not correctly handle overflow or underflow.
|
|
|
|
$si = Rmpfr_cbrt($rop, $op, $rnd);
|
|
Set $rop to the cubic root of $op, rounded in the direction $rnd.
|
|
|
|
$si = Rmpfr_root($rop, $op, $ui $rnd);
|
|
Deprecated in mpfr-4.0.0 - use Rmpfr_rootn_ui with mpfr-4.0.0.
|
|
Set $rop to the $ui'th root of $op, rounded in the direction
|
|
$rnd. Return 0 if the operation is exact, a non-zero value
|
|
otherwise.
|
|
|
|
$si = Rmpfr_rootn_ui($rop, $op, $ui $rnd); # mpfr-4.0.0 and later
|
|
Same as Rmpfr_root except that $rop is set to +0 (instead of -0)
|
|
when $op is -0 and $ui is even.
|
|
This function (and Rmpfr_cbrt) agree with the rootn function of
|
|
the IEEE 754-2008 standard (Section 9.2).
|
|
|
|
$si = Rmpfr_pow_ui($rop, $op, $ui, $rnd);
|
|
$si = Rmpfr_pow_si($rop, $op, $si, $rnd);
|
|
$si = Rmpfr_ui_pow_ui($rop, $ui, $ui, $rnd);
|
|
$si = Rmpfr_ui_pow($rop, $ui, $op, $rnd);
|
|
$si = Rmpfr_pow($rop, $op1, $op2, $rnd);
|
|
$si = Rmpfr_pow_z($rop, $op1, $z, $rnd); # $z is a mpz object
|
|
Set $rop to 2nd arg raised to 3rd arg, rounded to the directio
|
|
$rnd with the precision of $rop. Return zero if the result is
|
|
exact, a positive value when the result is greater than 2nd arg
|
|
to the power 3rd arg, and a negative value when it is smaller.
|
|
See the MPFR documentation for documentation regarding special
|
|
cases.
|
|
|
|
$si = Rmpfr_neg($rop, $op, $rnd);
|
|
Set $rop to -$op rounded in the direction $rnd. Just
|
|
changes the sign if $rop and $op are the same variable.
|
|
|
|
$si = Rmpfr_abs($rop, $op, $rnd);
|
|
Set $rop to the absolute value of $op, rounded in the direction
|
|
$rnd. Return 0 if the result is exact, a positive value if $rop
|
|
is larger than the absolute value of $op, and a negative value
|
|
otherwise.
|
|
|
|
$si = Rmpfr_dim($rop, $op1, $op2, $rnd);
|
|
Set $rop to the positive difference of $op1 and $op2, i.e.,
|
|
$op1 - $op2 rounded in the direction $rnd if $op1 > $op2, and
|
|
+0 otherwise. $rop is set to NaN when $op1 or $op2 is NaN.
|
|
|
|
$si = Rmpfr_mul_2exp($rop, $op, $ui, $rnd);
|
|
$si = Rmpfr_mul_2ui($rop, $op, $ui, $rnd);
|
|
$si = Rmpfr_mul_2si($rop, $op, $si, $rnd);
|
|
Set $rop to 2nd arg times 2 raised to 3rd arg rounded to the
|
|
direction $rnd. Just increases the exponent by 3rd arg when
|
|
$rop and 2nd arg are identical. Return zero when $rop = 2nd
|
|
arg, a positive value when $rop > 2nd arg, and a negative
|
|
value when $rop < 2nd arg. Note: The 'Rmpfr_mul_2exp' function
|
|
is defined for compatibility reasons; you should use
|
|
'Rmpfr_mul_2ui' (or 'Rmpfr_mul_2si') instead.
|
|
|
|
$si = Rmpfr_div_2exp($rop, $op, $ui, $rnd);
|
|
$si = Rmpfr_div_2ui($rop, $op, $ui, $rnd);
|
|
$si = Rmpfr_div_2si($rop, $op, $si, $rnd);
|
|
Set $rop to 2nd arg divided by 2 raised to 3rd arg rounded to
|
|
the direction $rnd. Just decreases the exponent by 3rd arg
|
|
when $rop and 2nd arg are identical. Return zero when
|
|
$rop = 2nd arg, a positive value when $rop > 2nd arg, and a
|
|
negative value when $rop < 2nd arg. Note: The 'Rmpfr_div_2exp'
|
|
function is defined for compatibility reasons; you should
|
|
use 'Rmpfr_div_2ui' (or 'Rmpfr_div_2si') instead.
|
|
|
|
##########
|
|
|
|
COMPARISON
|
|
|
|
$si = Rmpfr_cmp($op1, $op2);
|
|
$si = Rmpfr_cmpabs($op1, $op2);
|
|
$si = Rmpfr_cmpabs_ui($op, $ui); # requires mpfr-4.1.0 and later
|
|
$si = Rmpfr_cmp_ui($op, $ui);
|
|
$si = Rmpfr_cmp_si($op, $si);
|
|
$si = Rmpfr_cmp_d($op, $double);
|
|
$si = Rmpfr_cmp_ld($op, $ld); # long double
|
|
$si = Rmpfr_cmp_z($op, $z); # $z is a mpz object
|
|
$si = Rmpfr_cmp_q($op, $q); # $q is a mpq object
|
|
$si = Rmpfr_cmp_f($op, $f); # $f is a mpf object
|
|
$si = Rmpfr_cmp_NV($op, $nv);
|
|
Compare 1st and 2nd args. In the case of 'Rmpfr_cmpabs()' and
|
|
'Rmpfr_cmpabs_ui' compare the absolute values of the 2 args.
|
|
Return a positive value if 1st arg > 2nd arg, zero if
|
|
1st arg = 2nd arg, and a negative value if 1st arg < 2nd arg.
|
|
Both args are considered to their full own precision, which may
|
|
differ. In case 1st and 2nd args are of same sign but different,
|
|
the absolute value returned is one plus the absolute difference
|
|
of their exponents. If one of the operands is NaN (Not-a-Number),
|
|
return zero and set the erange flag.
|
|
|
|
$si = Rmpfr_total_order_p($op1, $op2); # new with mpfr-4.1.0
|
|
This function implements the totalOrder predicate from IEEE
|
|
754-2008, where -NaN < -Inf < negative finite numbers < -0 < +0
|
|
< positive finite numbers < +Inf < +NaN. It returns a non-zero
|
|
value (true) when X is smaller than or equal to Y for this order
|
|
relation, and zero (false) otherwise.
|
|
Contrary to 'Rmpfr_cmp($x, $y)', which returns a ternary value,
|
|
'Rmpfr_total_order_p' returns a binary value (zero or non-zero).
|
|
In particular, 'Rmpfr_total_order_p($x, $x)' returns true,
|
|
'Rmpfr_total_order_p(-0, +0)' returns true and
|
|
'Rmpfr_total_order_p(+0, -0)' returns false.
|
|
The sign bit of NaN also matters.
|
|
This function falls back to our own implementation if the mpfr
|
|
version is older than 4.1.0 (because, in that case,
|
|
mpfr_total_order_p is unavailable).
|
|
|
|
$si = Rmpfr_cmp_ui_2exp($op, $ui, $si);
|
|
$si = Rmpfr_cmp_si_2exp($op, $si, $si);
|
|
Compare 1st arg and 2nd arg multiplied by two to the power
|
|
3rd arg.
|
|
|
|
$bool = Rmpfr_eq($op1, $op2, $ui);
|
|
The mpfr library function mpfr_eq may change in future
|
|
releases of the mpfr library (post 2.4.0). If that happens,
|
|
the change will also be relected in Rmpfr_eq.
|
|
Return non-zero if the first $ui bits of $op1 and $op2 are
|
|
equal, zero otherwise. I.e., tests if $op1 and $op2 are
|
|
approximately equal.
|
|
|
|
$bool = Rmpfr_nan_p($op);
|
|
Return non-zero if $op is Not-a-Number (NaN), zero otherwise.
|
|
|
|
$bool = Rmpfr_inf_p($op);
|
|
Return non-zero if $op is plus or minus infinity, zero otherwise.
|
|
|
|
$bool = Rmpfr_number_p($op);
|
|
Return non-zero if $op is an ordinary number, i.e. neither
|
|
Not-a-Number nor plus or minus infinity.
|
|
|
|
$bool = Rmpfr_zero_p($op);
|
|
Return non-zero if $op is zero. Else return 0.
|
|
|
|
$bool = Rmpfr_regular_p($op); # mpfr-3.0.0 and later only
|
|
Return non-zero if $op is a regular number (i.e. neither NaN,
|
|
nor an infinity nor zero). Return zero otherwise.
|
|
|
|
Rmpfr_reldiff($rop, $op1, $op2, $rnd);
|
|
Compute the relative difference between $op1 and $op2 and
|
|
store the result in $rop. This function does not guarantee
|
|
the exact rounding on the relative difference; it just
|
|
computes abs($op1-$op2)/$op1, using the rounding mode
|
|
$rnd for all operations.
|
|
|
|
$si = Rmpfr_sgn($op);
|
|
Return a positive value if op > 0, zero if $op = 0, and a
|
|
negative value if $op < 0. Its result is not specified
|
|
when $op is NaN (Not-a-Number).
|
|
|
|
$bool = Rmpfr_greater_p($op1, $op2);
|
|
Return non-zero if $op1 > $op2, zero otherwise.
|
|
|
|
$bool = Rmpfr_greaterequal_p($op1, $op2);
|
|
Return non-zero if $op1 >= $op2, zero otherwise.
|
|
|
|
$bool = Rmpfr_less_p($op1, $op2);
|
|
Return non-zero if $op1 < $op2, zero otherwise.
|
|
|
|
$bool = Rmpfr_lessequal_p($op1, $op2);
|
|
Return non-zero if $op1 <= $op2, zero otherwise.
|
|
|
|
$bool = Rmpfr_lessgreater_p($op1, $op2);
|
|
Return non-zero if $op1 < $op2 or $op1 > $op2 (i.e. neither
|
|
$op1, nor $op2 is NaN, and $op1 <> $op2), zero otherwise
|
|
(i.e. $op1 and/or $op2 are NaN, or $op1 = $op2).
|
|
|
|
$bool = Rmpfr_equal_p($op1, $op2);
|
|
Return non-zero if $op1 = $op2, zero otherwise
|
|
(i.e. $op1 and/or $op2 are NaN, or $op1 <> $op2).
|
|
|
|
$bool = Rmpfr_unordered_p($op1, $op2);
|
|
Return non-zero if $op1 or $op2 is a NaN
|
|
(i.e. they cannot be compared), zero otherwise.
|
|
|
|
#######
|
|
|
|
SPECIAL
|
|
|
|
$si = Rmpfr_log($rop, $op, $rnd);
|
|
$si = Rmpfr_log_ui($rop, $ui, $rnd); # mpfr-4.0.0 & later only
|
|
$si = Rmpfr_log2($rop, $op, $rnd);
|
|
$si = Rmpfr_log10($rop, $op, $rnd);
|
|
Set $rop to the natural logarithm of $op, the natural
|
|
logarithm of $ui, log2($op) or log10($op), respectively,
|
|
rounded in the direction $rnd.
|
|
|
|
$si = Rmpfr_exp($rop, $op, $rnd);
|
|
$si = Rmpfr_exp2($rop, $op, $rnd);
|
|
$si = Rmpfr_exp10($rop, $op, $rnd);
|
|
Set rop to the exponential of op, to 2 power of op or to
|
|
10 power of op, respectively, rounded in the direction rnd.
|
|
|
|
$si = Rmpfr_sin($rop $op, $rnd);
|
|
$si = Rmpfr_cos($rop, $op, $rnd);
|
|
$si = Rmpfr_tan($rop, $op, $rnd);
|
|
Set $rop to the sine/cosine/tangent respectively of $op,
|
|
rounded to the direction $rnd with the precision of $rop.
|
|
Return 0 if the result is exact (this occurs in fact only
|
|
when $op is 0 i.e. the sine is 0, the cosine is 1, and the
|
|
tangent is 0). Return a negative value if the result is less
|
|
than the actual value. Return a positive result if the
|
|
return is greater than the actual value.
|
|
|
|
$si = Rmpfr_sin_cos($rop1, $rop2, $op, $rnd);
|
|
Set simultaneously $rop1 to the sine of $op and
|
|
$rop2 to the cosine of $op, rounded to the direction $rnd
|
|
with their corresponding precisions. Return 0 if both
|
|
results are exact.
|
|
|
|
$si = Rmpfr_sinh_cosh($rop1, $rop2, $op, $rnd);
|
|
Set simultaneously $rop1 to the hyperbolic sine of $op and
|
|
$rop2 to the hyperbolic cosine of $op, rounded in the direction
|
|
$rnd with the corresponding precision of $rop1 and $rop2 which
|
|
must be different variables. Return 0 if both results are
|
|
exact.
|
|
|
|
$si = Rmpfr_acos($rop, $op, $rnd);
|
|
$si = Rmpfr_asin($rop, $op, $rnd);
|
|
$si = Rmpfr_atan($rop, $op, $rnd);
|
|
Set $rop to the arc-cosine, arc-sine or arc-tangent of $op,
|
|
rounded to the direction $rnd with the precision of $rop.
|
|
Return 0 if the result is exact. Return a negative value if
|
|
the result is less than the actual value. Return a positive
|
|
result if the return is greater than the actual value.
|
|
|
|
$si = Rmpfr_atan2($rop, $op1, $op2, $rnd);
|
|
Set $rop to the tangent of $op1/$op2, rounded to the
|
|
direction $rnd with the precision of $rop.
|
|
Return 0 if the result is exact. Return a negative value if
|
|
the result is less than the actual value. Return a positive
|
|
result if the return is greater than the actual value.
|
|
See the MPFR documentation for details regarding special cases.
|
|
|
|
|
|
$si = Rmpfr_cosh($rop, $op, $rnd);
|
|
$si = Rmpfr_sinh($rop, $op, $rnd);
|
|
$si = Rmpfr_tanh($rop, $op, $rnd);
|
|
Set $rop to the hyperbolic cosine/hyperbolic sine/hyperbolic
|
|
tangent respectively of $op, rounded to the direction $rnd
|
|
with the precision of $rop. Return 0 if the result is exact
|
|
(this occurs in fact only when $op is 0 i.e. the result is 1).
|
|
Return a negative value if the result is less than the actual
|
|
value. Return a positive result if the return is greater than
|
|
the actual value.
|
|
|
|
$si = Rmpfr_acosh($rop, $op, $rnd);
|
|
$si = Rmpfr_asinh($rop, $op, $rnd);
|
|
$si = Rmpfr_atanh($rop, $op, $rnd);
|
|
Set $rop to the inverse hyperbolic cosine, sine or tangent
|
|
of $op, rounded to the direction $rnd with the precision of
|
|
$rop. Return 0 if the result is exact.
|
|
|
|
$si = Rmpfr_sec ($rop, $op, $rnd);
|
|
$si = Rmpfr_csc ($rop, $op, $rnd);
|
|
$si = Rmpfr_cot ($rop, $op, $rnd);
|
|
Set $rop to the secant of $op, cosecant of $op,
|
|
cotangent of $op, rounded in the direction RND. Return 0
|
|
if the result is exact. Return a negative value if the
|
|
result is less than the actual value. Return a positive
|
|
result if the return is greater than the actual value.
|
|
|
|
$si = Rmpfr_sech ($rop, $op, $rnd);
|
|
$si = Rmpfr_csch ($rop, $op, $rnd);
|
|
$si = Rmpfr_coth ($rop, $op, $rnd);
|
|
Set $rop to the hyperbolic secant of $op, cosecant of $op,
|
|
cotangent of $op, rounded in the direction RND. Return 0
|
|
if the result is exact. Return a negative value if the
|
|
result is less than the actual value. Return a positive
|
|
result if the return is greater than the actual value.
|
|
|
|
$bool = Rmpfr_fac_ui($rop, $ui, $rnd);
|
|
Set $rop to the factorial of $ui, rounded to the direction
|
|
$rnd with the precision of $rop. Return 0 if the
|
|
result is exact.
|
|
|
|
$bool = Rmpfr_log1p($rop, $op, $rnd);
|
|
Set $rop to the logarithm of one plus $op, rounded to the
|
|
direction $rnd with the precision of $rop. Return 0 if
|
|
the result is exact (this occurs in fact only when $op is 0
|
|
i.e. the result is 0).
|
|
|
|
$bool = Rmpfr_expm1($rop, $op, $rnd);
|
|
Set $rop to the exponential of $op minus one, rounded to the
|
|
direction $rnd with the precision of $rop. Return 0 if the
|
|
result is exact (this occurs in fact only when $op is 0 i.e
|
|
the result is 0).
|
|
|
|
$si = Rmpfr_fma($rop, $op1, $op2, $op3, $rnd);
|
|
Set $rop to $op1 * $op2 + $op3, rounded to the direction $rnd.
|
|
|
|
$si = Rmpfr_fmma($rop, $op1, $op2, $op3, $op4, $rnd);
|
|
NOTE: Needs mpfr-4.0.0 or later
|
|
Set $rop to $op1 * $op2 + $op3 * $op4, rounded to the
|
|
direction $rnd.
|
|
|
|
$si = Rmpfr_fms($rop, $op1, $op2, $op3, $rnd);
|
|
Set $rop to $op1 * $op2 - $op3, rounded to the direction $rnd.
|
|
|
|
$si = Rmpfr_fmms($rop, $op1, $op2, $op3, $op4, $rnd);
|
|
NOTE: Needs mpfr-4.0.0 or later
|
|
Set $rop to $op1 * $op2 - $op3 * $op4, rounded to the
|
|
direction $rnd.
|
|
|
|
$si = Rmpfr_agm($rop, $op1, $op2, $rnd);
|
|
Set $rop to the arithmetic-geometric mean of $op1 and $op2,
|
|
rounded to the direction $rnd with the precision of $rop.
|
|
Return zero if $rop is exact, a positive value if $rop is
|
|
larger than the exact value, or a negative value if $rop
|
|
is less than the exact value.
|
|
|
|
$si = Rmpfr_hypot ($rop, $op1, $op2, $rnd);
|
|
Set $rop to the Euclidean norm of $op1 and $op2, i.e. the
|
|
square root of the sum of the squares of $op1 and $op2,
|
|
rounded in the direction $rnd. Special values are currently
|
|
handled as described in Section F.9.4.3 of the ISO C99
|
|
standard, for the hypot function (note this may change in
|
|
future versions): If $op1 or $op2 is an infinity, then plus
|
|
infinity is returned in $rop, even if the other number is
|
|
NaN.
|
|
|
|
$si = Rmpfr_ai($rop, $op, $rnd); # mpfr-3.0.0 and later only
|
|
Set $rop to the value of the Airy function Ai on $op,
|
|
rounded in the direction $rnd. When $op is NaN, $rop is
|
|
always set to NaN. When $op is +Inf or -Inf, $rop is +0.
|
|
The current implementation is not intended to be used with
|
|
large arguments. It works with $op typically smaller than
|
|
500. For larger arguments, other methods should be used and
|
|
will be implemented soon.
|
|
|
|
|
|
$si = Rmpfr_const_log2($rop, $rnd);
|
|
Set $rop to the logarithm of 2 rounded to the direction
|
|
$rnd with the precision of $rop. This function stores the
|
|
computed value to avoid another calculation if a lower or
|
|
equal precision is requested.
|
|
Return zero if $rop is exact, a positive value if $rop is
|
|
larger than the exact value, or a negative value if $rop
|
|
is less than the exact value.
|
|
|
|
$si = Rmpfr_const_pi($rop, $rnd);
|
|
Set $rop to the value of Pi rounded to the direction $rnd
|
|
with the precision of $rop. This function uses the Borwein,
|
|
Borwein, Plouffe formula which directly gives the expansion
|
|
of Pi in base 16.
|
|
Return zero if $rop is exact, a positive value if $rop is
|
|
larger than the exact value, or a negative value if $rop
|
|
is less than the exact value.
|
|
|
|
$si = Rmpfr_const_euler($rop, $rnd);
|
|
Set $rop to the value of Euler's constant 0.577... rounded
|
|
to the direction $rnd with the precision of $rop.
|
|
Return zero if $rop is exact, a positive value if $rop is
|
|
larger than the exact value, or a negative value if $rop
|
|
is less than the exact value.
|
|
|
|
$si = Rmpfr_const_catalan($rop, $rnd);
|
|
Set $rop to the value of Catalan's constant 0.915...
|
|
rounded to the direction $rnd with the precision of $rop.
|
|
Return zero if $rop is exact, a positive value if $rop is
|
|
larger than the exact value, or a negative value if $rop
|
|
is less than the exact value.
|
|
|
|
Rmpfr_free_cache();
|
|
Free the cache used by the functions computing constants if
|
|
needed (currently 'mpfr_const_log2', 'mpfr_const_pi' and
|
|
'mpfr_const_euler').
|
|
|
|
Rmpfr_free_cache2($ui); # mpfr-4.0.0 and later only
|
|
Free various caches and pools used by MPFR internally, as
|
|
specified by $ui, which is a set of flags:
|
|
a) those local to the current thread if flag
|
|
MPFR_FREE_LOCAL_CACHE is set;
|
|
b) those shared by all threads if flag
|
|
MPFR_FREE_GLOBAL_CACHE is set.
|
|
|
|
The other bits of $ui are currently ignored and are reserved for
|
|
future use; they should be zero.
|
|
Note:
|
|
Rmpfr_free_cache2(MPFR_FREE_LOCAL_CACHE|MPFR_FREE_GLOBAL_CACHE)
|
|
is currently equivalent to mpfr_free_cache().
|
|
|
|
Rmpfr_free_pool() # mpfr-4.0.0 and later only
|
|
Free the pools used by mpfr internally.
|
|
Note:
|
|
This function is automatically called after the thread-local
|
|
caches are freed (with mpfr_free_cache or mpfr_free_cache2).
|
|
|
|
|
|
$si = Rmpfr_beta($rop, $op1, $op2, $rnd); # mpfr-4.0.0 &
|
|
# later only
|
|
Set $rop to the beta function at $op1, $op2, rounded
|
|
according to $rnd.
|
|
|
|
$si = Rmpfr_gamma($rop, $op, $rnd);
|
|
$si = Rmpfr_lngamma($rop, $op, $rnd);
|
|
Set $rop to the value of the Gamma function on $op
|
|
(and, respectively, its natural logarithm) rounded
|
|
to the direction $rnd. Return zero if $rop is exact, a
|
|
positive value if $rop is larger than the exact value, or a
|
|
negative value if $rop is less than the exact value.
|
|
'Rmpfr_gamma' sets $rop to NaN when $op is negative.
|
|
|
|
$si = Rmpfr_gamma_inc($rop, $op1, $op2, $rnd); # mpfr-4.0.0 &
|
|
# later only
|
|
Set $rop to the value of the incomplete Gamma function on $op1
|
|
and $op2, rounded in the direction $rnd.
|
|
When $op2 is zero and $op1 is a negative value, $rop is set to
|
|
NaN.
|
|
Note: the current implementation is slow for large values of
|
|
$rop and $op, in which case some internal overflow might
|
|
also occur.
|
|
|
|
|
|
($signp, $si) = Rmpfr_lgamma ($rop, $op, $rnd);
|
|
Set $rop to the value of the logarithm of the absolute value
|
|
of the Gamma function on $op, rounded in the direction $rnd.
|
|
The sign (1 or -1) of Gamma($op) is returned in $signp.
|
|
When $op is an infinity or a non-positive integer, +Inf is
|
|
returned. When $op is NaN, -Inf or a negative integer, $signp
|
|
is undefined, and when $op is 0, $signp is the sign of the zero.
|
|
|
|
$si = Rmpfr_digamma ($rop, $op, $rnd); # mpfr-3.0.0 and later only
|
|
Set $rop to the value of the Digamma (sometimes also called Psi)
|
|
function on $op, rounded in the direction $rnd. When $op is a
|
|
negative integer, set $rop to NaN.
|
|
|
|
$si = Rmpfr_zeta($rop, $op, $rnd);
|
|
$si = Rmpfr_zeta_ui($rop, $ul, $rnd);
|
|
Set $rop to the value of the Riemann Zeta function on 2nd arg,
|
|
rounded to the direction $rnd. Return zero if $rop is exact,
|
|
a positive value if $rop is larger than the exact value, or
|
|
a negative value if $rop is less than the exact value.
|
|
|
|
$si = Rmpfr_erf($rop, $op, $rnd);
|
|
Set $rop to the value of the error function on $op,
|
|
rounded to the direction $rnd. Return zero if $rop is exact,
|
|
a positive value if $rop is larger than the exact value, or
|
|
a negative value if $rop is less than the exact value.
|
|
|
|
$si = Rmpfr_erfc($rop, $op, $rnd);
|
|
Set $rop to the complementary error function on $op,
|
|
rounded to the direction $rnd. Return zero if $rop is exact,
|
|
a positive value if $rop is larger than the exact value, or
|
|
a negative value if $rop is less than the exact value.
|
|
|
|
$si = Rmpfr_j0 ($rop, $op, $rnd);
|
|
$si = Rmpfr_j1 ($rop, $op, $rnd);
|
|
$si = Rmpfr_jn ($rop, $si2, $op, $rnd);
|
|
Set $rop to the value of the first order Bessel function of
|
|
order 0, 1 and $si2 on $op, rounded in the direction $rnd.
|
|
When $op is NaN, $rop is always set to NaN. When $op is plus
|
|
or minus Infinity, $rop is set to +0. When $op is zero, and
|
|
$si2 is not zero, $rop is +0 or -0 depending on the parity
|
|
and sign of $si2, and the sign of $op.
|
|
|
|
$si = Rmpfr_y0 ($rop, $op, $rnd);
|
|
$si = Rmpfr_y1 ($rop, $op, $rnd);
|
|
$si = Rmpfr_yn ($rop, $si2, $op, $rnd);
|
|
Set $rop to the value of the second order Bessel function of
|
|
order 0, 1 and $si2 on $op, rounded in the direction $rnd.
|
|
When $op is NaN or negative, $rop is always set to NaN.
|
|
When $op is +Inf, $rop is +0. When $op is zero, $rop is +Inf
|
|
or -Inf depending on the parity and sign of $si2.
|
|
|
|
$si = Rmpfr_eint ($rop, $op, $rnd)
|
|
Set $rop to the exponential integral of $op, rounded in the
|
|
direction $rnd. See the MPFR documentation for details.
|
|
As of mpfr-4.0.0 Rmpfr_eint() returns the value of the
|
|
E1/eint1 function for negative input. (With previous versions
|
|
of mpfr NaN was returned for negative argument.)
|
|
|
|
$si = Rmpfr_li2 ($rop, $op, $rnd);
|
|
Set $rop to real part of the dilogarithm of $op, rounded in the
|
|
direction $rnd. The dilogarithm function is defined here as
|
|
the integral of -log(1-t)/t from 0 to x.
|
|
|
|
$si = Rmpfr_dot ($rop, \@op1, \@op2, $ui, $rnd); # mpfr-4.1.0 &
|
|
# later only
|
|
Set $rop to the dot product of elements of @op1 by those of
|
|
@op2, whose common size is $ui (== scalar @op1), correctly
|
|
rounded in the direction $rnd.
|
|
This function is experimental, and does not yet handle
|
|
intermediate overflows and underflows
|
|
|
|
#############
|
|
|
|
I-O FUNCTIONS
|
|
|
|
$ui = Rmpfr_out_str([$prefix,] $op, $base, $digits, $round [, $suffix]);
|
|
BEST TO USE TRmpfr_out_str INSTEAD
|
|
Output $op to STDOUT, as a string of digits in base $base,
|
|
rounded in direction $round. $base may be in the range 2 to 62
|
|
(or -36..-2, 2 .. 62 if Math::MPFR has been built against
|
|
mpfr-4.1.0 or later).
|
|
Print $digits significant digits exactly, or if $digits is 0,
|
|
enough digits so that $op can be read back exactly
|
|
(see Rmpfr_get_str). In addition to the significant
|
|
digits, a decimal point at the right of the first digit and a
|
|
trailing exponent in base 10, in the form 'eNNN', are printed
|
|
If $base is greater than 10, '@' will be used instead of 'e'
|
|
as exponent delimiter. The optional arguments, $prefix and
|
|
$suffix, are strings that will be prepended/appended to the
|
|
mpfr_out_str output. Return the number of bytes written (not
|
|
counting those contained in $suffix and $prefix), or if an error
|
|
occurred, return 0. (Note that none, one or both of $prefix and
|
|
$suffix can be supplied.)
|
|
|
|
$ui = TRmpfr_out_str([$prefix,] $stream, $base, $digits, $op, $round [, $suffix]);
|
|
As for Rmpfr_out_str, except that there's the capability to print
|
|
to somewhere other than STDOUT. Note that the order of the args
|
|
is different (to match the order of the mpfr_out_str args).
|
|
To print to STDERR:
|
|
TRmpfr_out_str(*stderr, $base, $digits, $op, $round);
|
|
To print to an open filehandle (let's call it FH):
|
|
TRmpfr_out_str(\*FH, $base, $digits, $op, $round);
|
|
|
|
$ui = Rmpfr_inp_str($rop, $base, $round);
|
|
BEST TO USE TRmpfr_inp_str INSTEAD.
|
|
Input a string in base $base from STDIN, rounded in
|
|
direction $round, and put the read float in $rop. The string
|
|
is of the form 'M@N' or, if the base is 10 or less, alternatively
|
|
'MeN' or 'MEN', or, if the base is 16, alternatively 'MpB' or
|
|
'MPB'. 'M' is the mantissa in the specified base, 'N' is the
|
|
exponent written in decimal for the specified base, and in base 16,
|
|
'B' is the binary exponent written in decimal (i.e. it indicates
|
|
the power of 2 by which the mantissa is to be scaled).
|
|
The argument $base may be in the range 2 to 62.
|
|
Special values can be read as follows (the case does not matter):
|
|
'@NaN@', '@Inf@', '+@Inf@' and '-@Inf@', possibly followed by
|
|
other characters; if the base is smaller or equal to 16, the
|
|
following strings are accepted too: 'NaN', 'Inf', '+Inf' and
|
|
'-Inf'.
|
|
Return the number of bytes read, or if non-numeric characters were
|
|
encountered in the input, return 0.
|
|
If 0 is returned:
|
|
1) the non-numeric flag (which was initialised to 0) will be
|
|
incremented. You can query/clear/reset the value of the
|
|
flag with (resp.) nnumflag()/clear_nnum()/set_nnum() - all
|
|
of which are documented below;
|
|
2) A warning will be emitted if $Math::MPFR::NNW is set to 1
|
|
(default is 0).
|
|
|
|
$ui = TRmpfr_inp_str($rop, $stream, $base, $round);
|
|
As for Rmpfr_inp_str, except that there's the capability to read
|
|
from somewhere other than STDIN.
|
|
To read from STDIN:
|
|
TRmpfr_inp_str($rop, *stdin, $base, $round);
|
|
To read from an open filehandle (let's call it FH):
|
|
TRmpfr_inp_str($rop, \*FH, $base, $round);
|
|
|
|
Rmpfr_dump($op);
|
|
Output "$op\n" on stdout in base 2.
|
|
As with 'Rmpfr_print_binary' the exponent is in base 10.
|
|
|
|
$si = Rmpfr_fpif_export ($stream, $op); # Needs mpfr-4.0.0
|
|
$si = Rmpfr_fpif_export ($op, $stream); # Needs mpfr-4.0.0
|
|
Note: These function are experimental and their interface might
|
|
change in future versions of mpfr.
|
|
Export/import the number $op to/from the stream $stream in a
|
|
floating-point interchange format. In particular one can export
|
|
on a 32-bit computer and import on a 64-bit computer, or export
|
|
on a little-endian computer and import on a big-endian computer.
|
|
The precision of OP is stored too. The import function fails if
|
|
the precision (which is read from the stream) is greater than
|
|
MPFR_PREC_MAX.
|
|
Return 0 if the export/import was successful.
|
|
|
|
##########
|
|
|
|
EXCEPTIONS
|
|
|
|
$si = Rmpfr_subnormalize ($op, $si, $rnd);
|
|
This function rounds $op emulating subnormal number arithmetic.
|
|
See the MPFR documentation for mpfr_subnormalize at:
|
|
www.mpfr.org/mpfr-current/mpfr.html#Function-and-Type-Index
|
|
|
|
$si = Rmpfr_get_emin();
|
|
$si = Rmpfr_get_emax();
|
|
Return the (current) smallest and largest exponents
|
|
allowed for a floating-point variable.
|
|
|
|
$si = Rmpfr_get_emin_min();
|
|
$si = Rmpfr_get_emin_max();
|
|
$si = Rmpfr_get_emax_min();
|
|
$si = Rmpfr_get_emax_max();
|
|
Return the minimum and maximum of the smallest and largest
|
|
exponents allowed for 'mpfr_set_emin' and 'mpfr_set_emax'. These
|
|
values are implementation dependent
|
|
|
|
$bool = Rmpfr_set_emin($si);
|
|
$bool = Rmpfr_set_emax($si);
|
|
Set the smallest and largest exponents allowed for a
|
|
floating-point variable. Return a non-zero value when $si is not
|
|
in the range of exponents accepted by the implementation (in that
|
|
case the smallest or largest exponent is not changed), and zero
|
|
otherwise. If the user changes the exponent range, it is her/his
|
|
responsibility to check that all current floating-point variables
|
|
are in the new allowed range (for example using 'Rmpfr_check_range',
|
|
otherwise the subsequent behaviour will be undefined, in the sense
|
|
of the ISO C standard.
|
|
|
|
$si2 = Rmpfr_check_range($op, $si1, $rnd);
|
|
This function assumes that $op is the correctly rounded value of
|
|
some real value X in the direction $rnd and some extended exponent
|
|
range, and that $si1 is the corresponding ternary value. Thus $si1
|
|
is negative if $op is smaller than X, positive if $op is larger than
|
|
X, and zero if $op equals X.
|
|
This function modifies $op if needed to be in the current range of
|
|
acceptable values. It generates an underflow or an overflow if the
|
|
exponent of $op is outside the current allowed range; the value of
|
|
$si1 may be used to avoid a double rounding. This function returns
|
|
zero if the new value of $op equals the exact one X, a positive
|
|
value if that new value is larger than X, and a negative value if
|
|
it is smaller than X. Note that unlike most functions, the new
|
|
result $op is compared to the (unknown) exact one X, not the input
|
|
value $op, i.e., the ternary value is propagated.
|
|
|
|
Note: If $op is an infinity and $si1 is different from zero (i.e.,
|
|
if the rounded result is an inexact infinity), then the
|
|
overflow flag is set.
|
|
|
|
Rmpfr_set_underflow();
|
|
Rmpfr_set_overflow();
|
|
Rmpfr_set_nanflag();
|
|
Rmpfr_set_inexflag();
|
|
Rmpfr_set_erangeflag();
|
|
Rmpfr_set_divby0(); # mpfr-3.1.0 and later only
|
|
Rmpfr_clear_underflow();
|
|
Rmpfr_clear_overflow();
|
|
Rmpfr_clear_nanflag();
|
|
Rmpfr_clear_inexflag();
|
|
Rmpfr_clear_erangeflag();
|
|
Rmpfr_clear_divby0(); # mpfr-3.1.0 and later only
|
|
Set/clear the underflow, overflow, invalid, inexact, erange and
|
|
divide-by-zero flags.
|
|
|
|
Rmpfr_clear_flags();
|
|
Clear all global flags (underflow, overflow, inexact, invalid,
|
|
erange and divide-by-zero).
|
|
|
|
$bool = Rmpfr_underflow_p();
|
|
$bool = Rmpfr_overflow_p();
|
|
$bool = Rmpfr_nanflag_p();
|
|
$bool = Rmpfr_inexflag_p();
|
|
$bool = Rmpfr_erangeflag_p();
|
|
$bool = Rmpfr_divby0_p(); # mpfr-3.1.0 and later only
|
|
Return the corresponding (underflow, overflow, invalid, inexact,
|
|
erange, divide-by-zero) flag, which is non-zero if the flag is set.
|
|
|
|
Rmpfr_flags_clear($mask); # needs mpfr-4.0.0 or later
|
|
Rmpfr_flags_set($mask); # needs mpfr-4.0.0 or later
|
|
$mask2 = Rmpfr_flags_test($mask); # needs mpfr-4.0.0 or later
|
|
$mask = Rmpfr_flags_save(); # needs mpfr-4.0.0 or later
|
|
Rmpfr_flags_restore($mask1, $mask2); # needs mpfr-4.0.0 or later
|
|
$mask is an integer value resulting from OR'ing (or adding) any of
|
|
the following constants together:
|
|
MPFR_FLAGS_UNDERFLOW
|
|
MPFR_FLAGS_OVERFLOW
|
|
MPFR_FLAGS_NAN
|
|
MPFR_FLAGS_INEXACT
|
|
MPFR_FLAGS_ERANGE
|
|
MPFR_FLAGS_DIVBY0
|
|
MPFR_FLAGS_ALL
|
|
MPFR_FLAGS_ALL is the same as all of those constants OR'ed (added)
|
|
together. Examples:
|
|
|
|
Clear the divby0 and nan flags, without affecting the status of
|
|
any other flags:
|
|
Rmpfr_flags_clear(MPFR_FLAGS_DIVBY0|MPFR_FLAGS_NAN);
|
|
|
|
Set the underflow and erange flags, without affecting the status of
|
|
any other flags:
|
|
Rmpfr_flags_set(MPFR_FLAGS_UNDERFLOW|MPFR_FLAGS_ERANGE);
|
|
|
|
Test the status of specific flags, ignoring all other flags. This
|
|
particular example will set $mask to the value of MPFR_FLAGS_NAN
|
|
if the nan flag is set - else $mask will be set to zero:
|
|
$mask = Rmpfr_flags_test(MPFR_FLAGS_UNDERFLOW);
|
|
|
|
Return all flags:
|
|
$mask = Rmpfr_flags_save();
|
|
Equivalently, this can be done with:
|
|
$mask = Rmpfr_flags_test(MPFR_FLAGS_ALL);
|
|
|
|
Set flags specified in $mask2 to the state specified in $mask1,
|
|
For this example, the overflow flag will be set && the nan flag
|
|
will be cleared. The underflow flag will remain untouched.
|
|
$mask1 = MPFR_FLAGS_UNDERFLOW | MPFR_FLAGS_OVERFLOW;
|
|
$mask2 = MPFR_FLAGS_OVERFLOW | MPFR_FLAGS_NAN;
|
|
Rmpfr_flags_restore($mask1, $mask2);
|
|
|
|
#############
|
|
|
|
MISCELLANEOUS
|
|
|
|
$str = doubletoa($nv [, $x]); # Available only when
|
|
# $Config{nvsize} == 8.
|
|
# Else use nvtoa().
|
|
Sets $str to the value of the double $nv.
|
|
$str will appear in standard decimal format such that the
|
|
condition ($str == $nv) is true.
|
|
The grisu3 algorithm used by this function, whilst very quick,
|
|
will fail for about 0.5% of values. When this happens doubletoa
|
|
will (by default) fall back to using nvtoa() - which is slower,
|
|
but reliable.
|
|
Alternatively, providing a second argument to doubletoa (any
|
|
scalar will do) will ensure that sprintf("%.16e", $nv) is
|
|
returned. This will be an accurate return, and it will be
|
|
quicker than the nvtoa() fallback, but it often provides more
|
|
digits than are necessary.
|
|
Whenever doubletoa reverts to a fallback routine,
|
|
$Math::MPFR::doubletoa_fallback (which is initially set to 0)
|
|
will be incremented. This feature can be disabled by providing
|
|
the FB=0 argument to the 'perl Makefile.PL' step of the
|
|
Math::MPFR build.
|
|
|
|
$nv = atodouble($str); # Needs mpfr-3.1.6 or later
|
|
Sets the $nv to the value of the double that's represented by
|
|
the string $str.
|
|
If $Config{nvtype} is double, it therefore returns the same
|
|
value as atonv.
|
|
See atonv() below.
|
|
|
|
$str = nvtoa($nv); # Available irrespective of $Config{nvsize}
|
|
# and $Config{nvtype}
|
|
Sets $str to the value of $nv.
|
|
$str will appear in standard decimal format, containing the
|
|
*minimum* number of digits such that the condition ($str == $nv)
|
|
is true.
|
|
NOTE 1: Except for perls whose nvtype is __float128:
|
|
1) perl versions prior to 5.30.0 are buggy in their
|
|
assignemt of values to the NV;
|
|
2) perl versions from 5.30.0 on that don't define
|
|
$Config{d_strtod} (or respectively $Config{d_strtold}
|
|
for -Duselongdouble builds) are also buggy in their
|
|
assignmentof values to the NV.
|
|
The nvtoa() function looks only at the value that was
|
|
passed to it - which, with such buggy perls, may differ
|
|
from the intended value by a few ULPs.
|
|
On these buggy perls, the bug can be avoided by assigning
|
|
with atonv() - which requires mpfr-3.1.6 or later.
|
|
NOTE 2: Be wary of values assigned by perl to double-double NVs,
|
|
as such assignments may also be buggy, irrespective of
|
|
the perl version.
|
|
Again, with these perls, assign using atonv() - which
|
|
requires mpfr-3.1.6 or later.
|
|
With double-double NVs, nvtoa() currently requires
|
|
mpfr-4.0.0 or later.
|
|
|
|
$nv = atonv($str); # Needs mpfr-3.1.6 or later
|
|
Sets $nv to the NV value represented by the string $str.
|
|
If $str expresses a base 2 value, begin it with '0b' or '0B'.
|
|
If $str expresses a base 16 value, begin it with '0x' or '0X.
|
|
For example:
|
|
atonv('0x0.89p5'), atonv('0x0.112@2'), atonv('17.125') and
|
|
atonv('0b0.10001001e5') all return 17.125.
|
|
NOTE: ORIGINALLY TOOK 2 ARGUMENTS - NOW TAKES ONLY 1, as of
|
|
Math-MPFR-4.07.
|
|
|
|
$str = numtoa($sv);
|
|
As for nvtoa() but prints out UVs and IVs in integer format.
|
|
(If UV-precision is greater than NV-precision then nvtoa()
|
|
output can lose precision as it prints out UVs and IVs in floating
|
|
point format.)
|
|
|
|
$sv = atonum($str); # Needs mpfr-3.1.6 or later
|
|
If $str numifies to an IV, return that IV.
|
|
Else return the NV that is returned by atonv($str).
|
|
|
|
$MPFR_version = Rmpfr_get_version();
|
|
Returns the version of the MPFR library (eg 4.0.2) being used by
|
|
Math::MPFR.
|
|
|
|
$GMP_version = Math::MPFR::gmp_v();
|
|
Returns the version of the gmp library (eg. 4.1.3) being used by
|
|
the mpfr library that's being used by Math::MPFR.
|
|
The function is not exportable.
|
|
|
|
$ui = MPFR_VERSION;
|
|
An integer whose value is dependent upon the 'major', 'minor' and
|
|
'patchlevel' values of the MPFR library against which Math::MPFR
|
|
was built.
|
|
This value is from the mpfr.h that was in use when the compilation
|
|
of Math::MPFR took place.
|
|
|
|
$ui = MPFR_VERSION_MAJOR;
|
|
The 'x' in the 'x.y.z' of the MPFR library version.
|
|
This value is from the mpfr.h that was in use when the compilation
|
|
of Math::MPFR took place.
|
|
|
|
$ui = MPFR_VERSION_MINOR;
|
|
The 'y' in the 'x.y.z' of the MPFR library version.
|
|
This value is from the mpfr.h that was in use when the compilation
|
|
of Math::MPFR took place.
|
|
|
|
$ui = MPFR_VERSION_PATCHLEVEL;
|
|
The 'z' in the 'x.y.z' of the MPFR library version.
|
|
This value is from the mpfr.h that was in use when the compilation
|
|
of Math::MPFR took place.
|
|
|
|
$string = MPFR_VERSION_STRING;
|
|
$string is set to the version of the MPFR library (eg 2.1.0)
|
|
against which Math::MPFR was built.
|
|
This value is from the mpfr.h that was in use when the compilation
|
|
of Math::MPFR took place.
|
|
|
|
$ui = MPFR_VERSION_NUM($major, $minor, $patchlevel);
|
|
Returns the value for MPFR_VERSION for "MPFR-$major.$minor.$patchlevel".
|
|
|
|
$str = Rmpfr_get_patches();
|
|
Return a string containing the ids of the patches applied to the
|
|
MPFR library (contents of the 'PATCHES' file), separated by spaces.
|
|
Note: If the program has been compiled with an older MPFR version and
|
|
is dynamically linked with a new MPFR library version, the ids of the
|
|
patches applied to the old (compile-time) MPFR version are not
|
|
available (however this information should not have much interest
|
|
in general).
|
|
|
|
$bool = Rmpfr_buildopt_tls_p(); # mpfr-3.0.0 and later only
|
|
Return a non-zero value if mpfr was compiled as thread safe using
|
|
compiler-level Thread Local Storage (that is mpfr was built with
|
|
the '--enable-thread-safe' configure option), else return zero.
|
|
|
|
$bool = Rmpfr_buildopt_decimal_p(); # mpfr-3.0.0 and later only
|
|
Return a non-zero value if mpfr was compiled with decimal float
|
|
support (that is mpfr was built with the '--enable-decimal-float'
|
|
configure option), return zero otherwise.
|
|
|
|
$bool = Rmpfr_buildopt_float128_p(); # mpfr-4.0.0 and later only
|
|
Return a non-zero value if mpfr was compiled with __float128
|
|
support (that is mpfr was built with the '--enable-decimal-float'
|
|
configure option), return zero otherwise.
|
|
|
|
$bool = Rmpfr_buildopt_gmpinternals_p(); # mpfr-3.1.0 and later only
|
|
Return a non-zero value if mpfr was compiled with gmp internals
|
|
(that is, mpfr was built with either '--with-gmp-build' or
|
|
'--enable-gmp-internals' configure option), return zero otherwise.
|
|
|
|
$bool = Rmpfr_buildopt_sharedcache_p(); # mpfr-4.0.0 and later only
|
|
Return a non-zero value if MPFR was compiled so that all threads
|
|
share the same cache for the one MPFR constant, like `mpfr_const_pi'
|
|
or `mpfr_const_log2' (that is, MPFR was built with the
|
|
`--enable-shared-cache' configure option), return zero otherwise.
|
|
|
|
$str = Rmpfr_buildopt_tune_case(); # mpfr-3.1.0 and later only
|
|
Return a string saying which thresholds file has been used at
|
|
compile time. This file is normally selected from the processor
|
|
type. If "make tune" has been used, then it will return
|
|
"src/mparam.h". Otherwise it will say which official mparam.h file
|
|
has been used.
|
|
|
|
$si = Rmpfr_rint($rop, $op, $rnd);
|
|
$si = Rmpfr_ceil($rop, $op);
|
|
$si = Rmpfr_floor($rop, $op);
|
|
$si = Rmpfr_round($rop, $op);
|
|
$si = Rmpfr_roundeven($rop, $op); # mpfr-4.0.0 and later only
|
|
$si = Rmpfr_trunc($rop, $op);
|
|
Set $rop to $op rounded to an integer. 'Rmpfr_ceil' rounds to the
|
|
next higher representable integer, 'Rmpfr_floor' to the next lower,
|
|
'Rmpfr_round' to the nearest representable integer, rounding
|
|
halfway cases away from zero, 'Rmpfr_roundeven' to the nearest
|
|
representable integer, rounding halfway cases with the even-
|
|
rounding rule and 'Rmpfr_trunc' to the representable integer
|
|
towards zero. 'Rmpfr_rint' behaves like one of these four functions,
|
|
depending on the rounding mode. The returned value is zero when the
|
|
result is exact, positive when it is greater than the original value
|
|
of $op, and negative when it is smaller. More precisely, the
|
|
returned value is 0 when $op is an integer representable in $rop, 1
|
|
or -1 when $op is an integer that is not representable in $rop, 2 or
|
|
-2 when $op is not an integer.
|
|
|
|
$si = Rmpfr_rint_ceil($rop, $op, $rnd);
|
|
$si = Rmpfr_rint_floor($rop, $op, $rnd);
|
|
$si = Rmpfr_rint_round($rop, $op, $rnd);
|
|
$si = Rmpfr_rint_roundeven($rop, $op, $rnd); # mpfr-4.0.0 & later
|
|
$si = Rmpfr_rint_trunc($rop, $op, $rnd);
|
|
Set $rop to $op rounded to an integer. 'Rmpfr_rint_ceil' rounds to
|
|
the next higher or equal integer, 'Rmpfr_rint_floor' to the next
|
|
lower or equal integer, 'Rmpfr_rint_round' to the nearest integer,
|
|
rounding halfway cases away from zero, 'Rmpfr_rint_roundeven' to
|
|
the nearest integer,rounding halfway cases to the nearest even
|
|
integer and 'Rmpfr_rint_trunc' to the next integer towards zero.
|
|
If the result is not representable, it is rounded in the direction
|
|
$rnd. The returned value is the ternary value associated with the
|
|
considered round-to-integer function (regarded in the same way as
|
|
any other mathematical function).
|
|
|
|
$si = Rmpfr_frac($rop, $op, $round);
|
|
Set $rop to the fractional part of $op, having the same sign as $op,
|
|
rounded in the direction $round (unlike in 'mpfr_rint', $round
|
|
affects only how the exact fractional part is rounded, not how
|
|
the fractional part is generated).
|
|
|
|
$si = Rmpfr_modf ($rop1, $rop2, $op, $rnd);
|
|
Set simultaneously $rop1 to the integral part of $op and $rop2
|
|
to the fractional part of $op, rounded in the direction RND with
|
|
the corresponding precision of $rop1 and $rop2 (equivalent to
|
|
'Rmpfr_trunc($rop1, $op, $rnd)' and 'Rmpfr_frac($rop1, $op, $rnd)').
|
|
The variables $rop1 and $rop2 must be different. Return 0 if both
|
|
results are exact.
|
|
|
|
$si = Rmpfr_remainder($rop, $op1, $op2, $rnd);
|
|
$si = Rmpfr_fmod($rop, $op1, $op2, $rnd);
|
|
($si2, $si) = Rmpfr_remquo ($rop, $op1, $op2, $rnd);
|
|
($si2, $si) = Rmpfr_fmodquo ($rop, $op1, $op2, $rnd); # mpfr-4.0.0 &
|
|
# later only
|
|
Set $rop to the value of $op - N*$op2, rounded according to the
|
|
direction $rnd, where N is the integer quotient of $op1 divided by
|
|
$op2, defined as follows: N is rounded toward zero for 'Rmpfr_fmod'
|
|
and 'Rmpfr_fmodquo', and to the nearest integer (ties rounded to
|
|
even) for 'mpfr_remainder' and 'mpfr_remquo'.
|
|
Special values are handled as described in Section F.9.7.1 of the
|
|
ISO C99 standard: If $op1 is infinite or $op2 is zero, $rop is NaN.
|
|
If $op2 is infinite and $op1 is finite, $rop is $op1 rounded to
|
|
the precision of $rop. If $rop is zero, it has the sign of $op1.
|
|
The return value is the ternary value corresponding to $rop.
|
|
Additionally, 'Rmpfr_remquo' and 'Rmpfr_fmodquo store the low
|
|
significant bits from the quotient in $si2 (more precisely the
|
|
number of bits in a 'long' minus one), with the sign of $op1
|
|
divided by $op2 (except if those low bits are all zero, in which
|
|
case zero is returned). Note that $op1 may be so large in
|
|
magnitude relative to $op2 that an exact representation of the
|
|
quotient is not practical. 'Rmpfr_remainder' and Rmpfr_remquo'
|
|
functions are useful for additive argument reduction.
|
|
|
|
$si = Rmpfr_integer_p($op);
|
|
Return non-zero if $op is an integer.
|
|
|
|
Rmpfr_nexttoward($op1, $op2);
|
|
If $op1 or $op2 is NaN, set $op1 to NaN. Otherwise, if $op1 is
|
|
different from $op2, replace $op1 by the next floating-point number
|
|
(with the precision of $op1 and the current exponent range) in the
|
|
direction of $op2, if there is one (the infinite values are seen as
|
|
the smallest and largest floating-point numbers). If the result is
|
|
zero, it keeps the same sign. No underflow or overflow is generated.
|
|
|
|
Rmpfr_nextabove($op1);
|
|
Equivalent to 'mpfr_nexttoward' where $op2 is plus infinity.
|
|
|
|
Rmpfr_nextbelow($op1);
|
|
Equivalent to 'mpfr_nexttoward' where $op2 is minus infinity.
|
|
|
|
$si = Rmpfr_min($rop, $op1, $op2, $round);
|
|
Set $rop to the minimum of $op1 and $op2. If $op1 and $op2
|
|
are both NaN, then $rop is set to NaN. If $op1 or $op2 is
|
|
NaN, then $rop is set to the numeric value. If $op1 and
|
|
$op2 are zeros of different signs, then $rop is set to -0.
|
|
|
|
$si = Rmpfr_max($rop, $op1, $op2, $round);
|
|
Set $rop to the maximum of $op1 and $op2. If $op1 and $op2
|
|
are both NaN, then $rop is set to NaN. If $op1 or $op2 is
|
|
NaN, then $rop is set to the numeric value. If $op1 and
|
|
$op2 are zeros of different signs, then $rop is set to +0.
|
|
|
|
$iv = Math::MPFR::nnumflag(); # not exported
|
|
Returns the value of the non-numeric flag. This flag is
|
|
initialized to zero, but incemented by 1 whenever the
|
|
a string containing non-numeric characters is passed to an
|
|
mpfr function. The value of the flag therefore tells us how
|
|
many times such strings were passed to mpfr functions . The
|
|
flag can be reset to 0 by running clear_nnum().
|
|
|
|
$iv = Math::MPFR::nok_pokflag(); # not exported
|
|
Returns the value of the nok_pok flag. This flag is
|
|
initialized to zero, but incemented by 1 whenever a
|
|
scalar that is both a float (NOK) and string (POK) is passed
|
|
to new() or to an overloaded operator. The value of the flag
|
|
therefore tells us how many times such events occurred . The
|
|
flag can be reset to 0 by running clear_nok_pok().
|
|
|
|
Math::MPFR::set_nnum($iv); # not exported
|
|
Resets the global non-numeric flag to the value specified by
|
|
$iv.
|
|
|
|
Math::MPFR::set_nok_pok($iv); # not exported
|
|
Resets the nok_pok flag to the value specified by $iv.
|
|
|
|
Math::MPFR::clear_nnum(); # not exported
|
|
Resets the global non-numeric flag to 0.(Essentially the same
|
|
as running set_nnum(0).)
|
|
|
|
Math::MPFR::clear_nok_pok(); # not exported
|
|
Resets the nok_pok flag to 0.(Essentially the same
|
|
as running set_nok_pok(0).)
|
|
|
|
$bytes = Math::MPFR::bytes($val, $bits);
|
|
(The semantics for calling this function have changed as of
|
|
Math-MPFR-4.13.)
|
|
$val must either be a string (eg '1.613e-45', '2.3', '0x17.8')
|
|
or a Math::MPFR object.
|
|
$bits must be one of 53, 64, 2098 or 113.
|
|
$bytes will be set to the hex representation of $val.
|
|
If $bits is 53, $bytes will display the byte structure (in
|
|
hex) of the standard 8-byte double, $val.
|
|
If $bits is 64, the structure returned will be that of $val
|
|
as an extended precison 10-byte long double.
|
|
If $bits is 2098, the structure returned will be that of $val
|
|
as the 16-byte IBM doubledouble.
|
|
If $bits is 113, the structure returned will be that of $val
|
|
as the quad precison 16-byte IEEE long double (or __float128,
|
|
which is identical in byte structure).
|
|
|
|
eg:
|
|
bytes('1.3', 53) returns 3ff4cccccccccccd
|
|
bytes('1.3', 64) returns 3fffa666666666666666
|
|
bytes('1.3', 2098) returns 3ff4cccccccccccdbc8999999999999a
|
|
bytes('1.3', 113) returns 3fff4ccccccccccccccccccccccccccd
|
|
|
|
If $val is a Math::MPFR object, its precision must be $bits.
|
|
|
|
For many architectures and mpfr configurations, the structures
|
|
for all 4 allowed values of $bits will be accessible.
|
|
In some cases, however, $bits values of 64 and/or 113 might
|
|
throw a fatal error (with diagnostic message stating that the
|
|
requested byte structure is not currently available).
|
|
|
|
##############
|
|
|
|
RANDOM NUMBERS
|
|
|
|
Rmpfr_urandomb(@r, $state);
|
|
Each member of @r is a Math::MPFR object.
|
|
$state is a reference to a gmp_randstate_t structure.
|
|
Set each member of @r to a uniformly distributed random
|
|
float in the interval 0 <= $_ < 1.
|
|
Before using this function you must first create $state
|
|
by calling one of the 4 Rmpfr_randinit functions, then
|
|
seed $state by calling one of the 2 Rmpfr_randseed functions.
|
|
The memory associated with $state will be freed automatically
|
|
when $state goes out of scope.
|
|
|
|
Rmpfr_random2($rop, $si, $ui); # not implemented in
|
|
# mpfr-3.0.0 and later
|
|
Attempting to use this function when Math::MPFR has been
|
|
built against mpfr-3.0.0 (or later) will cause the program
|
|
to die, with an appropriate error message.
|
|
Generate a random float of at most abs($si) limbs, with long
|
|
strings of zeros and ones in the binary representation.
|
|
The exponent of the number is in the interval -$ui to
|
|
$ui. This function is useful for testing functions and
|
|
algorithms, since this kind of random numbers have proven
|
|
to be more likely to trigger corner-case bugs. Negative
|
|
random numbers are generated when $si is negative.
|
|
|
|
$si = Rmpfr_urandom ($rop, $state, $rnd); # mpfr-3.0.0 and
|
|
# later only
|
|
Generate a uniformly distributed random float. The
|
|
floating-point number $rop can be seen as if a random real
|
|
number is generated according to the continuous uniform
|
|
distribution on the interval[0, 1] and then rounded in the
|
|
direction RND.
|
|
Before using this function you must first create $state
|
|
by calling one of the Rmpfr_randinit functions (below), then
|
|
seed $state by calling one of the Rmpfr_randseed functions.
|
|
|
|
$si = Rmpfr_grandom($rop1, $rop2, $state, $rnd);
|
|
Available only with mpfr-3.1.0 and later.
|
|
Deprecated in mpfr-4.0.0. Use Rmpfr_nrandom with mpfr-4.0.0.
|
|
Generate two random floats according to a standard normal
|
|
gaussian distribution. The floating-point numbers $rop1 and
|
|
$rop2 can be seen as if a random real number were generated
|
|
according to the standard normal gaussian distribution and
|
|
then rounded in the direction $rnd.
|
|
Before using this function you must first create $state
|
|
by calling one of the Rmpfr_randinit functions (below), then
|
|
seed $state by calling one of the Rmpfr_randseed functions.
|
|
|
|
$si = Rmpfr_nrandom ($rop, $state, $rnd); # mpfr-4.0.0 and
|
|
# later only
|
|
Generate a random floating-point number according to a standard
|
|
normal Gaussian distribution (with mean zero and variance one).
|
|
The floating-point number $rop can be seen as if a random real
|
|
number were generated according to the standard normal Gaussian
|
|
distribution and then rounded in the direction $rnd.
|
|
This function is more efficient than Rmpfr_grandom.
|
|
|
|
$si = Rmpfr_erandom($rop, $state, $rnd); # mpfr-4.0.0 and
|
|
# later only
|
|
Generate one random floating-point number according to an
|
|
exponential distribution, with mean one. Other characteristics
|
|
are identical to 'Rmpfr_nrandom'.
|
|
|
|
$state = Rmpfr_randinit_default();
|
|
Initialise $state with a default algorithm. This will be
|
|
a compromise between speed and randomness, and is
|
|
recommended for applications with no special requirements.
|
|
|
|
$state = Rmpfr_randinit_mt();
|
|
Initialize state for a Mersenne Twister algorithm. This
|
|
algorithm is fast and has good randomness properties.
|
|
|
|
$state = Rmpfr_randinit_lc_2exp($a, $c, $m2exp);
|
|
This function is not tested in the test suite.
|
|
Use with caution - I often select values here that cause
|
|
Rmpf_urandomb() to behave non-randomly.
|
|
Initialise $state with a linear congruential algorithm:
|
|
X = ($a * X + $c) % 2 ** $m2exp
|
|
The low bits in X are not very random - for this reason
|
|
only the high half of each X is actually used.
|
|
$c and $m2exp sre both unsigned longs.
|
|
$a can be any one of Math::GMP, or Math::GMPz objects.
|
|
Or it can be a string.
|
|
If it is a string of hex digits it must be prefixed with
|
|
either OX or Ox. If it is a string of octal digits it must
|
|
be prefixed with 'O'. Else it is assumed to be a decimal
|
|
integer. No other bases are allowed.
|
|
|
|
$state = Rmpfr_randinit_lc_2exp_size($ui);
|
|
Initialise state as per Rmpfr_randinit_lc_2exp. The values
|
|
for $a, $c. and $m2exp are selected from a table, chosen
|
|
so that $ui bits (or more) of each X will be used.
|
|
|
|
Rmpfr_randseed($state, $seed);
|
|
$state is a reference to a gmp_randstate_t strucure (the
|
|
return value of one of the Rmpfr_randinit functions).
|
|
$seed is the seed. It can be any one of Math::GMP,
|
|
or Math::GMPz objects. Or it can be a string of digits.
|
|
If it is a string of hex digits it must be prefixed with
|
|
either OX or Ox. If it is a string of octal digits it must
|
|
be prefixed with 'O'. Else it is assumed to be a decimal
|
|
integer. No other bases are allowed.
|
|
|
|
Rmpfr_randseed_ui($state, $ui);
|
|
$state is a reference to a gmp_randstate_t strucure (the
|
|
return value of one of the Rmpfr_randinit functions).
|
|
$ui is the seed.
|
|
|
|
#########
|
|
|
|
INTERNALS
|
|
|
|
$bool = Rmpfr_can_round($op, $ui, $rnd1, $rnd2, $p);
|
|
Assuming $op is an approximation of an unknown number X in direction
|
|
$rnd1 with error at most two to the power E(b)-$ui where E(b) is
|
|
the exponent of $op, returns 1 if one is able to round exactly X
|
|
to precision $p with direction $rnd2, and 0 otherwise. This
|
|
function *does not modify* its arguments.
|
|
|
|
$str = Rmpfr_print_rnd_mode($rnd);
|
|
Return a string ("MPFR_RNDD", "MPFR_RNDU", "MPFR_RNDN", "MPFR_RNDZ",
|
|
"MPFR_RNDA") corresponding to the rounding mode $rnd, or return
|
|
undef if $rnd is an invalid rounding mode.
|
|
|
|
$si = Rmpfr_get_exp($op);
|
|
Get the exponent of $op, assuming that $op is a non-zero
|
|
ordinary number.
|
|
|
|
$si = Rmpfr_set_exp($op, $si);
|
|
Set the exponent of $op if $si is in the current exponent
|
|
range, and return 0 (even if $op is not a non-zero
|
|
ordinary number); otherwise, return a non-zero value.
|
|
|
|
$si = Rmpfr_signbit ($op);
|
|
Return a non-zero value if $op has its sign bit set (i.e. if it is
|
|
negative, -0, or a NaN whose representation has its sign bit set).
|
|
|
|
$si2 = Rmpfr_setsign ($rop, $op, $si, $rnd);
|
|
Set the value of $rop from $op, rounded towards the given direction
|
|
$rnd, then set/clear its sign bit if $si is true/false (even when
|
|
$op is a NaN).
|
|
|
|
$si = Rmpfr_copysign ($rop, $op1, $op2, $rnd);
|
|
Set the value of $rop from $op1, rounded towards the given direction
|
|
$rnd, then set its sign bit to that of $op2 (even when $op1 or $op2
|
|
is a NaN). This function is equivalent to:
|
|
Rmpfr_setsign ($rop, $op1, Rmpfr_signbit ($op2), $rnd)'.
|
|
|
|
####################
|
|
|
|
OPERATOR OVERLOADING
|
|
|
|
Overloading works with numbers, strings (bases 2, 10, and 16
|
|
only - see step '4.' below) and Math::MPFR objects.
|
|
Overloaded operations are performed using the current
|
|
"default rounding mode" (which you can determine using the
|
|
'Rmpfr_get_default_rounding_mode' function, and change using
|
|
the 'Rmpfr_set_default_rounding_mode' function).
|
|
|
|
Be aware that when you use overloading with a string operand,
|
|
the overload subroutine converts that string operand to a
|
|
Math::MPFR object with *current default precision*, and using
|
|
the *current default rounding mode*.
|
|
|
|
Note that any comparison using the spaceship operator ( <=> )
|
|
will return undef if either/both of the operands is a NaN.
|
|
All comparisons ( < <= > >= == != <=> ) involving one or more
|
|
NaNs will set the erange flag.
|
|
|
|
For the purposes of the overloaded 'not', '!' and 'bool'
|
|
operators, a "false" Math::MPFR object is one whose value is
|
|
either 0 (including -0) or NaN.
|
|
(A "true" Math::MPFR object is, of course, simply one that
|
|
is not "false".)
|
|
|
|
The following operators are overloaded:
|
|
+ - * / ** sqrt (Return object has default precision)
|
|
+= -= *= /= **= ++ -- (Precision remains unchanged)
|
|
< <= > >= == != <=>
|
|
! bool
|
|
abs atan2 cos sin log exp (Return object has default precision)
|
|
int (On perl 5.8 only, NA on perl 5.6. The return object
|
|
has default precision)
|
|
= (The copy has the same precision as the copied object.)
|
|
""
|
|
|
|
All overloaded comparisons ( < <= > >= == != <=> ) between
|
|
Math::MPFR and Math::GMPz objects or between Math::MPFR and
|
|
Math::GMPq objects are now also permitted.
|
|
. allowed
|
|
|
|
As of version 3.13 of Math::MPFR, some cross-class overloading
|
|
is allowed.
|
|
Let $M be a Math::MPFR object, and $G be any one of a Math::GMPz,
|
|
Math::GMPq or Math::GMPf object. Then it is now permissible to
|
|
do:
|
|
|
|
$M + $G;
|
|
$M - $G;
|
|
$M * $G;
|
|
$M / $G;
|
|
$M ** $G;
|
|
|
|
In each of the above, a Math::MPFR object containing the result
|
|
of the operation is returned. It is also now permissible to do:
|
|
|
|
$M += $G;
|
|
$M -= $G;
|
|
$M *= $G;
|
|
$M /= $G;
|
|
$M **= $G;
|
|
|
|
If you have version 0.35 (or later) of Math::GMPz, Math::GMPq
|
|
and Math::GMPf, it is also permissible to do:
|
|
|
|
$G + $M;
|
|
$G - $M;
|
|
$G * $M;
|
|
$G / $M;
|
|
$G ** $M;
|
|
|
|
Again, each of those operations returns a Math::MPFR object
|
|
containing the result of the operation.
|
|
Each operation is conducted using current default rounding mode.
|
|
|
|
NOTE: In overloading a ** (power) operation that involves a
|
|
Math::GMPq object, it is necessary to convert the Math::GMPq
|
|
object to an mpfr_t (the type of value encapsulated in the
|
|
Math::MPFR object). This conversion is done using current default
|
|
precision and current default rounding mode.
|
|
|
|
The following is still NOT ALLOWED, and will cause a fatal error:
|
|
|
|
$G += $M;
|
|
$G -= $M;
|
|
$G *= $M;
|
|
$G /= $M;
|
|
$G **= $M;
|
|
|
|
In those situations where the overload subroutine operates on 2
|
|
perl variables, then obviously one of those perl variables is
|
|
a Math::MPFR object. To determine the value of the other variable
|
|
the subroutine works through the following steps (in order),
|
|
using the first value it finds, or croaking if it gets
|
|
to step 6:
|
|
|
|
1. If the variable is a UV (unsigned integer value) then that
|
|
value is used. The variable is considered to be a UV if
|
|
(perl 5.8) the UOK flag is set or if (perl 5.6) SvIsUV()
|
|
returns true.
|
|
|
|
2. If the variable is an IV (signed integer value) then that
|
|
value is used. The variable is considered to be an IV if the
|
|
IOK flag is set.
|
|
|
|
3. If the variable is an NV (floating point value) then that
|
|
value is used. The variable is considered to be an NV if the
|
|
NOK flag is set && the POK flag is unset.
|
|
Note therefore, that if the variable is both an NV (NOK flag
|
|
set) and PV (POK flag also set) then the string value in the
|
|
PV slot will be used. This is probably, but not necessarily,
|
|
what you want, and it's recommended not to pass such values
|
|
to the overloaded operators.
|
|
|
|
4. If the variable is a string (ie the POK flag is set) then the
|
|
value of that string is used. If the POK flag is set, but the
|
|
string is not a valid number, the subroutine croaks with an
|
|
appropriate error message. If the string starts with '0b' or
|
|
'0B' it is regarded as a base 2 number. If it starts with '0x'
|
|
or '0X' it is regarded as a base 16 number. Otherwise it is
|
|
regarded as a base 10 number.
|
|
|
|
5. If the variable is a Math::MPFR, Math::GMPz, Math::GMPf, or
|
|
Math::GMPq object then the value of that object is used.
|
|
|
|
6. If none of the above is true, then the second variable is
|
|
deemed to be of an invalid type. The subroutine croaks with
|
|
an appropriate error message.
|
|
|
|
#####################
|
|
|
|
FORMATTED OUTPUT
|
|
|
|
NOTE: When using the 'P' (precision) type specifier, instead of
|
|
providing $prec to the 'P' specifier, it's now advisable
|
|
to provide prec_cast($prec). The 'P' specifier expects an
|
|
mp_prec_t but, prior to 3.18, we could pass it only an IV.
|
|
This didn't work on at least some big-endian machines if
|
|
the size of the IV was greater than the size of the
|
|
mp_prec_t.
|
|
The Math::MPFR::Prec package (which is part of this
|
|
distribution) exists solely to provide the prec_cast sub.
|
|
And the prec_cast sub's return value should be passed *only*
|
|
to the 'P' type specifier. Nothing else will understand it.
|
|
Passing it to something other than the 'P' specifier may
|
|
produce a garbage result - might even cause a segfault.
|
|
|
|
prec_cast($prec);
|
|
|
|
Ensures that the 'P' type specifier will provide correct results.
|
|
In Math::MPFR versions prior to 3.18 we could do only (eg) :
|
|
Rmpfr_printf("%Pu\n", Rmpfr_get_prec($op));
|
|
But that didn't work correctly for all architectures. As of 3.18,
|
|
that can be rewritten as:
|
|
Rmpfr_printf("%Pu\n", prec_cast(Rmpfr_get_prec($op)));
|
|
which should work on all architectures.
|
|
|
|
Rmpfr_printf($format_string, [$rnd,] $var);
|
|
|
|
This function (unlike the MPFR counterpart) is limited to taking
|
|
2 or 3 arguments - the format string, optionally a rounding argument,
|
|
and the variable to be formatted.
|
|
That is, you can currently printf only one variable at a time.
|
|
If there's no variable to be formatted, just add a '0' as the final
|
|
argument. ie this will work fine:
|
|
Rmpfr_printf("hello world\n", 0);
|
|
NOTE: The rounding argument $rnd can be provided *only* if $var is a
|
|
Math::MPFR object. To do otherwise is a fatal error.
|
|
See the mpfr documentation for details re the formatting options:
|
|
http://www.mpfr.org/mpfr-current/mpfr.html#Formatted-Output-Functions
|
|
|
|
Rmpfr_fprintf($fh, $format_string, [$rnd,] $var);
|
|
|
|
This function (unlike the MPFR counterpart) is limited to taking
|
|
3 or 4 arguments - the filehandle, the format string, optionally a
|
|
rounding argument, and the variable to be formatted. That is, you
|
|
can printf only one variable at a time.
|
|
If there's no variable to be formatted, just add a '0' as the final
|
|
argument. ie this will work fine:
|
|
Rmpfr_fprintf($fh, "hello world\n", 0);
|
|
NOTE: The rounding argument $rnd can be provided *only* if $var is a
|
|
Math::MPFR object. To do otherwise is a fatal error.
|
|
See the mpfr documentation for details re the formatting options:
|
|
http://www.mpfr.org/mpfr-current/mpfr.html#Formatted-Output-Functions
|
|
|
|
Rmpfr_sprintf($buffer, $format_string, [$rnd,] $var, $buflen);
|
|
|
|
This function (unlike the MPFR counterpart) is limited to taking
|
|
4 or 5 arguments - the buffer, the format string, optionally a
|
|
rounding argument, the variable to be formatted and the size of the
|
|
buffer ($buflen) into which the result will be written. $buflen
|
|
must specify a size (characters) that is at least large enough to
|
|
accommodate the formatted string (including the terminating NULL).
|
|
The formatted string will be placed in $buffer.
|
|
If there's no variable to be formatted, just insert a '0' as the
|
|
value for $var. ie this will work fine:
|
|
Rmpfr_sprintf($buffer, "hello world", 0, $buflen);
|
|
NOTE: The rounding argument $rnd can be provided *only* if $var is a
|
|
Math::MPFR object. To do otherwise is a fatal error.
|
|
See the mpfr documentation for details re the formatting options:
|
|
http://www.mpfr.org/mpfr-current/mpfr.html#Formatted-Output-Functions
|
|
|
|
Rmpfr_snprintf($buffer, $bytes, $format_string, [$rnd,] $var, $buflen);
|
|
|
|
This function (unlike the MPFR counterpart) is limited to taking
|
|
5 or 6 arguments - the buffer, the number of bytes to be written,
|
|
the format string, optionally a rounding argument, the variable
|
|
to be formatted and the size of the buffer ($buflen). $buflen must
|
|
specify a size (characters) that is at least large enough to
|
|
accommodate the formatted string (including the terminating NULL).
|
|
The formatted string will be placed in $buffer.
|
|
If there's no variable to be formatted, just insert a '0' as the
|
|
value for $arg. ie this will work fine:
|
|
Rmpfr_snprintf($buffer, 12, "hello world", 0, $buflen);
|
|
NOTE: The rounding argument $rnd can be provided *only* if $var is a
|
|
Math::MPFR object. To do otherwise is a fatal error.
|
|
See the mpfr documentation for further details:
|
|
http://www.mpfr.org/mpfr-current/mpfr.html#Formatted-Output-Functions
|
|
|
|
#####################
|
|
|
|
BASE CONVERSIONS
|
|
|
|
$DBL_DIG = MPFR_DBL_DIG; # Will be undef if float.h doesn't define
|
|
# DBL_DIG.
|
|
|
|
$LDBL_DIG = MPFR_LDBL_DIG; # Will be undef if float.h doesn't define
|
|
# LDBL_DIG.
|
|
|
|
$FLT128_DIG = MPFR_FLT128_DIG; # Will be undef if quadmath.h has not
|
|
# been loaded, or quadmath.h does not
|
|
# define FLT128_DIG
|
|
.
|
|
$min_prec = mpfr_min_inter_prec($orig_base, $orig_prec, $to_base);
|
|
|
|
NOTE: $min_prec can be (very rarely) off by one if $orig_prec is in
|
|
the millions, or if either $orig_base or $to_base are
|
|
outside of the range 2..64.
|
|
|
|
Example 1:
|
|
Let's say we have some base 10 integers comprising 16 base 10
|
|
digits, and we want to represent those numbers in base 2 (binary).
|
|
What is the minimum required number of bits, such that it can be
|
|
guaranteed that converting the base 2 representations back to base
|
|
10 will result in the original 16 digit representations ?
|
|
|
|
We can calculate that minimum required precision with:
|
|
$min_prec = mpfr_min_inter_prec($orig_base, $orig_prec, $to_base);
|
|
|
|
In this example case that becomes:
|
|
$min_prec = mpfr_min_inter_prec(10, 16, 2);
|
|
which will set $min_prec to 55.
|
|
|
|
That is, so long as our base 2 representations provide at least 55
|
|
bits, we can pass 16-digit, base 10, integer values to them,
|
|
and be assured of retrieving the original base 10 representation when
|
|
we convert the base 2 representations back to base 10.
|
|
Sure ... not all 16-digit values require 55 bits, but there are some
|
|
that do ... and there are none that require more than 55 bits.
|
|
|
|
Example 2:
|
|
$min_prec = mpfr_min_inter_prec(2, 53, 10);
|
|
$min_prec is set to 17.
|
|
This tells us that a base 10 representation of a 53-bit integer needs
|
|
to comprise at least 17 digits if we are to be assured that assigning
|
|
that base 10 representation to a 53-bit integer will result in a
|
|
53-bit integer that is identical to the first.
|
|
Otherwise, there is no such assurance.
|
|
|
|
|
|
$max_prec = mpfr_max_orig_prec ($orig_base, $to_base, $to_prec);
|
|
|
|
NOTE: $max_prec can be (very rarely) off by one if $to_prec is in
|
|
the millions, or if either $orig_base or $to_base are
|
|
outside of the range 2..64.
|
|
|
|
For example:
|
|
To determine the maximum significant number of base 10 digits that
|
|
can be specified, when assigning to a 53-bit double. We have:
|
|
|
|
$max_len = mpfr_max_orig_len($orig_base, $to_base, $to_prec);
|
|
|
|
For this example that becomes:
|
|
|
|
$max_len = mpfr_max_orig_len(10, 2, 53);
|
|
|
|
which will set $max_len to 15.
|
|
That is, so long as our base 10 integer consists of no more than
|
|
15 significant digits, we can assign it to a 53-bit double and be
|
|
assured of retrieving the original value upon converting that
|
|
double back to a 15-digit base 10 representation.
|
|
Otherwise, there is no such assurance.
|
|
|
|
It is to be expected that
|
|
mpfr_max_orig_len(10, 2, 53) == DBL_DIG
|
|
and
|
|
mpfr_max_orig_len(10, 2, 113) == FLT128_DIG
|
|
and
|
|
mpfr_max_orig_len(10, 2, $long_double_prec) == LDBL_DIG
|
|
|
|
(where $long_double_prec is the precision, in bits, of the
|
|
the C 'long double' type - usually either 53 or 64 or 113.)
|
|
|
|
#####################
|
|
|
|
=head1 TODO
|
|
|
|
Look at wrapping mpfr_mp_memory_cleanup, mp_set_memory_functions
|
|
|
|
=head1 BUGS
|
|
|
|
You can get segfaults if you pass the wrong type of argument to the
|
|
functions - so if you get a segfault, the first thing to do is to
|
|
check that the argument types you have supplied are appropriate.
|
|
|
|
=head1 ACKNOWLEDGEMENTS
|
|
|
|
Thanks to Vincent Lefevre for providing corrections to errors
|
|
and omissions, and suggesting improvements (which were duly
|
|
put in place).
|
|
|
|
=head1 LICENSE
|
|
|
|
This program is free software; you may redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
Copyright 2006-2020 Sisyphus
|
|
|
|
=head1 AUTHOR
|
|
|
|
Sisyphus <sisyphus at(@) cpan dot (.) org>
|
|
|
|
=cut
|