You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

282 lines
15 KiB
HTML

<!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> &nbsp; [<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 &lt;= <var>rop</var> &lt; 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, &quot;Warning: header and library do not match\n&quot;);
</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&lt;MPFR_VERSION_NUM(3,0,0)))
# error &quot;Wrong MPFR version.&quot;
#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> &nbsp; [<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>