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.
264 lines
12 KiB
HTML
264 lines
12 KiB
HTML
4 years ago
|
<!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>Initialization 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="Initialization 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="Assignment-Functions.html#Assignment-Functions" rel="next" title="Assignment Functions">
|
||
|
|
<link href="MPFR-Interface.html#MPFR-Interface" rel="prev" title="MPFR Interface">
|
||
|
|
<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="Initialization-Functions"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Assignment-Functions.html#Assignment-Functions" accesskey="n" rel="next">Assignment Functions</a>, Previous: <a href="MPFR-Interface.html#MPFR-Interface" accesskey="p" rel="prev">MPFR Interface</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-Initialization-functions"></a>
|
||
|
|
<a name="Initialization-Functions-1"></a>
|
||
|
|
<h3 class="section">5.1 Initialization Functions</h3>
|
||
|
|
|
||
|
|
<p>An <code>mpfr_t</code> object must be initialized before storing the first value in
|
||
|
|
it. The functions <code>mpfr_init</code> and <code>mpfr_init2</code> are used for that
|
||
|
|
purpose.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005finit2"></a>Function: <em>void</em> <strong>mpfr_init2</strong> <em>(mpfr_t <var>x</var>, mpfr_prec_t <var>prec</var>)</em></dt>
|
||
|
|
<dd><p>Initialize <var>x</var>, set its precision to be <strong>exactly</strong>
|
||
|
|
<var>prec</var> bits and its value to NaN. (Warning: the corresponding
|
||
|
|
MPF function initializes to zero instead.)
|
||
|
|
</p>
|
||
|
|
<p>Normally, a variable should be initialized once only or at
|
||
|
|
least be cleared, using <code>mpfr_clear</code>, between initializations.
|
||
|
|
To change the precision of a variable which has already been initialized,
|
||
|
|
use <code>mpfr_set_prec</code>.
|
||
|
|
The precision <var>prec</var> must be an integer between <code>MPFR_PREC_MIN</code> and
|
||
|
|
<code>MPFR_PREC_MAX</code> (otherwise the behavior is undefined).
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005finits2"></a>Function: <em>void</em> <strong>mpfr_inits2</strong> <em>(mpfr_prec_t <var>prec</var>, mpfr_t <var>x</var>, ...)</em></dt>
|
||
|
|
<dd><p>Initialize all the <code>mpfr_t</code> variables of the given variable
|
||
|
|
argument <code>va_list</code>, set their precision to be <strong>exactly</strong>
|
||
|
|
<var>prec</var> bits and their value to NaN.
|
||
|
|
See <code>mpfr_init2</code> for more details.
|
||
|
|
The <code>va_list</code> is assumed to be composed only of type <code>mpfr_t</code>
|
||
|
|
(or equivalently <code>mpfr_ptr</code>).
|
||
|
|
It begins from <var>x</var>, and ends when it encounters a null pointer (whose
|
||
|
|
type must also be <code>mpfr_ptr</code>).
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005fclear"></a>Function: <em>void</em> <strong>mpfr_clear</strong> <em>(mpfr_t <var>x</var>)</em></dt>
|
||
|
|
<dd><p>Free the space occupied by the significand of
|
||
|
|
<var>x</var>. Make sure to call this function for all
|
||
|
|
<code>mpfr_t</code> variables when you are done with them.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005fclears"></a>Function: <em>void</em> <strong>mpfr_clears</strong> <em>(mpfr_t <var>x</var>, ...)</em></dt>
|
||
|
|
<dd><p>Free the space occupied by all the <code>mpfr_t</code> variables of the given
|
||
|
|
<code>va_list</code>. See <code>mpfr_clear</code> for more details.
|
||
|
|
The <code>va_list</code> is assumed to be composed only of type <code>mpfr_t</code>
|
||
|
|
(or equivalently <code>mpfr_ptr</code>).
|
||
|
|
It begins from <var>x</var>, and ends when it encounters a null pointer (whose
|
||
|
|
type must also be <code>mpfr_ptr</code>).
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<p>Here is an example of how to use multiple initialization functions
|
||
|
|
(since <code>NULL</code> is not necessarily defined in this context, we use
|
||
|
|
<code>(mpfr_ptr) 0</code> instead, but <code>(mpfr_ptr) NULL</code> is also correct).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">{
|
||
|
|
mpfr_t x, y, z, t;
|
||
|
|
mpfr_inits2 (256, x, y, z, t, (mpfr_ptr) 0);
|
||
|
|
…
|
||
|
|
mpfr_clears (x, y, z, t, (mpfr_ptr) 0);
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005finit"></a>Function: <em>void</em> <strong>mpfr_init</strong> <em>(mpfr_t <var>x</var>)</em></dt>
|
||
|
|
<dd><p>Initialize <var>x</var>, set its precision to the default precision,
|
||
|
|
and set its value to NaN.
|
||
|
|
The default precision can be changed by a call to <code>mpfr_set_default_prec</code>.
|
||
|
|
</p>
|
||
|
|
<p>Warning! In a given program, some other libraries might change the default
|
||
|
|
precision and not restore it. Thus it is safer to use <code>mpfr_init2</code>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005finits"></a>Function: <em>void</em> <strong>mpfr_inits</strong> <em>(mpfr_t <var>x</var>, ...)</em></dt>
|
||
|
|
<dd><p>Initialize all the <code>mpfr_t</code> variables of the given <code>va_list</code>,
|
||
|
|
set their precision to the default precision and their value to NaN.
|
||
|
|
See <code>mpfr_init</code> for more details.
|
||
|
|
The <code>va_list</code> is assumed to be composed only of type <code>mpfr_t</code>
|
||
|
|
(or equivalently <code>mpfr_ptr</code>).
|
||
|
|
It begins from <var>x</var>, and ends when it encounters a null pointer (whose
|
||
|
|
type must also be <code>mpfr_ptr</code>).
|
||
|
|
</p>
|
||
|
|
<p>Warning! In a given program, some other libraries might change the default
|
||
|
|
precision and not restore it. Thus it is safer to use <code>mpfr_inits2</code>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-MPFR_005fDECL_005fINIT"></a>Macro: <strong>MPFR_DECL_INIT</strong> <em>(<var>name</var>, <var>prec</var>)</em></dt>
|
||
|
|
<dd><p>This macro declares <var>name</var> as an automatic variable of type <code>mpfr_t</code>,
|
||
|
|
initializes it and sets its precision to be <strong>exactly</strong> <var>prec</var> bits
|
||
|
|
and its value to NaN. <var>name</var> must be a valid identifier.
|
||
|
|
You must use this macro in the declaration section.
|
||
|
|
This macro is much faster than using <code>mpfr_init2</code> but has some
|
||
|
|
drawbacks:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li> You <strong>must not</strong> call <code>mpfr_clear</code> with variables
|
||
|
|
created with this macro (the storage is allocated at the point of declaration
|
||
|
|
and deallocated when the brace-level is exited).
|
||
|
|
|
||
|
|
</li><li> You <strong>cannot</strong> change their precision.
|
||
|
|
|
||
|
|
</li><li> You <strong>should not</strong> create variables with huge precision with this
|
||
|
|
macro.
|
||
|
|
|
||
|
|
</li><li> Your compiler must support ‘<samp>Non-Constant Initializers</samp>’ (standard
|
||
|
|
in C++ and ISO C99) and ‘<samp>Token Pasting</samp>’
|
||
|
|
(standard in ISO C89). If <var>prec</var> is not a constant expression, your
|
||
|
|
compiler must support ‘<samp>variable-length automatic arrays</samp>’ (standard
|
||
|
|
in ISO C99). GCC 2.95.3 and above supports all these features.
|
||
|
|
If you compile your program with GCC in C89 mode and with ‘<samp>-pedantic</samp>’,
|
||
|
|
you may want to define the <code>MPFR_USE_EXTENSION</code> macro to avoid warnings
|
||
|
|
due to the <code>MPFR_DECL_INIT</code> implementation.
|
||
|
|
|
||
|
|
</li></ul>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005fset_005fdefault_005fprec"></a>Function: <em>void</em> <strong>mpfr_set_default_prec</strong> <em>(mpfr_prec_t <var>prec</var>)</em></dt>
|
||
|
|
<dd><p>Set the default precision to be <strong>exactly</strong> <var>prec</var> bits, where
|
||
|
|
<var>prec</var> can be any integer between <code>MPFR_PREC_MIN</code> and
|
||
|
|
<code>MPFR_PREC_MAX</code>.
|
||
|
|
The
|
||
|
|
precision of a variable means the number of bits used to store its significand.
|
||
|
|
All
|
||
|
|
subsequent calls to <code>mpfr_init</code> or <code>mpfr_inits</code>
|
||
|
|
will use this precision, but previously
|
||
|
|
initialized variables are unaffected.
|
||
|
|
The default precision is set to 53 bits initially.
|
||
|
|
</p>
|
||
|
|
<p>Note: when MPFR is built with the <code>--enable-thread-safe</code> configure option,
|
||
|
|
the default precision is local to each thread. See <a href="Memory-Handling.html#Memory-Handling">Memory Handling</a>, for
|
||
|
|
more information.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005fget_005fdefault_005fprec"></a>Function: <em>mpfr_prec_t</em> <strong>mpfr_get_default_prec</strong> <em>(void)</em></dt>
|
||
|
|
<dd><p>Return the current default MPFR precision in bits.
|
||
|
|
See the documentation of <code>mpfr_set_default_prec</code>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<p>Here is an example on how to initialize floating-point variables:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">{
|
||
|
|
mpfr_t x, y;
|
||
|
|
mpfr_init (x); /* use default precision */
|
||
|
|
mpfr_init2 (y, 256); /* precision <em>exactly</em> 256 bits */
|
||
|
|
…
|
||
|
|
/* When the program is about to exit, do ... */
|
||
|
|
mpfr_clear (x);
|
||
|
|
mpfr_clear (y);
|
||
|
|
mpfr_free_cache (); /* free the cache for constants like pi */
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The following functions are useful for changing the precision during a
|
||
|
|
calculation. A typical use would be for adjusting the precision gradually in
|
||
|
|
iterative algorithms like Newton-Raphson, making the computation precision
|
||
|
|
closely match the actual accurate part of the numbers.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005fset_005fprec"></a>Function: <em>void</em> <strong>mpfr_set_prec</strong> <em>(mpfr_t <var>x</var>, mpfr_prec_t <var>prec</var>)</em></dt>
|
||
|
|
<dd><p>Reset the precision of <var>x</var> to be <strong>exactly</strong> <var>prec</var> bits,
|
||
|
|
and set its value to NaN.
|
||
|
|
The previous value stored in <var>x</var> is lost. It is equivalent to
|
||
|
|
a call to <code>mpfr_clear(x)</code> followed by a call to
|
||
|
|
<code>mpfr_init2(x, prec)</code>, but more efficient as no allocation is done in
|
||
|
|
case the current allocated space for the significand of <var>x</var> is enough.
|
||
|
|
The precision <var>prec</var> can be any integer between <code>MPFR_PREC_MIN</code> and
|
||
|
|
<code>MPFR_PREC_MAX</code>.
|
||
|
|
In case you want to keep the previous value stored in <var>x</var>,
|
||
|
|
use <code>mpfr_prec_round</code> instead.
|
||
|
|
</p>
|
||
|
|
<p>Warning! You must not use this function if <var>x</var> was initialized
|
||
|
|
with <code>MPFR_DECL_INIT</code> or with <code>mpfr_custom_init_set</code>
|
||
|
|
(see <a href="Custom-Interface.html#Custom-Interface">Custom Interface</a>).
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><a name="index-mpfr_005fget_005fprec"></a>Function: <em>mpfr_prec_t</em> <strong>mpfr_get_prec</strong> <em>(mpfr_t <var>x</var>)</em></dt>
|
||
|
|
<dd><p>Return the precision of <var>x</var>, i.e., the
|
||
|
|
number of bits used to store its significand.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Assignment-Functions.html#Assignment-Functions" accesskey="n" rel="next">Assignment Functions</a>, Previous: <a href="MPFR-Interface.html#MPFR-Interface" accesskey="p" rel="prev">MPFR Interface</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>
|