Imported Upstream version 1.72.0
[platform/upstream/boost.git] / libs / multiprecision / doc / html / boost_multiprecision / tut / floats / mpfr_float.html
1 <html>
2 <head>
3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>mpfr_float</title>
5 <link rel="stylesheet" href="../../../multiprecision.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="../../../index.html" title="Chapter&#160;1.&#160;Boost.Multiprecision">
8 <link rel="up" href="../floats.html" title="floating-point Numbers">
9 <link rel="prev" href="gmp_float.html" title="gmp_float">
10 <link rel="next" href="float128.html" title="float128">
11 </head>
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
20 </tr></table>
21 <hr>
22 <div class="spirit-nav">
23 <a accesskey="p" href="gmp_float.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../floats.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="float128.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
24 </div>
25 <div class="section">
26 <div class="titlepage"><div><div><h4 class="title">
27 <a name="boost_multiprecision.tut.floats.mpfr_float"></a><a class="link" href="mpfr_float.html" title="mpfr_float">mpfr_float</a>
28 </h4></div></div></div>
29 <p>
30           <code class="computeroutput"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">multiprecision</span><span class="special">/</span><span class="identifier">mpfr</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
31         </p>
32 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">multiprecision</span><span class="special">{</span>
33
34 <span class="keyword">enum</span> <span class="identifier">mpfr_allocation_type</span>
35 <span class="special">{</span>
36    <span class="identifier">allocate_stack</span><span class="special">,</span>
37    <span class="identifier">allocate_dynamic</span>
38 <span class="special">};</span>
39
40 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="identifier">Digits10</span><span class="special">,</span> <span class="identifier">mpfr_allocation_type</span> <span class="identifier">AllocateType</span> <span class="special">=</span> <span class="identifier">allocate_dynamic</span><span class="special">&gt;</span>
41 <span class="keyword">class</span> <span class="identifier">mpfr_float_backend</span><span class="special">;</span>
42
43 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">50</span><span class="special">&gt;</span> <span class="special">&gt;</span>    <span class="identifier">mpfr_float_50</span><span class="special">;</span>
44 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">100</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">mpfr_float_100</span><span class="special">;</span>
45 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">500</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">mpfr_float_500</span><span class="special">;</span>
46 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">1000</span><span class="special">&gt;</span> <span class="special">&gt;</span>  <span class="identifier">mpfr_float_1000</span><span class="special">;</span>
47 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">mpfr_float</span><span class="special">;</span>
48
49 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">50</span><span class="special">,</span> <span class="identifier">allocate_stack</span><span class="special">&gt;</span> <span class="special">&gt;</span>    <span class="identifier">static_mpfr_float_50</span><span class="special">;</span>
50 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">100</span><span class="special">,</span> <span class="identifier">allocate_stack</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">static_mpfr_float_100</span><span class="special">;</span>
51
52 <span class="special">}}</span> <span class="comment">// namespaces</span>
53 </pre>
54 <p>
55           The <code class="computeroutput"><span class="identifier">mpfr_float_backend</span></code>
56           type is used in conjunction with <code class="computeroutput"><span class="identifier">number</span></code>:
57           It acts as a thin wrapper around the <a href="http://www.mpfr.org" target="_top">MPFR</a>
58           <code class="computeroutput"><span class="identifier">mpfr_t</span></code> to provide an real-number
59           type that is a drop-in replacement for the native C++ floating-point types,
60           but with much greater precision.
61         </p>
62 <p>
63           Type <code class="computeroutput"><span class="identifier">mpfr_float_backend</span></code>
64           can be used at fixed precision by specifying a non-zero <code class="computeroutput"><span class="identifier">Digits10</span></code>
65           template parameter, or at variable precision by setting the template argument
66           to zero. The typedefs mpfr_float_50, mpfr_float_100, mpfr_float_500, mpfr_float_1000
67           provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision
68           respectively. The typedef mpfr_float provides a variable precision type
69           whose precision can be controlled via the <code class="computeroutput"><span class="identifier">number</span></code>s
70           member functions.
71         </p>
72 <p>
73           In addition the second template parameter lets you choose between dynamic
74           allocation (the default, and uses MPFR's normal allocation routines), or
75           stack allocation (where all the memory required for the underlying data
76           types is stored within <code class="computeroutput"><span class="identifier">mpfr_float_backend</span></code>).
77           The latter option can result in significantly faster code, at the expense
78           of growing the size of <code class="computeroutput"><span class="identifier">mpfr_float_backend</span></code>.
79           It can only be used at fixed precision, and should only be used for lower
80           digit counts. Note that we can not guarantee that using <code class="computeroutput"><span class="identifier">allocate_stack</span></code>
81           won't cause any calls to mpfr's allocation routines, as mpfr may call these
82           inside it's own code. The following table gives an idea of the performance
83           tradeoff's at 50 decimal digits precision<a href="#ftn.boost_multiprecision.tut.floats.mpfr_float.f0" class="footnote" name="boost_multiprecision.tut.floats.mpfr_float.f0"><sup class="footnote">[2]</sup></a>:
84         </p>
85 <div class="informaltable"><table class="table">
86 <colgroup>
87 <col>
88 <col>
89 </colgroup>
90 <thead><tr>
91 <th>
92                   <p>
93                     Type
94                   </p>
95                 </th>
96 <th>
97                   <p>
98                     Bessel function evaluation, relative times
99                   </p>
100                 </th>
101 </tr></thead>
102 <tbody>
103 <tr>
104 <td>
105                   <p>
106                     <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">50</span><span class="special">,</span> <span class="identifier">allocate_static</span><span class="special">&gt;,</span>
107                     <span class="identifier">et_on</span><span class="special">&gt;</span></code>
108                   </p>
109                 </td>
110 <td>
111                   <p>
112                     1.0 (5.5s)
113                   </p>
114                 </td>
115 </tr>
116 <tr>
117 <td>
118                   <p>
119                     <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">50</span><span class="special">,</span> <span class="identifier">allocate_static</span><span class="special">&gt;,</span>
120                     <span class="identifier">et_off</span><span class="special">&gt;</span></code>
121                   </p>
122                 </td>
123 <td>
124                   <p>
125                     1.05 (5.8s)
126                   </p>
127                 </td>
128 </tr>
129 <tr>
130 <td>
131                   <p>
132                     <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">50</span><span class="special">,</span> <span class="identifier">allocate_dynamic</span><span class="special">&gt;,</span>
133                     <span class="identifier">et_on</span><span class="special">&gt;</span></code>
134                   </p>
135                 </td>
136 <td>
137                   <p>
138                     1.05 (5.8s)
139                   </p>
140                 </td>
141 </tr>
142 <tr>
143 <td>
144                   <p>
145                     <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="number">50</span><span class="special">,</span> <span class="identifier">allocate_dynamic</span><span class="special">&gt;,</span>
146                     <span class="identifier">et_off</span><span class="special">&gt;</span></code>
147                   </p>
148                 </td>
149 <td>
150                   <p>
151                     1.16 (6.4s)
152                   </p>
153                 </td>
154 </tr>
155 </tbody>
156 </table></div>
157 <div class="note"><table border="0" summary="Note">
158 <tr>
159 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
160 <th align="left">Note</th>
161 </tr>
162 <tr><td align="left" valign="top"><p>
163             This type only provides <code class="computeroutput"><span class="identifier">numeric_limits</span></code>
164             support when the precision is fixed at compile time.
165           </p></td></tr>
166 </table></div>
167 <p>
168           As well as the usual conversions from arithmetic and string types, instances
169           of <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="identifier">N</span><span class="special">&gt;</span> <span class="special">&gt;</span></code> are copy constructible and assignable
170           from:
171         </p>
172 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
173 <li class="listitem">
174               The <a href="http://gmplib.org" target="_top">GMP</a> native types <code class="computeroutput"><span class="identifier">mpf_t</span></code>, <code class="computeroutput"><span class="identifier">mpz_t</span></code>,
175               <code class="computeroutput"><span class="identifier">mpq_t</span></code>.
176             </li>
177 <li class="listitem">
178               The <a href="http://www.mpfr.org" target="_top">MPFR</a> native type <code class="computeroutput"><span class="identifier">mpfr_t</span></code>.
179             </li>
180 <li class="listitem">
181               The <code class="computeroutput"><span class="identifier">number</span></code> wrappers
182               around those types: <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpfr_float_backend</span><span class="special">&lt;</span><span class="identifier">M</span><span class="special">&gt;</span> <span class="special">&gt;</span></code>,
183               <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">mpf_float</span><span class="special">&lt;</span><span class="identifier">M</span><span class="special">&gt;</span> <span class="special">&gt;</span></code>, <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">gmp_int</span><span class="special">&gt;</span></code>, <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">gmp_rational</span><span class="special">&gt;</span></code>.
184             </li>
185 </ul></div>
186 <p>
187           It's also possible to access the underlying <code class="computeroutput"><span class="identifier">mpfr_t</span></code>
188           via the data() member function of <code class="computeroutput"><span class="identifier">mpfr_float_backend</span></code>.
189         </p>
190 <p>
191           Things you should know when using this type:
192         </p>
193 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
194 <li class="listitem">
195               A default constructed <code class="computeroutput"><span class="identifier">mpfr_float_backend</span></code>
196               is set to zero (<span class="emphasis"><em>Note that this is <span class="bold"><strong>not</strong></span>
197               the default <a href="http://www.mpfr.org" target="_top">MPFR</a> behavior</em></span>).
198             </li>
199 <li class="listitem">
200               All operations use round to nearest.
201             </li>
202 <li class="listitem">
203               No changes are made to <a href="http://gmplib.org" target="_top">GMP</a> or
204               <a href="http://www.mpfr.org" target="_top">MPFR</a> global settings, so this
205               type can coexist with existing <a href="http://www.mpfr.org" target="_top">MPFR</a>
206               or <a href="http://gmplib.org" target="_top">GMP</a> code.
207             </li>
208 <li class="listitem">
209               The code can equally use <a href="http://mpir.org/" target="_top">MPIR</a>
210               in place of <a href="http://gmplib.org" target="_top">GMP</a> - indeed that
211               is the preferred option on Win32.
212             </li>
213 <li class="listitem">
214               This backend supports rvalue-references and is move-aware, making instantiations
215               of <code class="computeroutput"><span class="identifier">number</span></code> on this backend
216               move aware.
217             </li>
218 <li class="listitem">
219               Conversion from a string results in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span></code>
220               being thrown if the string can not be interpreted as a valid floating-point
221               number.
222             </li>
223 <li class="listitem">
224               Division by zero results in an infinity.
225             </li>
226 <li class="listitem">
227               When using the variable precision type <code class="computeroutput"><span class="identifier">mpfr_float</span></code>,
228               then copy construction and assignment <span class="emphasis"><em>copies the precision
229               of the source variable</em></span>. Likewise move construction and assignment.
230             </li>
231 <li class="listitem">
232               When constructing the variable precision type <code class="computeroutput"><span class="identifier">mpfr_float</span></code>
233               you can specify two arguments to the constructor - the first is the
234               value to assign to the variable, the second is an unsigned integer
235               specifying the precision in decimal places. The <code class="computeroutput"><span class="identifier">assign</span></code>
236               member function similarly has a 2-argument overload taking the value
237               to assign and the precision. You can use this to preserve the precision
238               of the target variable using the somewhat arcane: <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">assign</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span> <span class="identifier">a</span><span class="special">.</span><span class="identifier">precision</span><span class="special">())</span></code>, which assigns <code class="computeroutput"><span class="identifier">b</span></code>
239               to <code class="computeroutput"><span class="identifier">a</span></code> but preserves
240               the precision of <code class="computeroutput"><span class="identifier">a</span></code>.
241             </li>
242 </ul></div>
243 <h6>
244 <a name="boost_multiprecision.tut.floats.mpfr_float.h0"></a>
245           <span class="phrase"><a name="boost_multiprecision.tut.floats.mpfr_float.mpfr_example"></a></span><a class="link" href="mpfr_float.html#boost_multiprecision.tut.floats.mpfr_float.mpfr_example"> MPFR example:</a>
246         </h6>
247 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">multiprecision</span><span class="special">/</span><span class="identifier">mpfr</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
248 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
249 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
250
251 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
252 <span class="special">{</span>
253    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">;</span>
254
255    <span class="comment">// Operations at variable precision and no numeric_limits support:</span>
256    <span class="identifier">mpfr_float</span> <span class="identifier">a</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
257    <span class="identifier">mpfr_float</span><span class="special">::</span><span class="identifier">default_precision</span><span class="special">(</span><span class="number">1000</span><span class="special">);</span>
258    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">mpfr_float</span><span class="special">::</span><span class="identifier">default_precision</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
259    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// print root-2</span>
260
261    <span class="comment">// Operations at fixed precision and full numeric_limits support:</span>
262    <span class="identifier">mpfr_float_100</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
263    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">mpfr_float_100</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
264    <span class="comment">// We can use any C++ std lib function:</span>
265    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">log</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// print log(2)</span>
266    <span class="comment">// We can also use any function from Boost.Math:</span>
267    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
268    <span class="comment">// These even work when the argument is an expression template:</span>
269    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">b</span> <span class="special">*</span> <span class="identifier">b</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
270
271    <span class="comment">// Access the underlying data:</span>
272    <span class="identifier">mpfr_t</span> <span class="identifier">r</span><span class="special">;</span>
273    <span class="identifier">mpfr_init</span><span class="special">(</span><span class="identifier">r</span><span class="special">);</span>
274    <span class="identifier">mpfr_set</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">b</span><span class="special">.</span><span class="identifier">backend</span><span class="special">().</span><span class="identifier">data</span><span class="special">(),</span> <span class="identifier">GMP_RNDN</span><span class="special">);</span>
275    <span class="identifier">mpfr_clear</span><span class="special">(</span><span class="identifier">r</span><span class="special">);</span>
276    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
277 <span class="special">}</span>
278 </pre>
279 <div class="footnotes">
280 <br><hr style="width:100; text-align:left;margin-left: 0">
281 <div id="ftn.boost_multiprecision.tut.floats.mpfr_float.f0" class="footnote"><p><a href="#boost_multiprecision.tut.floats.mpfr_float.f0" class="para"><sup class="para">[2] </sup></a>
282             Compiled with VC++10 and /Ox, with MPFR-3.0.0 and MPIR-2.3.0
283           </p></div>
284 </div>
285 </div>
286 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
287 <td align="left"></td>
288 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2019 John Maddock
289       and Christopher Kormanyos<p>
290         Distributed under the Boost Software License, Version 1.0. (See accompanying
291         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
292       </p>
293 </div></td>
294 </tr></table>
295 <hr>
296 <div class="spirit-nav">
297 <a accesskey="p" href="gmp_float.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../floats.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="float128.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
298 </div>
299 </body>
300 </html>