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