Next: Input and Output Functions, Previous: Comparison Functions, Up: MPFR Interface [Index]
All those functions, except explicitly stated (for example
mpfr_sin_cos), return a ternary value, i.e., zero for an
exact return value, a positive value for a return value larger than the
exact result, and a negative value otherwise.
Important note: In some domains, computing transcendental functions
(even more with correct rounding) is expensive, even in small precision,
for example the trigonometric and Bessel functions with a large argument.
For some functions, the algorithm complexity and memory usage does not
depend only on the output precision: for instance, the memory usage of
mpfr_rootn_ui is also linear in the argument k, and the
memory usage of the incomplete Gamma function also depends on the
precision of the input op. It is also theoretically possible that
some functions on some particular inputs might be very hard to round
(i.e. the Table Maker’s Dilemma occurs in much larger precisions than
normally expected from the context), meaning that the internal precision
needs to be increased even more; but it is conjectured that the needed
precision has a reasonable bound (and in particular, that potentially
exact cases are known and can be detected efficiently).
Set rop to the natural logarithm of op, log2(op) or log10(op), respectively, rounded in the direction rnd. Set rop to +0 if op is 1 (in all rounding modes), for consistency with the ISO C99 and IEEE 754 standards. Set rop to −Inf if op is ±0 (i.e., the sign of the zero has no influence on the result).
Set rop to the logarithm of one plus op (in radix two for
mpfr_log2p1, and in radix ten for mpfr_log10p1), rounded in the
direction rnd.
Set rop to −Inf if op is −1.
Set rop to the exponential of op, to 2 power of op or to 10 power of op, respectively, rounded in the direction rnd.
Set rop to the exponential of op followed by a subtraction by one (resp. 2 power of op followed by a subtraction by one, and 10 power of op followed by a subtraction by one), rounded in the direction rnd.
Set rop to op1 raised to op2,
rounded in the direction rnd.
The mpfr_powr function corresponds to the powr function
from IEEE 754, i.e., it computes the exponential of
op2 multiplied by the logarithm of op1.
The mpfr_pown function is just an alias for mpfr_pow_sj
(defined with #define mpfr_pown mpfr_pow_sj), to follow the
C2x function pown.
Special values are handled as described in the ISO C99 and IEEE 754
standards for the pow function:
pow(±0, y) returns ±Inf for y a negative odd integer.
pow(±0, y) returns +Inf for y negative and not an odd integer.
pow(±0, y) returns ±0 for y a positive odd integer.
pow(±0, y) returns +0 for y positive and not an odd integer.
pow(-1, ±Inf) returns 1.
pow(+1, y) returns 1 for any y, even a NaN.
pow(x, ±0) returns 1 for any x, even a NaN.
pow(x, y) returns NaN for finite negative x and finite non-integer y.
pow(x, -Inf) returns +Inf for 0 < abs(x) < 1, and +0 for abs(x) > 1.
pow(x, +Inf) returns +0 for 0 < abs(x) < 1, and +Inf for abs(x) > 1.
pow(-Inf, y) returns −0 for y a negative odd integer.
pow(-Inf, y) returns +0 for y negative and not an odd integer.
pow(-Inf, y) returns −Inf for y a positive odd integer.
pow(-Inf, y) returns +Inf for y positive and not an odd integer.
pow(+Inf, y) returns +0 for y negative, and +Inf for y positive.
Note: When 0 is of integer type, it is regarded as +0 by these functions.
We do not use the usual limit rules in this case, as these rules are not
used for pow.
Set rop to the power n of one plus op, following IEEE 754 for the special cases and exceptions. When n is zero and op is NaN or greater or equal to −1, rop is set to 1.
Set rop to the cosine of op, sine of op, tangent of op, rounded in the direction rnd.
Set rop to the cosine (resp. sine and tangent) of
op multiplied by 2 Pi and divided
by u. For example, if u equals 360, one gets the cosine
(resp. sine and tangent) for op in degrees. For mpfr_cosu, when
op multiplied by 2 and divided by u
is a half-integer, the result is +0, following IEEE 754 (cosPi),
so that the function is even. For mpfr_sinu, when
op multiplied by 2 and divided by u
is an integer, the result is zero with the same sign as op, following
IEEE 754 (sinPi), so that the function is odd.
Similarly, the function mpfr_tanu follows IEEE 754 (tanPi).
Set rop to the cosine (resp. sine and tangent) of
op multiplied by Pi. See the description of
mpfr_sinu, mpfr_cosu and mpfr_tanu for special values.
Set simultaneously sop to the sine of op and cop to the cosine of op, rounded in the direction rnd with the corresponding precisions of sop and cop, which must be different variables. Return 0 iff both results are exact, more precisely it returns s + 4c where s = 0 if sop is exact, s = 1 if sop is larger than the sine of op, s = 2 if sop is smaller than the sine of op, and similarly for c and the cosine of op.
Set rop to the secant of op, cosecant of op, cotangent of op, rounded in the direction rnd.
Set rop to the arc-cosine, arc-sine or arc-tangent of op,
rounded in the direction rnd.
Note that since acos(-1) returns the floating-point number closest to
Pi according to the given rounding mode, this number might not be
in the output range 0 <= rop < Pi
of the arc-cosine function;
still, the result lies in the image of the output range
by the rounding function.
The same holds for asin(-1), asin(1), atan(-Inf),
atan(+Inf) or for atan(op) with large op and
small precision of rop.
Set rop to a multiplied
by u and divided by 2 Pi, where a is the arc-cosine
(resp. arc-sine and arc-tangent) of op.
For example, if u equals 360, mpfr_acosu yields the arc-cosine in
degrees.
Set rop to acos(op) (resp. asin(op) and
atan(op)) divided by Pi.
For mpfr_atan2, set rop to the arc-tangent2 of y and
x, rounded in the direction rnd:
if x > 0, then atan2(y, x) returns
atan(y/x);
if x < 0, then atan2(y, x) returns
the sign
of y multiplied by Pi − atan(abs(y/x)),
thus a number from −Pi to Pi.
As for atan, in case the exact mathematical result is +Pi or
−Pi,
its rounded result might be outside the function output range.
The function mpfr_atan2u behaves similarly, except the result is
multiplied by u and divided by 2 Pi; and
mpfr_atan2pi is the same as mpfr_atan2u with u = 2.
For example, if u equals 360, mpfr_atan2u returns the
arc-tangent in degrees, with values from −180 to 180.
atan2(y, 0) does not raise any floating-point exception.
Special values are handled as described in the ISO C99 and IEEE 754
standards for the atan2 function:
atan2(+0, -0) returns +Pi.
atan2(-0, -0) returns −Pi.
atan2(+0, +0) returns +0.
atan2(-0, +0) returns −0.
atan2(+0, x) returns +Pi for x < 0.
atan2(-0, x) returns −Pi for x < 0.
atan2(+0, x) returns +0 for x > 0.
atan2(-0, x) returns −0 for x > 0.
atan2(y, 0) returns −Pi/2 for y < 0.
atan2(y, 0) returns +Pi/2 for y > 0.
atan2(+Inf, -Inf) returns +3*Pi/4.
atan2(-Inf, -Inf) returns −3*Pi/4.
atan2(+Inf, +Inf) returns +Pi/4.
atan2(-Inf, +Inf) returns −Pi/4.
atan2(+Inf, x) returns +Pi/2 for finite x.
atan2(-Inf, x) returns −Pi/2 for finite x.
atan2(y, -Inf) returns +Pi for finite y > 0.
atan2(y, -Inf) returns −Pi for finite y < 0.
atan2(y, +Inf) returns +0 for finite y > 0.
atan2(y, +Inf) returns −0 for finite y < 0.
Set rop to the hyperbolic cosine, sine or tangent of op, rounded in the direction rnd.
Set simultaneously sop to the hyperbolic sine of op and
cop to the hyperbolic cosine of op,
rounded in the direction rnd with the corresponding precision of
sop and cop, which must be different variables.
Return 0 iff both results are exact (see mpfr_sin_cos for a more
detailed description of the return value).
Set rop to the hyperbolic secant of op, cosecant of op, cotangent of op, rounded in the direction rnd.
Set rop to the inverse hyperbolic cosine, sine or tangent of op, rounded in the direction rnd.
Set rop to the exponential integral of op, rounded in the direction rnd. This is the sum of Euler’s constant, of the logarithm of the absolute value of op, and of the sum for k from 1 to infinity of op to the power k, divided by k and the factorial of k. For positive op, it corresponds to the Ei function at op (see formula 5.1.10 from the Handbook of Mathematical Functions from Abramowitz and Stegun), and for negative op, to the opposite of the E1 function (sometimes called eint1) at −op (formula 5.1.1 from the same reference).
Set rop to real part of the dilogarithm of op, rounded in the direction rnd. MPFR defines the dilogarithm function as the integral of −log(1−t)/t from 0 to op.
Set rop to the value of the Gamma function on op, resp. the
incomplete Gamma function on op and op2,
rounded in the direction rnd.
(In the literature, mpfr_gamma_inc is called upper
incomplete Gamma function,
or sometimes complementary incomplete Gamma function.)
For mpfr_gamma (and mpfr_gamma_inc when op2 is zero),
when op is a negative integer, rop is set to NaN.
Note: the current implementation of mpfr_gamma_inc is slow for
large values of rop or op, in which case some internal overflow
might also occur.
Set rop to the value of the logarithm of the Gamma function on op,
rounded in the direction rnd.
When op is 1 or 2, set rop to +0 (in all rounding modes).
When op is an infinity or a non-positive integer, set rop to
+Inf, following the general rules on special values.
When −2k − 1 < op < −2k,
k being a non-negative integer, set rop to NaN.
See also mpfr_lgamma.
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 the object pointed to by signp. When op is 1 or 2, set rop to +0 (in all rounding modes). When op is an infinity or a non-positive integer, set rop to +Inf. When op is NaN, −Inf or a negative integer, *signp is undefined, and when op is ±0, *signp is the sign of the zero.
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.
Set rop to the value of the Beta function at arguments op1 and op2. Note: the current code does not try to avoid internal overflow or underflow, and might use a huge internal precision in some cases.
Set rop to the value of the Riemann Zeta function on op, rounded in the direction rnd.
Set rop to the value of the error function on op (resp. the complementary error function on op) rounded in the direction rnd.
Set rop to the value of the first kind Bessel function of order 0, (resp. 1 and n) on op, rounded in the direction rnd. When op is NaN, rop is always set to NaN. When op is positive or negative infinity, rop is set to +0. When op is zero, and n is not zero, rop is set to +0 or −0 depending on the parity and sign of n, and the sign of op.
Set rop to the value of the second kind Bessel function of order 0 (resp. 1 and n) 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 set to +0. When op is zero, rop is set to +Inf or −Inf depending on the parity and sign of n.
Set rop to the arithmetic-geometric mean of op1 and op2, rounded in the direction rnd. The arithmetic-geometric mean is the common limit of the sequences u_n and v_n, where u_0 = op1, v_0 = op2, u_(n+1) is the arithmetic mean of u_n and v_n, and v_(n+1) is the geometric mean of u_n and v_n. If any operand is negative and the other one is not zero, set rop to NaN. If any operand is zero and the other one is finite (resp. infinite), set rop to +0 (resp. NaN).
Set rop to the value of the Airy function Ai on x, rounded in the direction rnd. When x is NaN, rop is always set to NaN. When x is +Inf or −Inf, rop is +0. The current implementation is not intended to be used with large arguments. It works with abs(x) typically smaller than 500. For larger arguments, other methods should be used and will be implemented in a future version.
Set rop to the logarithm of 2, the value of Pi,
of Euler’s constant 0.577…, of Catalan’s constant 0.915…,
respectively, rounded in the direction
rnd. These functions cache the computed values to avoid other
calculations if a lower or equal precision is requested. To free these caches,
use mpfr_free_cache or mpfr_free_cache2.
Next: Input and Output Functions, Previous: Comparison Functions, Up: MPFR Interface [Index]