<!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>