1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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 1. 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"><</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">></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"><</span><span class="identifier">cpp_bin_float</span><span class="special"><</span><span class="number">50</span><span class="special">></span> <span class="special">></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"><</span><span class="identifier">cpp_bin_float</span><span class="special"><</span><span class="number">100</span><span class="special">></span> <span class="special">></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"><</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special"><</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">>,</span> <span class="identifier">et_off</span><span class="special">></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"><</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special"><</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">>,</span> <span class="identifier">et_off</span><span class="special">></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"><</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special"><</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">>,</span> <span class="identifier">et_off</span><span class="special">></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"><</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special"><</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">>,</span> <span class="identifier">et_off</span><span class="special">></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"><</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special"><</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">>,</span> <span class="identifier">et_off</span><span class="special">></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"><</span><span class="identifier">cpp_bin_float</span><span class="special"><</span><span class="identifier">Args</span><span class="special">...></span> <span class="special">>::</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"><</span><span class="identifier">number_kind_floating_point</span><span class="special">></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 its 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 © 2002-2020 John 177 Maddock 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> 189
