Miscellaneous Functions (GNU MPFR 4.2.1)
Description: How to install and use GNU MPFR, a library for reliable multiple precision floating-point arithmetic, version 4.2.1.

### 5.12 Miscellaneous Functions

Function: `void` mpfr_nexttoward `(mpfr_t x, mpfr_t y)` ¶

  If x or y is NaN, set x to NaN; note that the NaN flag is set as usual. If x and y are equal, x is unchanged. Otherwise, if x is different from y, replace x by the next floating-point number (with the precision of x and the current exponent range) in the direction of y (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, overflow, or inexact exception is raised.

  Note: Concerning the exceptions and the sign of 0, the behavior differs from the ISO C `nextafter` and `nexttoward` functions. It is similar to the nextUp and nextDown operations from IEEE 754 (introduced in its 2008 revision).

Function: `void` mpfr_nextabove `(mpfr_t x)` ¶
Function: `void` mpfr_nextbelow `(mpfr_t x)` ¶

  Equivalent to `mpfr_nexttoward` where y is +Inf (resp. −Inf).

Function: `int` mpfr_min `(mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_max `(mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_rnd_t rnd)` ¶

  Set rop to the minimum (resp. 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 (resp. +0). As usual, the NaN flag is set only when the result is NaN, i.e., when both op1 and op2 are NaN.

  Note: These functions correspond to the minimumNumber and maximumNumber operations of IEEE 754-2019 for the result. But in MPFR, the NaN flag is set only when both operands are NaN.

Function: `int` mpfr_urandomb `(mpfr_t rop, gmp_randstate_t state)` ¶

  Generate a uniformly distributed random float in the interval 0 <= rop < 1. More precisely, the number can be seen as a float with a random non-normalized significand and exponent 0, which is then normalized (thus if e denotes the exponent after normalization, then the least −e significant bits of the significand are always 0).

  Return 0, unless the exponent is not in the current exponent range, in which case rop is set to NaN and a non-zero value is returned (this should never happen in practice, except in very specific cases). The second argument is a `gmp_randstate_t` structure, which should be created using the GMP `gmp_randinit` function (see the GMP manual).

  Note: for a given version of MPFR, the returned value of rop and the new value of state (which controls further random values) do not depend on the machine word size.

Function: `int` mpfr_urandom `(mpfr_t rop, gmp_randstate_t state, mpfr_rnd_t rnd)` ¶

  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.

  The second argument is a `gmp_randstate_t` structure, which should be created using the GMP `gmp_randinit` function (see the GMP manual).

  Note: the note for `mpfr_urandomb` holds too. Moreover, the exact number (the random value to be rounded) and the next random state do not depend on the current exponent range and the rounding mode. However, they depend on the target precision: from the same state of the random generator, if the precision of the destination is changed, then the value may be completely different (and the state of the random generator is different too).

Function: `int` mpfr_nrandom `(mpfr_t rop1, gmp_randstate_t state, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_grandom `(mpfr_t rop1, mpfr_t rop2, gmp_randstate_t state, mpfr_rnd_t rnd)` ¶

  Generate one (possibly two for `mpfr_grandom`) random floating-point number according to a standard normal Gaussian distribution (with mean zero and variance one). For `mpfr_grandom`, if rop2 is a null pointer, then only one value is generated and stored in rop1.

  The floating-point number 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.

  The `gmp_randstate_t` argument should be created using the GMP `gmp_randinit` function (see the GMP manual).

  For `mpfr_grandom`, the combination of the ternary values is returned like with `mpfr_sin_cos`. If rop2 is a null pointer, the second ternary value is assumed to be 0 (note that the encoding of the only ternary value is not the same as the usual encoding for functions that return only one result). Otherwise the ternary value of a random number is always non-zero.

  Note: the note for `mpfr_urandomb` holds too. In addition, the exponent range and the rounding mode might have a side effect on the next random state.

  Note: `mpfr_nrandom` is much more efficient than `mpfr_grandom`, especially for large precision. Thus `mpfr_grandom` is marked as deprecated and will be removed in a future release.

Function: `int` mpfr_erandom `(mpfr_t rop1, gmp_randstate_t state, mpfr_rnd_t rnd)` ¶

  Generate one random floating-point number according to an exponential distribution, with mean one. Other characteristics are identical to `mpfr_nrandom`.

Function: `mpfr_exp_t` mpfr_get_exp `(mpfr_t x)` ¶

  Return the exponent of x, assuming that x is a non-zero ordinary number and the significand is considered in [1/2,1). For this function, x is allowed to be outside of the current range of acceptable values. The behavior for NaN, infinity or zero is undefined.

Function: `int` mpfr_set_exp `(mpfr_t x, mpfr_exp_t e)` ¶

  Set the exponent of x to e if x is a non-zero ordinary number and e is in the current exponent range, and return 0; otherwise, return a non-zero value (x is not changed).

Function: `int` mpfr_signbit `(mpfr_t op)` ¶

  Return a non-zero value iff op has its sign bit set (i.e., if it is negative, −0, or a NaN whose representation has its sign bit set).

Function: `int` mpfr_setsign `(mpfr_t rop, mpfr_t op, int s, mpfr_rnd_t rnd)` ¶

  Set the value of rop from op, rounded toward the given direction rnd, then set (resp. clear) its sign bit if s is non-zero (resp. zero), even when op is a NaN.

Function: `int` mpfr_copysign `(mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_rnd_t rnd)` ¶

  Set the value of rop from op1, rounded toward 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 `mpfr_setsign (rop, op1, mpfr_signbit (op2), rnd)`.

Function: `const char *` mpfr_get_version `(void)` ¶

  Return the MPFR version, as a null-terminated string.

Macro: MPFR_VERSION ¶
Macro: MPFR_VERSION_MAJOR ¶
Macro: MPFR_VERSION_MINOR ¶
Macro: MPFR_VERSION_PATCHLEVEL ¶
Macro: MPFR_VERSION_STRING ¶

  `MPFR_VERSION` is the version of MPFR as a preprocessing constant. `MPFR_VERSION_MAJOR`, `MPFR_VERSION_MINOR` and `MPFR_VERSION_PATCHLEVEL` are respectively the major, minor and patch level of MPFR version, as preprocessing constants. `MPFR_VERSION_STRING` is the version (with an optional suffix, used in development and pre-release versions) as a string constant, which can be compared to the result of `mpfr_get_version` to check at run time the header file and library used match:

      if (strcmp (mpfr_get_version (), MPFR_VERSION_STRING))
        fprintf (stderr, "Warning: header and library do not match\n");

  Note: Obtaining different strings is not necessarily an error, as in general, a program compiled with some old MPFR version can be dynamically linked with a newer MPFR library version (if allowed by the library versioning system).

Macro: `long` MPFR_VERSION_NUM `(major, minor, patchlevel)` ¶

  Create an integer in the same format as used by `MPFR_VERSION` from the given major, minor and patchlevel. Here is an example of how to check the MPFR version at compile time:

      #if (!defined(MPFR_VERSION) || (MPFR_VERSION < MPFR_VERSION_NUM(3,0,0)))
      # error "Wrong MPFR version."
      #endif

Function: `const char *` mpfr_get_patches `(void)` ¶

  Return a null-terminated 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 identifiers of the patches applied to the old (compile-time) MPFR version are not available (however, this information should not have much interest in general).

Function: `int` mpfr_buildopt_tls_p `(void)` ¶

  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, see `INSTALL` file), return zero otherwise.

Function: `int` mpfr_buildopt_float128_p `(void)` ¶

  Return a non-zero value if MPFR was compiled with ‘`_Float128`’ support (that is, MPFR was built with the ‘`--enable-float128`’ configure option), return zero otherwise.

Function: `int` mpfr_buildopt_decimal_p `(void)` ¶

  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.

Function: `int` mpfr_buildopt_gmpinternals_p `(void)` ¶

  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.

Function: `int` mpfr_buildopt_sharedcache_p `(void)` ¶

  Return a non-zero value if MPFR was compiled so that all threads share the same cache for 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. If the return value is non-zero, MPFR applications may need to be compiled with the ‘`-pthread`’ option.

Function: `const char *` mpfr_buildopt_tune_case `(void)` ¶

  Return a string saying which thresholds file has been used at compile time. This file is normally selected from the processor type.