4.5 Floating-Point Values on Special Numbers

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 Section “Rounding Modes” (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 Special Functions), since for any finite or infinite input x, mpfr_hypot on (x,+Inf) gives +Inf.