ceph/src/boost/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="../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.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"><sup class="footnote"><a name="boost_multiprecision.tut.floats.mpfr_float.f0"></a>[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 </ul></div>
 227 <h6>
 228 <a name="boost_multiprecision.tut.floats.mpfr_float.h0"></a>
 229           <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>
 230         </h6>
 231 <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>
 232 <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>
 233 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 234
 235 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 236 <span class="special">{</span>
 237    <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>
 238
 239    <span class="comment">// Operations at variable precision and no numeric_limits support:</span>
 240    <span class="identifier">mpfr_float</span> <span class="identifier">a</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
 241    <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>
 242    <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>
 243    <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>
 244
 245    <span class="comment">// Operations at fixed precision and full numeric_limits support:</span>
 246    <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>
 247    <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>
 248    <span class="comment">// We can use any C++ std lib function:</span>
 249    <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>
 250    <span class="comment">// We can also use any function from Boost.Math:</span>
 251    <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>
 252    <span class="comment">// These even work when the argument is an expression template:</span>
 253    <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>
 254
 255    <span class="comment">// Access the underlying data:</span>
 256    <span class="identifier">mpfr_t</span> <span class="identifier">r</span><span class="special">;</span>
 257    <span class="identifier">mpfr_init</span><span class="special">(</span><span class="identifier">r</span><span class="special">);</span>
 258    <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>
 259    <span class="identifier">mpfr_clear</span><span class="special">(</span><span class="identifier">r</span><span class="special">);</span>
 260    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 261 <span class="special">}</span>
 262 </pre>
 263 <div class="footnotes">
 264 <br><hr style="width:100; align:left;">
 265 <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>
 266             Compiled with VC++10 and /Ox, with MPFR-3.0.0 and MPIR-2.3.0
 267           </p></div>
 268 </div>
 269 </div>
 270 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 271 <td align="left"></td>
 272 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2013 John Maddock and Christopher Kormanyos<p>
 273         Distributed under the Boost Software License, Version 1.0. (See accompanying
 274         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>)
 275       </p>
 276 </div></td>
 277 </tr></table>
 278 <hr>
 279 <div class="spirit-nav">
 280 <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>
 281 </div>
 282 </body>
 283 </html>