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