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.
"$inex" is a signed integer value (IV) returned by many of the
mpfr functions.
$inex == 0 indicates that the function's result was exact;
$inex < 0 indicates that the function's result was rounded to a
value that is less than the exact result;
$inex > 0 indicates that the function's result was rounded to a
a value that is greater than the exact result.
"$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 bigas 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 bigas 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 precisionof your Perl's NV is less than the precision of a 'long double'.
"$f128" means a __float128. Don't use these functions unless yourPerl's NV is a __float128 && mpfr has been configured with
'--enable-float128'. (Note that versions of mpfr prior to 4.0.0
"$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)
that many of the functions require as their rounding arg. In my code, rather than providing them as a perl scalar, I usually write
them in their bareword form - MPFR_RNDN or MPFR_RNDU or ..., etc.
"$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 to $si the numeric value (0, 1, 2, 3 or 4) of the
current default rounding mode. This will initially be 0.
$inex = 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 precision $p can be any
integer between RMPFR_PREC_MIN and RMPFR_PREC_MAX.
$inex = 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:
$inex = Rmpfr_round_nearest_away(\&Rmpfr_add, $rop,
$op1, $op2);
$inex = Rmpfr_round_nearest_away(\&Rmpfr_strtofr, $rop,
'1e-200', 10);
$inex = 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).$inex = 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'.
NOTE: The new() sub can accept an argument - in which case
$rop is initialized and the given value assigned to it.
See COMBINED INITIALIZATION AND ASSIGNMENT below for
more details.
$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 to $si 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
$inex = Rmpfr_set($rop, $op, $rnd);
$inex = Rmpfr_set_ui($rop, $ui, $rnd);
$inex = Rmpfr_set_si($rop, $si, $rnd);
$inex = Rmpfr_set_sj($rop, $sj, $rnd);
$inex = Rmpfr_set_uj($rop, $uj, $rnd);
$inex = Rmpfr_set_IV($rop, $iv, $rnd);
$inex = Rmpfr_set_d ($rop, $double, $rnd);
$inex = Rmpfr_set_ld($rop, $ld, $rnd);
$inex = Rmpfr_set_NV($rop, $nv, $rnd);
$inex = Rmpfr_set_LD($rop, $LD, $rnd);
$inex = Rmpfr_set_z($rop, $z, $rnd);
$inex = Rmpfr_set_q($rop, $q, $rnd);
$inex = Rmpfr_set_f($rop, $f, $rnd);
$inex = Rmpfr_set_flt($rop, $float, $rnd);
$inex = Rmpfr_set_float16($rop, $f16, $rnd);
$inex = Rmpfr_set_float128($rop, $f128, $rnd);
$inex = Rmpfr_set_DECIMAL64($rop, $D64, $rnd);
$inex = Rmpfr_set_DECIMAL128($rop, $D128, $rnd);
$inex = Rmpfr_set_FLOAT128($rop, $F128, $rnd);
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.
Rmpfr_set_float16 is currently unavailable to 32-bit systems.
NOTE:
1) Rmpfr_set_IV requires that $iv has it's IOK flag set, and
Rmpfr_set_NV requires that $nv has its NOK flag set.
Otherwise these functions will croak.
Best to first check IOK_flag($iv) or NOK_flag($nv), both of which
will return a non-zero value if and only if the flag in question
is set.
2) Rmpfr_set_IV also handles unsigned (UV) arguments.
$inex = Rmpfr_set_ui_2exp($rop, $ui, $exp, $rnd);
$inex = Rmpfr_set_si_2exp($rop, $si, $exp, $rnd);
$inex = Rmpfr_set_uj_2exp($rop, $sj, $exp, $rnd);
$inex = Rmpfr_set_sj_2exp($rop, $sj, $exp, $rnd);
$inex = Rmpfr_set_z_2exp($rop, $z, $exp, $rnd);
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.)
$iv = 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);
$inex = Rmpfr_strtofr($rop, $str, $base, $rnd);
This function differs from Rmpfr_set_str() mainly in that it
returns the usual "exactness" ternary value ($inex).
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.
Rmpfr_set_inf($rop, $si);
Rmpfr_set_nan($rop);
Rmpfr_set_zero($rop, $si);
Set the variable $rop to infinity or NaN (Not-a-Number) or zero
respectively. In 'Rmpfr_set_inf' and 'Rmpfr_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 alreadybeen 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 made, and for rules regarding the string format.
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, $inex) = Rmpfr_init_set ($op, $rnd);
($rop, $inex) = Rmpfr_init_set_nobless($op, $rnd);
($rop, $inex) = Rmpfr_init_set_ui ($ui, $rnd);
($rop, $inex) = Rmpfr_init_set_ui_nobless($ui, $rnd);
($rop, $inex) = Rmpfr_init_set_si ($si, $rnd);
($rop, $inex) = Rmpfr_init_set_si_nobless($si, $rnd);
($rop, $inex) = Rmpfr_init_set_d ($double, $rnd);
($rop, $inex) = Rmpfr_init_set_d_nobless($double, $rnd);
($rop, $inex) = Rmpfr_init_set_ld ($ld, $rnd);
($rop, $inex) = Rmpfr_init_set_ld_nobless($ld, $rnd);
($rop, $inex) = Rmpfr_init_set_float128 ($f128, $rnd);
($rop, $inex) = Rmpfr_init_set_float128_nobless($f128, $rnd);
($rop, $inex) = Rmpfr_init_set_f ($f, $rnd);
($rop, $inex) = Rmpfr_init_set_f_nobless($f, $rnd);
($rop, $inex) = Rmpfr_init_set_z ($z, $rnd);
($rop, $inex) = Rmpfr_init_set_z_nobless($z, $rnd);
($rop, $inex) = Rmpfr_init_set_q ($q, $rnd);
($rop, $inex) = Rmpfr_init_set_q_nobless($q, $rnd);
($rop, $inex) = Rmpfr_init_set_IV ($IV,$rnd);
($rop, $inex) = Rmpfr_init_set_IV_nobless($IV,$rnd);
($rop, $inex) = Rmpfr_init_set_NV ($NV,$rnd);
($rop, $inex) = Rmpfr_init_set_NV_nobless($NV,$rnd);
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'.
($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 "mantissa" portion fo the returned
string will be presented in base $base. The "exponent" portion will
be in base 10. $digits 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 base $base digits,
prefixed with a minus sign if $op is negative), and returns the
exponent to $si as a base 10 value. There's an implicit decimal
point to the left of the first digit in $str. $digits 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.
$bool = Rmpfr_fits_ushort_p($op, $rnd);
$bool = Rmpfr_fits_sshort_p($op, $rnd);
$bool = Rmpfr_fits_uint_p($op, $rnd);
$bool = Rmpfr_fits_sint_p($op, $rnd);
$bool = Rmpfr_fits_ulong_p($op, $rnd);
$bool = Rmpfr_fits_slong_p($op, $rnd);
$bool = Rmpfr_fits_uintmax_p($op, $rnd);
$bool = Rmpfr_fits_intmax_p($op, $rnd);
$bool = Rmpfr_fits_IV_p($op, $rnd);
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);
$IV = Rmpfr_get_IV($op, $rnd);
Convert $op to an 'unsigned long long', a 'signed long', a
'signed long long', an 'unsigned long long' 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);
$NV = Rmpfr_get_NV ($op, $rnd);
$NV = Rmpfr_get_flt ($op, $rnd);
$NV = Rmpfr_get_float16($op, $rnd);
Rmpfr_get_LD($LD, $op, $rnd);
Rmpfr_get_DECIMAL64($d64, $op, $rnd);
Rmpfr_get_FLOAT128($F128, $op, $rnd);
Convert $op to a 'double', a 'long double', a '__float128', an 'NV',
a 'float', a '_Float16', a Math::LongDouble object,
''' a Math::Decimal64 object, or a Math::Float128 object using the
rounding mode $rnd.
Rmpfr_get_float16 is currently unavailable to 32-bit systems.
$double = Rmpfr_get_d1($op);
Convert $op to a double, using the default MPFR rounding mode.
THIS FUNCTION IS DEPRECATED.
Instead, do:
$double = Rmpfr_get_d($op, Rmpfr_get_default_prec());
$si = Rmpfr_get_z_exp($z, $op);
$si = Rmpfr_get_z_2exp($z, $op);
(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).
$inex = Rmpfr_get_z($z, $op, $rnd);
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.)
Croak with appropriate error message if $op is NaN or Inf.
$inex = Rmpfr_get_f ($f, $op, $rnd);
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. When built against earlier versions of mpfr,
return zero if no error occurred.
Croak with appropriate error message if $op is NaN or Inf.
Rmpfr_get_q ($q, $op);
Convert $op to a rational value. $q will be set to the exact
value contained in $op - hence no need for a rounding argument.
Croak with appropriate error message if $op is NaN or Inf.
$d = Rmpfr_get_d_2exp ($exp, $op, $rnd);
$d = Rmpfr_get_ld_2exp ($exp, $op, $rnd);
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.
$inex = Rmpfr_frexp($si, $rop, $op, $rnd);
Set $si and $rop such that 0.5<=abs($rop)<1 and $rop * (2 ** $si)
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);
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
$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
$inex = Rmpfr_add($rop, $op1, $op2, $rnd);
$inex = Rmpfr_add_ui($rop, $op, $ui, $rnd);
$inex = Rmpfr_add_si($rop, $op, $si1, $rnd);
$inex = Rmpfr_add_d($rop, $op, $double, $rnd);
$inex = Rmpfr_add_z($rop, $op, $z, $rnd);
$inex = Rmpfr_add_q($rop, $op, $q, $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.
$inex = 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.
$inex = Rmpfr_sub($rop, $op1, $op2, $rnd);
$inex = Rmpfr_sub_ui($rop, $op, $ui, $rnd);
$inex = Rmpfr_sub_z($rop, $op, $z, $rnd);
$inex = Rmpfr_z_sub($rop, $z, $op, $rnd);
$inex = Rmpfr_sub_q($rop, $op, $q, $rnd);
$inex = Rmpfr_ui_sub($rop, $ui, $op, $rnd);
$inex = Rmpfr_si_sub($rop, $si1, $op, $rnd);
$inex = Rmpfr_sub_si($rop, $op, $si1, $rnd);
$inex = Rmpfr_sub_d($rop, $op, $double, $rnd);
$inex = 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.
$inex = Rmpfr_mul($rop, $op1, $op2, $rnd);
$inex = Rmpfr_mul_ui($rop, $op, $ui, $rnd);
$inex = Rmpfr_mul_si($rop, $op, $si1, $rnd);
$inex = Rmpfr_mul_d($rop, $op, $double, $rnd);
$inex = Rmpfr_mul_z($rop, $op, $z, $rnd);
$inex = Rmpfr_mul_q($rop, $op, $q, $rnd);
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.
$inex = Rmpfr_div($rop, $op1, $op2, $rnd);
$inex = Rmpfr_div_ui($rop, $op, $ui, $rnd);
$inex = Rmpfr_ui_div($rop, $ui, $op, $rnd);
$inex = Rmpfr_div_si($rop, $op, $si1, $rnd);
$inex = Rmpfr_si_div($rop, $si1, $op, $rnd);
$inex = Rmpfr_div_d($rop, $op, $double, $rnd);
$inex = Rmpfr_d_div($rop, $double, $op, $rnd);
$inex = Rmpfr_div_z($rop, $op, $z, $rnd);
$inex = Rmpfr_z_div($rop, $z, $op, $rnd);
$inex = Rmpfr_div_q($rop, $op, $q, $rnd);
$inex = Rmpfr_q_div($rop, $q, $op, $rnd);
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.
q_add_fr($q1, $q2, $op);
Set $q1 to the exact rational value of $q2 + $op.
q_sub_fr($q1, $q2, $op);
Set $q1 to the exact rational value of $q2 - $op.
q_mul_fr($q1, $q2, $op);
Set $q1 to the exact rational value of $q2 * $op.
q_div_fr($q1, $q2, $op);
Set $q1 to the exact rational value of $q2 % p.
q_fmod_fr($q1, $q2, $op);
Set $q1 to the exact rational value of fmod($q2,$op).
$inex = Rmpfr_sqr($rop, $op, $rnd);
Set $rop to the square of $op, rounded in direction $rnd.
$inex = Rmpfr_sqrt($rop, $op, $rnd);
$inex = 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.
$inex = 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.
$inex = 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.
Set $rop to $op ** (-1 / $ui) rounded in the direction $rnd.
This function sets its $rop to the reciprocal of the $rop that
is set by Rmpfr_rootn_ui (below) for identical arguments.
May not correctly handle overflow or underflow.
$inex = Rmpfr_cbrt($rop, $op, $rnd);
Set $rop to the cubic root of $op, rounded in the direction $rnd.
$inex = Rmpfr_root($rop, $op, $ui $rnd);
This function will croak with "deprecation" warning if Math::MPFR has been built against mpfr-4.x.x or later.
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.
$inex = Rmpfr_rootn_ui($rop, $op, $ui $rnd);
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).
$inex = Rmpfr_pow_ui($rop, $op, $ui, $rnd);
$inex = Rmpfr_pow_uj($rop, $op, $uj, $rnd);
$inex = Rmpfr_pow_si($rop, $op, $si, $rnd);
$inex = Rmpfr_pow_sj($rop, $op, $sj, $rnd);
$inex = Rmpfr_pown($rop, $op, $sj, $rnd);
$inex = Rmpfr_ui_pow_ui($rop, $ui, $ui, $rnd);
$inex = Rmpfr_ui_pow($rop, $ui, $op, $rnd);
$inex = Rmpfr_pow ($rop, $op1, $op2, $rnd);
$inex = Rmpfr_pow_z ($rop, $op, $z, $rnd);
$inex = Rmpfr_pow_IV($rop, $op, $IV, $rnd);
Set $rop to 2nd arg raised to 3rd arg, rounded to the direction
$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 (ie when nan or signed inf/zero values are involved).
$inex = Rmpfr_powr($rop, $op1, $op2, $rnd);
Corresponds to the 'powr' function from IEEE 754:
$rop = exp($op2 * log($op1)) rounded to the direction $rnd
with the precision of $rop.
$inex = Rmpfr_compound ($rop, $op1, $op2, $rnd);
$inex = Rmpfr_compound_si($rop, $op1, $si, $rnd);
$rop = ($op1 + 1) ** 3rd_arg, rounded according to $rnd, to the
precision of $rop. However, there are special cases:
$rop is set to NaN when $op1 < -1;
$rop is set to 1 when $op1 is NaN and $op2 is 0;
$rop is set to +Inf when $op1 is -1 and $op2 < 0;
$rop is set to +0 when $op1 is -1 and $op2 > 0.
The other special cases follow the 'Rmpfr_pow' rules on
(1 + OP1, OP2).
$inex = 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.
$inex = 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.
$inex = 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.
$inex = Rmpfr_mul_2exp($rop, $op, $ui, $rnd);
$inex = Rmpfr_mul_2ui($rop, $op, $ui, $rnd);
$inex = 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.
$inex = Rmpfr_div_2exp($rop, $op, $ui, $rnd);
$inex = Rmpfr_div_2ui($rop, $op, $ui, $rnd);
$inex = 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);
$si = Rmpfr_cmp_ui($op, $ui);
$si = Rmpfr_cmp_si($op, $si);
$si = Rmpfr_cmp_d($op, $double);
$si = Rmpfr_cmp_ld($op, $ld);
$si = Rmpfr_cmp_float128($op, $f128);
$si = Rmpfr_cmp_z($op, $z);
$si = Rmpfr_cmp_q($op, $q);
$si = Rmpfr_cmp_f($op, $f);
$si = Rmpfr_cmp_IV($op, $iv);
$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.
NOTE:
1) Rmpfr_cmp_IV() requires that the 2nd argument has its
IOK flag set, and Rmpfr_cmp_NV() requires that the 2nd
argument has its NOK flag set.
Otherwise these functions croak.
Suggestion: first check the status of the flag using
IOK_flag($iv) or NOK_flag($nv),which return a non-zero
value if and only if the flag in question is set.
2) Rmpfr_cmp_IV handles both signed and unsigned IV args.
$si = fr_cmp_q_rounded($op, $q, $rnd);
Convert $q to an mpfr object of current default precision,
rounded in accordance with the value specified by $rnd.
Then compare $op with this mpfr object, according to the rules
specified for Rmpfr_cmp (above).
$bool = Rmpfr_total_order_p($op1, $op2);
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 reflected 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);
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
$rop = log_2 ($op);
$rop = log_10($op);
Return log2 of $op (resp. log10 of $op), set to default
precision and using default rounding mode.
These are the functions that log2 and log10 overloading would
call if log2 and log10 overloading was available.
$inex = Rmpfr_log($rop, $op, $rnd);
$inex = Rmpfr_log_ui($rop, $ui, $rnd);
$inex = Rmpfr_log2($rop, $op, $rnd);
$inex = 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.
$inex = Rmpfr_exp($rop, $op, $rnd);
$inex = Rmpfr_exp2($rop, $op, $rnd);
$inex = 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.
$rop = sind($op);
$rop = cosd($op);
Return (respectively) sin() and cos() of $op, where the
value of $op is expressed in degrees. The return value is
calculated using default precision and default rounding mode.
These are essentially the same as the overloaded sin and
cos functions except that the given argument is in degrees.
$rop = tand($op);
$rop = tangent($op);
Return tan($op) calculated with default precision and
default rounding mode.
$inex = Rmpfr_sin($rop $op, $rnd);
$inex = Rmpfr_cos($rop, $op, $rnd);
$inex = 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.
$inex = Rmpfr_cosu($rop, $op, $ui, $rnd);
$inex = Rmpfr_sinu($rop, $op, $ui, $rnd);
$inex = Rmpfr_tanu($rop, $op, $ui, $rnd);
Set $rop to the cosine (resp. sine and tangent) of $op multiplied by
2*Pi and divided by $ui. For example, if $ui equals 360, one gets
the cosine (resp. sine and tangent) for $op in degrees. For
'Rmpfr_cosu', when $op multiplied by 2 and divided by $ui is a
half-integer, the result is +0, following IEEE 754-2019 (cosPi), so
that the function is even. For 'Rmpfr_sinu', when $op multiplied by
2 and divided by $ui is an integer, the result is zero with the same
sign as $op, following IEEE 754-2019 (sinPi), so that the function
is odd. Similarly, the function 'Rmpfr_tanu' follows IEEE 754-2019
(tanPi).
$inex = Rmpfr_acosu($rop, $op, $ui, $rnd);
$inex = Rmpfr_asinu($rop, $op, $ui, $rnd);
$inex = Rmpfr_atanu($rop, $op, $ui, $rnd);
Set $rop to X multiplied by $ui and divided by 2*Pi, where X is the
arc-cosine (resp. arc-sine and arc-tangent) of $op. For example,
if $ui equals 360, mpfr_acosu yields the arc-cosine in degrees.
$inex = Rmpfr_cospi($rop, $op, $rnd);
$inex = Rmpfr_sinpi($rop, $op, $rnd);
$inex = Rmpfr_tanpi($rop, $op, $rnd);
Set $rop to the cosine (resp. sine and tangent) of $op multiplied
by Pi. See the description of 'Rmpfr_sinu', 'Rmpfr_cosu' and
'Rmpfr_tanu' for special values.
$inex = Rmpfr_acospi($rop, $op, $rnd);
$inex = Rmpfr_asinpi($rop, $op, $rnd);
$inex = Rmpfr_atanpi($rop, $op, $rnd);
$rop = acos($op)/Pi, resp. asin($op)/Pi and atan($op)/Pi.
$inex = 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.
$inex = Rmpfr_acos($rop, $op, $rnd);
$inex = Rmpfr_asin($rop, $op, $rnd);
$inex = 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.
$inex = 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.
$inex = Rmpfr_atan2u($rop, $op1, $op2, $ui, $rnd);
Same as taking the Rmpfr_atan2() result and multiplying it
by $ui/(2*Pi).
$inex = Rmpfr_atan2pi($rop, $op1, $op2, $rnd);
Same as Rmpfr_atan2u() with $ui = 2.
$inex = Rmpfr_cosh($rop, $op, $rnd);
$inex = Rmpfr_sinh($rop, $op, $rnd);
$inex = 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.
$inex = Rmpfr_acosh($rop, $op, $rnd);
$inex = Rmpfr_asinh($rop, $op, $rnd);
$inex = 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.
$inex = Rmpfr_sec ($rop, $op, $rnd);
$inex = Rmpfr_csc ($rop, $op, $rnd);
$inex = 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.
$inex = Rmpfr_sech ($rop, $op, $rnd);
$inex = Rmpfr_csch ($rop, $op, $rnd);
$inex = 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.
$inex = Rmpfr_fac_ui($rop, $ui, $rnd);
Set $rop to the factorial of $ui, rounded to the direction
$rnd with the precision of $rop.
$inex = Rmpfr_log1p ($rop, $op, $rnd);
$inex = Rmpfr_log2p1 ($rop, $op, $rnd);
$inex = Rmpfr_log10p1($rop, $op, $rnd);
In Rmpfr_log1p set $rop = log( $op + 1).
In Rmpfr_log2p1 set $rop = log2( $op + 1).
In Rmpfr_log10p1 set $rop = log10($op + 1).
In all three cases, round the result in the
direction $rnd to the precision of $rop.
$inex = Rmpfr_expm1 ($rop, $op, $rnd);
$inex = Rmpfr_exp2m1 ($rop, $op, $rnd);
$inex = Rmpfr_exp10m1($rop, $op, $rnd);
In Rmpfr_expm1, set $rop to the exponential of $op followed
by a subtraction of 1. $rop = (e ** $op) - 1.
In Rmpfr_exp2p1, set $rop = (2 ** $op) - 1.
In Rmpfr_exp10p1, set $rop = (10 ** $op) - 1.
For all three, the result is rounded to the direction $rnd
with the precision of $rop.
$inex = Rmpfr_fma($rop, $op1, $op2, $op3, $rnd);
Set $rop to $op1 * $op2 + $op3, rounded to the direction $rnd.
$inex = 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.
$inex = Rmpfr_fms($rop, $op1, $op2, $op3, $rnd);
Set $rop to $op1 * $op2 - $op3, rounded to the direction $rnd.
$inex = 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.
$inex = 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.
$inex = 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.
$inex = Rmpfr_ai($rop, $op, $rnd);
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.
$inex = 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.
$inex = 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.
$inex = 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.
inex = 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);
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()
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).
$inex = Rmpfr_beta($rop, $op1, $op2, $rnd);
Set $rop to the beta function at $op1, $op2, rounded
according to $rnd.
$inex = Rmpfr_gamma($rop, $op, $rnd);
$inex = 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.
$inex = Rmpfr_gamma_inc($rop, $op1, $op2, $rnd);
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.
$inex = Rmpfr_digamma($rop, $op, $rnd);
Set $rop to digammma($op), rounded according to $rnd.
$inex = Rmpfr_trigamma ($rop, $op, $rnd);
Set $rop to trigammma($op), rounded according to $rnd.
$inex = Rmpfr_zeta($rop, $op, $rnd);
$inex = 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.
$inex = 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.
$inex = 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.
$inex = Rmpfr_j0 ($rop, $op, $rnd);
$inex = Rmpfr_j1 ($rop, $op, $rnd);
$inex = 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.
$inex = Rmpfr_y0 ($rop, $op, $rnd);
$inex = Rmpfr_y1 ($rop, $op, $rnd);
$inex = 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.
$inex = 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.)
$inex = 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.
$inex = Rmpfr_dot ($rop, \@op1, \@op2, $ui, $rnd);
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.
$si = Rmpfr_fpif_export ($stream, $op);
$si = Rmpfr_fpif_export ($op, $stream);
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.
DISPLAYING INFS AND NANS
Generally, these will be displayed as 'Inf', '-Inf' and 'NaN'.
However, if you set $Math::MPFR::PERL_INFNAN to a TRUE value,
then nvtoa($num) and numtoa($num) (which are documented below
in 'MISCELLANEOUS') will display them in the same way that perl
itself displays them.
Note that nvtoa() and numtoa() expect a plain numeric perl
scalar as their argument - not a Math::MPFR object.
$Math::MPFR::PERL_INFNAN has the initial (default) value of 0.
EXCEPTIONS
$inex = 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
$si = Rmpfr_get_emin();
$si = Rmpfr_get_emax();
Return to $si 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 to $si 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.
$inex = Rmpfr_check_range($op, $si, $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 $si is the corresponding ternary value. Thus $si
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
$si 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 $inex 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();
Rmpfr_clear_underflow();
Rmpfr_clear_overflow();
Rmpfr_clear_nanflag();
Rmpfr_clear_inexflag();
Rmpfr_clear_erangeflag();
Rmpfr_clear_divby0();
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();
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);
Rmpfr_flags_set($mask);
$mask2 = Rmpfr_flags_test($mask);
$mask = Rmpfr_flags_save();
Rmpfr_flags_restore($mask1, $mask2);
$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
$rop = nv2mpfr($sv);
Return a new Math::MMPFR object whose value is the same as that
held by $sv, with the same precision as that of $Config{nvtype}.
$str = doubletoa($double [, $x]);
Sets $str to the value of $double.
$str will appear in standard decimal format such that the
condition ($str == $double) 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 it falls back to returning
sprintf("%.17g", $double).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.
$str = nvtoa($NV);
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
assignment 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
assignment of 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.
$str = mpfrtoa($op [, $uv]);
As for nvtoa(), except that mpfrtoa() instead takes a Math::MPFR
object as its argument.
Sets $str to the value of $op.
$str will appear in standard decimal format, containing the
*minimum* number of significant digits such that the condition
($str == $op) is true when the current default precision equals
the precision of $op.
(The overloaded '==' operator evaluates $str according to the
current default precision, so that condition might be untrue
whenever the default precision != the precision of $op.)
The second (optional) arg became available with Math-MPFR-4.24 and
it can alter the behaviour of mpfrtoa when the value of $uv is
greater than the precision of $op. AFAIK, it is used only (and
arcanely in Math:FakeDD::dd_repro(), and the option will be removed
as soon as Math::FakeDD::dd_repro() can be adapted to that removal.