Next: Exceptions, Previous: Rounding, Up: MPFR Basics [Index]
This section specifies the floating-point values (of type mpfr_t)
returned by MPFR functions (where by “returned” we mean here the modified
value of the destination object, which should not be mixed with the ternary
return value of type int of those functions).
For functions returning several values (like
mpfr_sin_cos), the rules apply to each result separately.
Functions can have one or several input arguments. An input point is a mapping from these input arguments to the set of the MPFR numbers. When none of its components are NaN, an input point can also be seen as a tuple in the extended real numbers (the set of the real numbers with both infinities).
When the input point is in the domain of the mathematical function, the result is rounded as described in Rounding (but see below for the specification of the sign of an exact zero). Otherwise the general rules from this section apply unless stated otherwise in the description of the MPFR function (MPFR Interface).
When the input point is not in the domain of the mathematical function
but is in its closure in the extended real numbers and the function can
be extended by continuity, the result is the obtained limit.
Examples: mpfr_hypot on (+Inf,0) gives +Inf. But
mpfr_pow cannot be defined on (1,+Inf) using this rule, as
one can find sequences (x_n,y_n)
such that x_n goes to 1, y_n goes
to +Inf and x_n to the y_n
goes to any positive value when n goes to the infinity.
When the input point is in the closure of the domain of the mathematical
function and an input argument is +0 (resp. −0), one considers
the limit when the corresponding argument approaches 0 from above
(resp. below), if possible. If the limit is not defined (e.g.,
mpfr_sqrt and mpfr_log on −0), the behavior is
specified in the description of the MPFR function, but must be consistent
with the rule from the above paragraph (e.g., mpfr_log on ±0
gives −Inf).
When the result is equal to 0, its sign is determined by considering the
limit as if the input point were not in the domain: If one approaches 0
from above (resp. below), the result is +0 (resp. −0);
for example, mpfr_sin on −0 gives −0 and
mpfr_acos on 1 gives +0 (in all rounding modes).
In the other cases, the sign is specified in the description of the MPFR
function; for example mpfr_max on −0 and +0 gives +0.
When the input point is not in the closure of the domain of the function,
the result is NaN. Example: mpfr_sqrt on −17 gives NaN.
When an input argument is NaN, the result is NaN, possibly except when
a partial function is constant on the finite floating-point numbers;
such a case is always explicitly specified in MPFR Interface.
Example: mpfr_hypot on (NaN,0) gives NaN, but mpfr_hypot
on (NaN,+Inf) gives +Inf (as specified in
Transcendental Functions), since for any finite or infinite
input x, mpfr_hypot on (x,+Inf) gives +Inf.
MPFR also tries to follow the specifications of the IEEE 754 standard on special values (IEEE 754 agree with the above rules in most cases). Any difference with IEEE 754 that is not explicitly mentioned, other than those due to the single NaN, is unintended and might be regarded as a bug. See also MPFR and the IEEE 754 Standard.
Next: Exceptions, Previous: Rounding, Up: MPFR Basics [Index]