ceph/src/boost/libs/multiprecision/doc/html/boost_multiprecision/ref/cpp_bin_float_ref.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.77.1">
   7 <link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Multiprecision">
   8 <link rel="up" href="../ref.html" title="Reference">
   9 <link rel="prev" href="mpfr_ref.html" title="mpfr_float_backend">
  10 <link rel="next" href="cpp_dec_ref.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="mpfr_ref.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.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_ref.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_multiprecision.ref.cpp_bin_float_ref"></a><a class="link" href="cpp_bin_float_ref.html" title="cpp_bin_float">cpp_bin_float</a>
  28 </h3></div></div></div>
  29 <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>
  30
  31 <span class="keyword">enum</span> <span class="identifier">digit_base_type</span>
  32 <span class="special">{</span>
  33    <span class="identifier">digit_base_2</span> <span class="special">=</span> <span class="number">2</span><span class="special">,</span>
  34    <span class="identifier">digit_base_10</span> <span class="special">=</span> <span class="number">10</span>
  35 <span class="special">};</span>
  36
  37 <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>
  38 <span class="keyword">class</span> <span class="identifier">cpp_bin_float</span><span class="special">;</span>
  39
  40 <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>
  41 <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>
  42
  43 <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>
  44 <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>
  45 <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>
  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">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>
  47
  48 <span class="special">}}</span> <span class="comment">// namespaces</span>
  49 </pre>
  50 <p>
  51         Class template <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code>
  52         fulfils all of the requirements for a <a class="link" href="backendconc.html" title="Backend Requirements">Backend</a>
  53         type. Its members and non-member functions are deliberately not documented:
  54         these are considered implementation details that are subject to change.
  55       </p>
  56 <p>
  57         The class takes six template parameters:
  58       </p>
  59 <div class="variablelist">
  60 <p class="title"><b></b></p>
  61 <dl class="variablelist">
  62 <dt><span class="term">Digits</span></dt>
  63 <dd><p>
  64               The number of digits precision the type should support. This is normally
  65               expressed as base-10 digits, but that can be changed via the second
  66               template parameter.
  67             </p></dd>
  68 <dt><span class="term">base</span></dt>
  69 <dd><p>
  70               An enumerated value (either <code class="computeroutput"><span class="identifier">digit_base_10</span></code>
  71               or <code class="computeroutput"><span class="identifier">digit_base_2</span></code>) that
  72               indicates whether <code class="computeroutput"><span class="identifier">Digits</span></code>
  73               is base-10 or base-2
  74             </p></dd>
  75 <dt><span class="term">Allocator</span></dt>
  76 <dd><p>
  77               The allocator used: defaults to type <code class="computeroutput"><span class="keyword">void</span></code>,
  78               meaning all storage is within the class, and no dynamic allocation
  79               is performed, but can be set to a standard library allocator if dynamic
  80               allocation makes more sense.
  81             </p></dd>
  82 <dt><span class="term">Exponent</span></dt>
  83 <dd><p>
  84               A signed integer type to use as the type of the exponent - defaults
  85               to <code class="computeroutput"><span class="keyword">int</span></code>.
  86             </p></dd>
  87 <dt><span class="term">ExponentMin</span></dt>
  88 <dd><p>
  89               The smallest (most negative) permitted exponent, defaults to zero,
  90               meaning "define as small as possible given the limitations of
  91               the type and our internal requirements".
  92             </p></dd>
  93 <dt><span class="term">ExponentMax</span></dt>
  94 <dd><p>
  95               The largest (most positive) permitted exponent, defaults to zero, meaning
  96               "define as large as possible given the limitations of the type
  97               and our internal requirements".
  98             </p></dd>
  99 </dl>
 100 </div>
 101 <p>
 102         The type of <code class="computeroutput"><span class="identifier">number_category</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="identifier">Args</span><span class="special">...&gt;</span> <span class="special">&gt;::</span><span class="identifier">type</span></code> is <code class="computeroutput"><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">int_</span><span class="special">&lt;</span><span class="identifier">number_kind_floating_point</span><span class="special">&gt;</span></code>.
 103       </p>
 104 <p>
 105         More information on this type can be found in the <a class="link" href="../tut/floats/cpp_bin_float.html" title="cpp_bin_float">tutorial</a>.
 106       </p>
 107 <h5>
 108 <a name="boost_multiprecision.ref.cpp_bin_float_ref.h0"></a>
 109         <span class="phrase"><a name="boost_multiprecision.ref.cpp_bin_float_ref.implementation_notes"></a></span><a class="link" href="cpp_bin_float_ref.html#boost_multiprecision.ref.cpp_bin_float_ref.implementation_notes">Implementation
 110         Notes</a>
 111       </h5>
 112 <p>
 113         Internally, an N-bit <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code>
 114         is represented as an N-bit unsigned integer along with an exponent and a
 115         sign. The integer part is normalized so that it's most significant bit is
 116         always 1. The decimal point is assumed to be directly after the most significant
 117         bit of the integer part. The special values zero, infinity and NaN all have
 118         the integer part set to zero, and the exponent to one of 3 special values
 119         above the maximum permitted exponent.
 120       </p>
 121 <p>
 122         Multiplication is trivial: multiply the two N-bit integer mantissa's to obtain
 123         a 2N-bit number, then round and adjust the sign and exponent.
 124       </p>
 125 <p>
 126         Addition and subtraction proceed similarly - if the exponents are such that
 127         there is overlap between the two values, then left shift the larger value
 128         to produce a number with between N and 2N bits, then perform integer addition
 129         or subtraction, round, and adjust the exponent.
 130       </p>
 131 <p>
 132         Division proceeds as follows: first scale the numerator by some power of
 133         2 so that integer division will produce either an N-bit or N+1 bit result
 134         plus a remainder. If we get an N bit result then the size of twice the remainder
 135         compared to the denominator gives us the rounding direction. Otherwise we
 136         have one extra bit in the result which we can use to determine rounding (in
 137         this case ties occur only if the remainder is zero and the extra bit is a
 138         1).
 139       </p>
 140 <p>
 141         Square root uses integer square root in a manner analogous to division.
 142       </p>
 143 <p>
 144         Decimal string to binary conversion proceeds as follows: first parse the
 145         digits to produce an integer multiplied by a decimal exponent. Note that
 146         we stop parsing digits once we have parsed as many as can possibly effect
 147         the result - this stops the integer part growing too large when there are
 148         a very large number of input digits provided. At this stage if the decimal
 149         exponent is positive then the result is an integer and we can in principle
 150         simply multiply by 10^N to get an exact integer result. In practice however,
 151         that could produce some very large integers. We also need to be able to divide
 152         by 10^N in the event that the exponent is negative. Therefore calculation
 153         of the 10^N values plus the multiplication or division are performed using
 154         limited precision integer arithmetic, plus an exponent, and a track of the
 155         accumulated error. At the end of the calculation we will either be able to
 156         round unambiguously, or the error will be such that we can't tell which way
 157         to round. In the latter case we simply up the precision and try again until
 158         we have an unambiguously rounded result.
 159       </p>
 160 <p>
 161         Binary to decimal conversion proceeds very similarly to the above, our aim
 162         is to calculate <code class="computeroutput"><span class="identifier">mantissa</span> <span class="special">*</span> <span class="number">2</span><span class="special">^</span><span class="identifier">shift</span> <span class="special">*</span> <span class="number">10</span><span class="special">^</span><span class="identifier">E</span></code>
 163         where <code class="computeroutput"><span class="identifier">E</span></code> is the decimal exponent
 164         and <code class="computeroutput"><span class="identifier">shift</span></code> is calculated so
 165         that the result is an N bit integer assuming we want N digits printed in
 166         the result. As before we use limited precision arithmetic to calculate the
 167         result and up the precision as necessary until the result is unambiguously
 168         correctly rounded. In addition our initial calculation of the decimal exponent
 169         may be out by 1, so we have to correct that and loop as well in the that
 170         case.
 171       </p>
 172 </div>
 173 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 174 <td align="left"></td>
 175 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2013 John Maddock and Christopher Kormanyos<p>
 176         Distributed under the Boost Software License, Version 1.0. (See accompanying
 177         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>)
 178       </p>
 179 </div></td>
 180 </tr></table>
 181 <hr>
 182 <div class="spirit-nav">
 183 <a accesskey="p" href="mpfr_ref.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.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_ref.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 184 </div>
 185 </body>
 186 </html>