|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
|
<html>
|
|
|
<!-- This manual documents how to install and use the Multiple Precision
|
|
|
Floating-Point Reliable Library, version 3.1.4.
|
|
|
|
|
|
Copyright 1991, 1993-2016 Free Software Foundation, Inc.
|
|
|
|
|
|
Permission is granted to copy, distribute and/or modify this document under
|
|
|
the terms of the GNU Free Documentation License, Version 1.2 or any later
|
|
|
version published by the Free Software Foundation; with no Invariant Sections,
|
|
|
with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the
|
|
|
license is included in GNU Free Documentation License. -->
|
|
|
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
|
|
|
<head>
|
|
|
<title>Miscellaneous Functions (GNU MPFR 3.1.4)</title>
|
|
|
|
|
|
<meta name="description" content="How to install and use GNU MPFR, a library for reliable multiple precision
|
|
|
floating-point arithmetic, version 3.1.4.">
|
|
|
<meta name="keywords" content="Miscellaneous Functions (GNU MPFR 3.1.4)">
|
|
|
<meta name="resource-type" content="document">
|
|
|
<meta name="distribution" content="global">
|
|
|
<meta name="Generator" content="makeinfo">
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
|
<link href="index.html#Top" rel="start" title="Top">
|
|
|
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
|
|
|
<link href="MPFR-Interface.html#MPFR-Interface" rel="up" title="MPFR Interface">
|
|
|
<link href="Exception-Related-Functions.html#Exception-Related-Functions" rel="next" title="Exception Related Functions">
|
|
|
<link href="Rounding-Related-Functions.html#Rounding-Related-Functions" rel="prev" title="Rounding Related Functions">
|
|
|
<style type="text/css">
|
|
|
<!--
|
|
|
a.summary-letter {text-decoration: none}
|
|
|
blockquote.indentedblock {margin-right: 0em}
|
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
|
|
blockquote.smallquotation {font-size: smaller}
|
|
|
div.display {margin-left: 3.2em}
|
|
|
div.example {margin-left: 3.2em}
|
|
|
div.lisp {margin-left: 3.2em}
|
|
|
div.smalldisplay {margin-left: 3.2em}
|
|
|
div.smallexample {margin-left: 3.2em}
|
|
|
div.smalllisp {margin-left: 3.2em}
|
|
|
kbd {font-style: oblique}
|
|
|
pre.display {font-family: inherit}
|
|
|
pre.format {font-family: inherit}
|
|
|
pre.menu-comment {font-family: serif}
|
|
|
pre.menu-preformatted {font-family: serif}
|
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
|
|
pre.smallexample {font-size: smaller}
|
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
|
|
pre.smalllisp {font-size: smaller}
|
|
|
span.nolinebreak {white-space: nowrap}
|
|
|
span.roman {font-family: initial; font-weight: normal}
|
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
|
|
ul.no-bullet {list-style: none}
|
|
|
-->
|
|
|
</style>
|
|
|
|
|
|
|
|
|
</head>
|
|
|
|
|
|
<body lang="en">
|
|
|
<a name="Miscellaneous-Functions"></a>
|
|
|
<div class="header">
|
|
|
<p>
|
|
|
Next: <a href="Exception-Related-Functions.html#Exception-Related-Functions" accesskey="n" rel="next">Exception Related Functions</a>, Previous: <a href="Rounding-Related-Functions.html#Rounding-Related-Functions" accesskey="p" rel="prev">Rounding Related Functions</a>, Up: <a href="MPFR-Interface.html#MPFR-Interface" accesskey="u" rel="up">MPFR Interface</a> [<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
|
|
|
</div>
|
|
|
<hr>
|
|
|
<a name="index-Miscellaneous-float-functions"></a>
|
|
|
<a name="Miscellaneous-Functions-1"></a>
|
|
|
<h3 class="section">5.12 Miscellaneous Functions</h3>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fnexttoward"></a>Function: <em>void</em> <strong>mpfr_nexttoward</strong> <em>(mpfr_t <var>x</var>, mpfr_t <var>y</var>)</em></dt>
|
|
|
<dd><p>If <var>x</var> or <var>y</var> is NaN, set <var>x</var> to NaN. If <var>x</var> and <var>y</var>
|
|
|
are equal, <var>x</var> is unchanged. Otherwise, if <var>x</var>
|
|
|
is different from <var>y</var>, replace <var>x</var> by the next floating-point
|
|
|
number (with the precision of <var>x</var> and the current exponent range)
|
|
|
in the direction of <var>y</var>
|
|
|
(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 or
|
|
|
overflow is generated.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fnextabove"></a>Function: <em>void</em> <strong>mpfr_nextabove</strong> <em>(mpfr_t <var>x</var>)</em></dt>
|
|
|
<dt><a name="index-mpfr_005fnextbelow"></a>Function: <em>void</em> <strong>mpfr_nextbelow</strong> <em>(mpfr_t <var>x</var>)</em></dt>
|
|
|
<dd><p>Equivalent to <code>mpfr_nexttoward</code> where <var>y</var> is plus infinity
|
|
|
(resp. minus infinity).
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fmin"></a>Function: <em>int</em> <strong>mpfr_min</strong> <em>(mpfr_t <var>rop</var>, mpfr_t <var>op1</var>, mpfr_t <var>op2</var>, mpfr_rnd_t <var>rnd</var>)</em></dt>
|
|
|
<dt><a name="index-mpfr_005fmax"></a>Function: <em>int</em> <strong>mpfr_max</strong> <em>(mpfr_t <var>rop</var>, mpfr_t <var>op1</var>, mpfr_t <var>op2</var>, mpfr_rnd_t <var>rnd</var>)</em></dt>
|
|
|
<dd><p>Set <var>rop</var> to the minimum (resp. maximum)
|
|
|
of <var>op1</var> and <var>op2</var>. If <var>op1</var>
|
|
|
and <var>op2</var> are both NaN, then <var>rop</var> is set to NaN. If <var>op1</var>
|
|
|
or <var>op2</var> is NaN, then <var>rop</var> is set to the numeric value. If
|
|
|
<var>op1</var> and <var>op2</var> are zeros of different signs, then <var>rop</var>
|
|
|
is set to −0 (resp. +0).
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005furandomb"></a>Function: <em>int</em> <strong>mpfr_urandomb</strong> <em>(mpfr_t <var>rop</var>, gmp_randstate_t <var>state</var>)</em></dt>
|
|
|
<dd><p>Generate a uniformly distributed random float in the interval
|
|
|
<em>0 <= <var>rop</var> < 1</em>. 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 <var>e</var> denotes the exponent after normalization, then
|
|
|
the least <em>-<var>e</var></em> significant bits of the significand are always 0).
|
|
|
</p>
|
|
|
<p>Return 0, unless the exponent is not in the current exponent range, in
|
|
|
which case <var>rop</var> 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 <code>gmp_randstate_t</code> structure which should be
|
|
|
created using the GMP <code>gmp_randinit</code> function (see the GMP manual).
|
|
|
</p>
|
|
|
<p>Note: for a given version of MPFR, the returned value of <var>rop</var> and the
|
|
|
new value of <var>state</var> (which controls further random values) do not depend
|
|
|
on the machine word size.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005furandom"></a>Function: <em>int</em> <strong>mpfr_urandom</strong> <em>(mpfr_t <var>rop</var>, gmp_randstate_t <var>state</var>, mpfr_rnd_t <var>rnd</var>)</em></dt>
|
|
|
<dd><p>Generate a uniformly distributed random float.
|
|
|
The floating-point number <var>rop</var> 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 <var>rnd</var>.
|
|
|
</p>
|
|
|
<p>The second argument is a <code>gmp_randstate_t</code> structure which should be
|
|
|
created using the GMP <code>gmp_randinit</code> function (see the GMP manual).
|
|
|
</p>
|
|
|
<p>Note: the note for <code>mpfr_urandomb</code> holds too. In addition, the exponent
|
|
|
range and the rounding mode might have a side effect on the next random state.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fgrandom"></a>Function: <em>int</em> <strong>mpfr_grandom</strong> <em>(mpfr_t <var>rop1</var>, mpfr_t <var>rop2</var>, gmp_randstate_t <var>state</var>, mpfr_rnd_t <var>rnd</var>)</em></dt>
|
|
|
<dd><p>Generate two random floats according to a standard normal gaussian
|
|
|
distribution. If <var>rop2</var> is a null pointer, then only one value is generated
|
|
|
and stored in <var>rop1</var>.
|
|
|
</p>
|
|
|
<p>The floating-point number <var>rop1</var> (and <var>rop2</var>) can be seen as if a
|
|
|
random real number were generated according to the standard normal gaussian
|
|
|
distribution and then rounded in the direction <var>rnd</var>.
|
|
|
</p>
|
|
|
<p>The third argument is a <code>gmp_randstate_t</code> structure, which should be
|
|
|
created using the GMP <code>gmp_randinit</code> function (see the GMP manual).
|
|
|
</p>
|
|
|
<p>The combination of the ternary values is returned like with
|
|
|
<code>mpfr_sin_cos</code>. If <var>rop2</var> 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.
|
|
|
</p>
|
|
|
<p>Note: the note for <code>mpfr_urandomb</code> holds too. In addition, the exponent
|
|
|
range and the rounding mode might have a side effect on the next random state.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fget_005fexp"></a>Function: <em>mpfr_exp_t</em> <strong>mpfr_get_exp</strong> <em>(mpfr_t <var>x</var>)</em></dt>
|
|
|
<dd><p>Return the exponent of <var>x</var>, assuming that <var>x</var> is a non-zero ordinary
|
|
|
number and the significand is considered in [1/2,1). The behavior for NaN,
|
|
|
infinity or zero is undefined.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fset_005fexp"></a>Function: <em>int</em> <strong>mpfr_set_exp</strong> <em>(mpfr_t <var>x</var>, mpfr_exp_t <var>e</var>)</em></dt>
|
|
|
<dd><p>Set the exponent of <var>x</var> if <var>e</var> is in the current exponent range,
|
|
|
and return 0 (even if <var>x</var> is not a non-zero ordinary number);
|
|
|
otherwise, return a non-zero value.
|
|
|
The significand is assumed to be in [1/2,1).
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fsignbit"></a>Function: <em>int</em> <strong>mpfr_signbit</strong> <em>(mpfr_t <var>op</var>)</em></dt>
|
|
|
<dd><p>Return a non-zero value iff <var>op</var> has its sign bit set (i.e., if it is
|
|
|
negative, −0, or a NaN whose representation has its sign bit set).
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fsetsign"></a>Function: <em>int</em> <strong>mpfr_setsign</strong> <em>(mpfr_t <var>rop</var>, mpfr_t <var>op</var>, int <var>s</var>, mpfr_rnd_t <var>rnd</var>)</em></dt>
|
|
|
<dd><p>Set the value of <var>rop</var> from <var>op</var>, rounded toward the given
|
|
|
direction <var>rnd</var>, then set (resp. clear) its sign bit if <var>s</var>
|
|
|
is non-zero (resp. zero), even when <var>op</var> is a NaN.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fcopysign"></a>Function: <em>int</em> <strong>mpfr_copysign</strong> <em>(mpfr_t <var>rop</var>, mpfr_t <var>op1</var>, mpfr_t <var>op2</var>, mpfr_rnd_t <var>rnd</var>)</em></dt>
|
|
|
<dd><p>Set the value of <var>rop</var> from <var>op1</var>, rounded toward the given
|
|
|
direction <var>rnd</var>, then set its sign bit to that of <var>op2</var> (even
|
|
|
when <var>op1</var> or <var>op2</var> is a NaN). This function is equivalent to
|
|
|
<code>mpfr_setsign (<var>rop</var>, <var>op1</var>, mpfr_signbit (<var>op2</var>), <var>rnd</var>)</code>.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fget_005fversion"></a>Function: <em>const char *</em> <strong>mpfr_get_version</strong> <em>(void)</em></dt>
|
|
|
<dd><p>Return the MPFR version, as a null-terminated string.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-MPFR_005fVERSION"></a>Macro: <strong>MPFR_VERSION</strong></dt>
|
|
|
<dt><a name="index-MPFR_005fVERSION_005fMAJOR"></a>Macro: <strong>MPFR_VERSION_MAJOR</strong></dt>
|
|
|
<dt><a name="index-MPFR_005fVERSION_005fMINOR"></a>Macro: <strong>MPFR_VERSION_MINOR</strong></dt>
|
|
|
<dt><a name="index-MPFR_005fVERSION_005fPATCHLEVEL"></a>Macro: <strong>MPFR_VERSION_PATCHLEVEL</strong></dt>
|
|
|
<dt><a name="index-MPFR_005fVERSION_005fSTRING"></a>Macro: <strong>MPFR_VERSION_STRING</strong></dt>
|
|
|
<dd><p><code>MPFR_VERSION</code> is the version of MPFR as a preprocessing constant.
|
|
|
<code>MPFR_VERSION_MAJOR</code>, <code>MPFR_VERSION_MINOR</code> and
|
|
|
<code>MPFR_VERSION_PATCHLEVEL</code> are respectively the major, minor and patch
|
|
|
level of MPFR version, as preprocessing constants.
|
|
|
<code>MPFR_VERSION_STRING</code> 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 <code>mpfr_get_version</code> to check at run time
|
|
|
the header file and library used match:
|
|
|
</p><div class="example">
|
|
|
<pre class="example">if (strcmp (mpfr_get_version (), MPFR_VERSION_STRING))
|
|
|
fprintf (stderr, "Warning: header and library do not match\n");
|
|
|
</pre></div>
|
|
|
<p>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).
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-MPFR_005fVERSION_005fNUM"></a>Macro: <em>long</em> <strong>MPFR_VERSION_NUM</strong> <em>(<var>major</var>, <var>minor</var>, <var>patchlevel</var>)</em></dt>
|
|
|
<dd><p>Create an integer in the same format as used by <code>MPFR_VERSION</code> from the
|
|
|
given <var>major</var>, <var>minor</var> and <var>patchlevel</var>.
|
|
|
Here is an example of how to check the MPFR version at compile time:
|
|
|
</p><div class="example">
|
|
|
<pre class="example">#if (!defined(MPFR_VERSION) || (MPFR_VERSION<MPFR_VERSION_NUM(3,0,0)))
|
|
|
# error "Wrong MPFR version."
|
|
|
#endif
|
|
|
</pre></div>
|
|
|
</dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fget_005fpatches"></a>Function: <em>const char *</em> <strong>mpfr_get_patches</strong> <em>(void)</em></dt>
|
|
|
<dd><p>Return a null-terminated string containing the ids of the patches applied to
|
|
|
the MPFR library (contents of the <samp>PATCHES</samp> 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).
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fbuildopt_005ftls_005fp"></a>Function: <em>int</em> <strong>mpfr_buildopt_tls_p</strong> <em>(void)</em></dt>
|
|
|
<dd><p>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
|
|
|
<code>--enable-thread-safe</code> configure option, see <code>INSTALL</code> file), return
|
|
|
zero otherwise.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fbuildopt_005fdecimal_005fp"></a>Function: <em>int</em> <strong>mpfr_buildopt_decimal_p</strong> <em>(void)</em></dt>
|
|
|
<dd><p>Return a non-zero value if MPFR was compiled with decimal float support (that
|
|
|
is, MPFR was built with the <code>--enable-decimal-float</code> configure option),
|
|
|
return zero otherwise.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fbuildopt_005fgmpinternals_005fp"></a>Function: <em>int</em> <strong>mpfr_buildopt_gmpinternals_p</strong> <em>(void)</em></dt>
|
|
|
<dd><p>Return a non-zero value if MPFR was compiled with GMP internals
|
|
|
(that is, MPFR was built with either <code>--with-gmp-build</code> or
|
|
|
<code>--enable-gmp-internals</code> configure option), return zero otherwise.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<dl>
|
|
|
<dt><a name="index-mpfr_005fbuildopt_005ftune_005fcase"></a>Function: <em>const char *</em> <strong>mpfr_buildopt_tune_case</strong> <em>(void)</em></dt>
|
|
|
<dd><p>Return a string saying which thresholds file has been used at compile time.
|
|
|
This file is normally selected from the processor type.
|
|
|
</p></dd></dl>
|
|
|
|
|
|
<hr>
|
|
|
<div class="header">
|
|
|
<p>
|
|
|
Next: <a href="Exception-Related-Functions.html#Exception-Related-Functions" accesskey="n" rel="next">Exception Related Functions</a>, Previous: <a href="Rounding-Related-Functions.html#Rounding-Related-Functions" accesskey="p" rel="prev">Rounding Related Functions</a>, Up: <a href="MPFR-Interface.html#MPFR-Interface" accesskey="u" rel="up">MPFR Interface</a> [<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
</body>
|
|
|
</html>
|