libs/multiprecision/doc/html/boost_multiprecision/tut/floats/cpp_bin_float.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>cpp_bin_float</title>
   5 <link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.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="../floats.html" title="Floating Point Numbers">
  10 <link rel="next" href="cpp_dec_float.html" title="cpp_dec_float">
  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="../floats.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="cpp_dec_float.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.cpp_bin_float"></a><a class="link" href="cpp_bin_float.html" title="cpp_bin_float">cpp_bin_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">cpp_bin_float</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">digit_base_type</span>
  35 <span class="special">{</span>
  36    <span class="identifier">digit_base_2</span> <span class="special">=</span> <span class="number">2</span><span class="special">,</span>
  37    <span class="identifier">digit_base_10</span> <span class="special">=</span> <span class="number">10</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">Digits</span><span class="special">,</span> <span class="identifier">digit_base_type</span> <span class="identifier">base</span> <span class="special">=</span> <span class="identifier">digit_base_10</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Allocator</span> <span class="special">=</span> <span class="keyword">void</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Exponent</span> <span class="special">=</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">ExponentMin</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">ExponentMax</span> <span class="special">=</span> <span class="number">0</span><span class="special">&gt;</span>
  41 <span class="keyword">class</span> <span class="identifier">cpp_bin_float</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">cpp_bin_float</span><span class="special">&lt;</span><span class="number">50</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">cpp_bin_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">cpp_bin_float</span><span class="special">&lt;</span><span class="number">100</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">cpp_bin_float_100</span><span class="special">;</span>
  45
  46 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">24</span><span class="special">,</span> <span class="identifier">backends</span><span class="special">::</span><span class="identifier">digit_base_2</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">int16_t</span><span class="special">,</span> <span class="special">-</span><span class="number">126</span><span class="special">,</span> <span class="number">127</span><span class="special">&gt;,</span> <span class="identifier">et_off</span><span class="special">&gt;</span>       <span class="identifier">cpp_bin_float_single</span><span class="special">;</span>
  47 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">53</span><span class="special">,</span> <span class="identifier">backends</span><span class="special">::</span><span class="identifier">digit_base_2</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">int16_t</span><span class="special">,</span> <span class="special">-</span><span class="number">1022</span><span class="special">,</span> <span class="number">1023</span><span class="special">&gt;,</span> <span class="identifier">et_off</span><span class="special">&gt;</span>     <span class="identifier">cpp_bin_float_double</span><span class="special">;</span>
  48 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">64</span><span class="special">,</span> <span class="identifier">backends</span><span class="special">::</span><span class="identifier">digit_base_2</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">int16_t</span><span class="special">,</span> <span class="special">-</span><span class="number">16382</span><span class="special">,</span> <span class="number">16383</span><span class="special">&gt;,</span> <span class="identifier">et_off</span><span class="special">&gt;</span>   <span class="identifier">cpp_bin_float_double_extended</span><span class="special">;</span>
  49 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">113</span><span class="special">,</span> <span class="identifier">backends</span><span class="special">::</span><span class="identifier">digit_base_2</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">int16_t</span><span class="special">,</span> <span class="special">-</span><span class="number">16382</span><span class="special">,</span> <span class="number">16383</span><span class="special">&gt;,</span> <span class="identifier">et_off</span><span class="special">&gt;</span>  <span class="identifier">cpp_bin_float_quad</span><span class="special">;</span>
  50
  51 <span class="special">}}</span> <span class="comment">// namespaces</span>
  52 </pre>
  53 <p>
  54           The <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code> back-end
  55           is used in conjunction with <code class="computeroutput"><span class="identifier">number</span></code>:
  56           It acts as an entirely C++ (header only and dependency free) floating-point
  57           number type that is a drop-in replacement for the native C++ floating-point
  58           types, but with much greater precision.
  59         </p>
  60 <p>
  61           Type <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code> can
  62           be used at fixed precision by specifying a non-zero <code class="computeroutput"><span class="identifier">Digits</span></code>
  63           template parameter. The typedefs <code class="computeroutput"><span class="identifier">cpp_bin_float_50</span></code>
  64           and <code class="computeroutput"><span class="identifier">cpp_bin_float_100</span></code> provide
  65           arithmetic types at 50 and 100 decimal digits precision respectively.
  66         </p>
  67 <p>
  68           Optionally, you can specify whether the precision is specified in decimal
  69           digits or binary bits - for example to declare a <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code>
  70           with exactly the same precision as <code class="computeroutput"><span class="keyword">double</span></code>
  71           one would use <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">53</span><span class="special">,</span> <span class="identifier">digit_base_2</span><span class="special">&gt;</span> <span class="special">&gt;</span></code>.
  72           The typedefs <code class="computeroutput"><span class="identifier">cpp_bin_float_single</span></code>,
  73           <code class="computeroutput"><span class="identifier">cpp_bin_float_double</span></code>,
  74           <code class="computeroutput"><span class="identifier">cpp_bin_float_quad</span></code> and
  75           <code class="computeroutput"><span class="identifier">cpp_bin_float_double_extended</span></code>
  76           provide software analogues of the IEEE single, double and quad float data
  77           types, plus the Intel-extended-double type respectively. Note that while
  78           these types are functionally equivalent to the native IEEE types, but they
  79           do not have the same size or bit-layout as true IEEE compatible types.
  80         </p>
  81 <p>
  82           Normally <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code>
  83           allocates no memory: all of the space required for its digits are allocated
  84           directly within the class. As a result care should be taken not to use
  85           the class with too high a digit count as stack space requirements can grow
  86           out of control. If that represents a problem then providing an allocator
  87           as a template parameter causes <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code>
  88           to dynamically allocate the memory it needs: this significantly reduces
  89           the size of <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code>
  90           and increases the viable upper limit on the number of digits at the expense
  91           of performance. However, please bear in mind that arithmetic operations
  92           rapidly become <span class="emphasis"><em>very</em></span> expensive as the digit count grows:
  93           the current implementation really isn't optimized or designed for large
  94           digit counts. Note that since the actual type of the objects allocated
  95           is completely opaque, the suggestion would be to use an allocator with
  96           <code class="computeroutput"><span class="keyword">void</span></code> <code class="computeroutput"><span class="identifier">value_type</span></code>,
  97           for example: <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">1000</span><span class="special">,</span> <span class="identifier">digit_base_10</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span></code>.
  98         </p>
  99 <p>
 100           The final template parameters determine the type and range of the exponent:
 101           parameter <code class="computeroutput"><span class="identifier">Exponent</span></code> can
 102           be any signed integer type, but note that <code class="computeroutput"><span class="identifier">MinExponent</span></code>
 103           and <code class="computeroutput"><span class="identifier">MaxExponent</span></code> can not
 104           go right up to the limits of the <code class="computeroutput"><span class="identifier">Exponent</span></code>
 105           type as there has to be a little extra headroom for internal calculations.
 106           You will get a compile time error if this is the case. In addition if MinExponent
 107           or MaxExponent are zero, then the library will choose suitable values that
 108           are as large as possible given the constraints of the type and need for
 109           extra headroom for internal calculations.
 110         </p>
 111 <p>
 112           There is full standard library and <code class="computeroutput"><span class="identifier">numeric_limits</span></code>
 113           support available for this type.
 114         </p>
 115 <p>
 116           Things you should know when using this type:
 117         </p>
 118 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 119 <li class="listitem">
 120               Default constructed <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code>s
 121               have a value of zero.
 122             </li>
 123 <li class="listitem">
 124               The radix of this type is 2, even when the precision is specified as
 125               decimal digits.
 126             </li>
 127 <li class="listitem">
 128               The type supports both infinities and NaN's. An infinity is generated
 129               whenever the result would overflow, and a NaN is generated for any
 130               mathematically undefined operation.
 131             </li>
 132 <li class="listitem">
 133               There is a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code> specialisation for
 134               this type.
 135             </li>
 136 <li class="listitem">
 137               Any <code class="computeroutput"><span class="identifier">number</span></code> instantiated
 138               on this type, is convertible to any other <code class="computeroutput"><span class="identifier">number</span></code>
 139               instantiated on this type - for example you can convert from <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">50</span><span class="special">&gt;</span> <span class="special">&gt;</span></code> to <code class="computeroutput"><span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="identifier">SomeOtherValue</span><span class="special">&gt;</span> <span class="special">&gt;</span></code>.
 140               Narrowing conversions round to nearest and are <code class="computeroutput"><span class="keyword">explicit</span></code>.
 141             </li>
 142 <li class="listitem">
 143               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>
 144               being thrown if the string can not be interpreted as a valid floating
 145               point number.
 146             </li>
 147 <li class="listitem">
 148               All arithmetic operations are correctly rounded to nearest. String
 149               conversions and the <code class="computeroutput"><span class="identifier">sqrt</span></code>
 150               function are also correctly rounded, but transcendental functions (sin,
 151               cos, pow, exp etc) are not.
 152             </li>
 153 </ul></div>
 154 <h6>
 155 <a name="boost_multiprecision.tut.floats.cpp_bin_float.h0"></a>
 156           <span class="phrase"><a name="boost_multiprecision.tut.floats.cpp_bin_float.cpp_bin_float_example"></a></span><a class="link" href="cpp_bin_float.html#boost_multiprecision.tut.floats.cpp_bin_float.cpp_bin_float_example">cpp_bin_float
 157           example:</a>
 158         </h6>
 159 <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">cpp_bin_float</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 160 <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>
 161 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 162
 163 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 164 <span class="special">{</span>
 165    <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>
 166
 167    <span class="comment">// Operations at fixed precision and full numeric_limits support:</span>
 168    <span class="identifier">cpp_bin_float_100</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
 169    <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">cpp_bin_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>
 170    <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">cpp_bin_float_100</span><span class="special">&gt;::</span><span class="identifier">digits10</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>
 171    <span class="comment">// We can use any C++ std lib function, lets print all the digits as well:</span>
 172    <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">setprecision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float_100</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">)</span>
 173       <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>
 174    <span class="comment">// We can also use any function from Boost.Math:</span>
 175    <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>
 176    <span class="comment">// These even work when the argument is an expression template:</span>
 177    <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>
 178    <span class="comment">// And since we have an extended exponent range we can generate some really large </span>
 179    <span class="comment">// numbers here (4.0238726007709377354370243e+2564):</span>
 180    <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">cpp_bin_float_100</span><span class="special">(</span><span class="number">1000</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>
 181    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 182 <span class="special">}</span>
 183 </pre>
 184 </div>
 185 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 186 <td align="left"></td>
 187 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2013 John Maddock and Christopher Kormanyos<p>
 188         Distributed under the Boost Software License, Version 1.0. (See accompanying
 189         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>)
 190       </p>
 191 </div></td>
 192 </tr></table>
 193 <hr>
 194 <div class="spirit-nav">
 195 <a accesskey="p" href="../floats.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="cpp_dec_float.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 196 </div>
 197 </body>
 198 </html>