1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>cpp_dec_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="cpp_bin_float.html" title="cpp_bin_float"> 10<link rel="next" href="gmp_float.html" title="gmp_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="cpp_bin_float.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="gmp_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_dec_float"></a><a class="link" href="cpp_dec_float.html" title="cpp_dec_float">cpp_dec_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_dec_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">template</span> <span class="special"><</span><span class="keyword">unsigned</span> <span class="identifier">Digits10</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">ExponentType</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="keyword">class</span> <span class="identifier">Allocator</span> <span class="special">=</span> <span class="keyword">void</span><span class="special">></span> 35<span class="keyword">class</span> <span class="identifier">cpp_dec_float</span><span class="special">;</span> 36 37<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special"><</span><span class="identifier">cpp_dec_float</span><span class="special"><</span><span class="number">50</span><span class="special">></span> <span class="special">></span> <span class="identifier">cpp_dec_float_50</span><span class="special">;</span> 38<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special"><</span><span class="identifier">cpp_dec_float</span><span class="special"><</span><span class="number">100</span><span class="special">></span> <span class="special">></span> <span class="identifier">cpp_dec_float_100</span><span class="special">;</span> 39 40<span class="special">}}</span> <span class="comment">// namespaces</span> 41</pre> 42<p> 43 The <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code> back-end 44 is used in conjunction with <code class="computeroutput"><span class="identifier">number</span></code>: 45 It acts as an entirely C++ (header only and dependency free) floating-point 46 number type that is a drop-in replacement for the native C++ floating-point 47 types, but with much greater precision. 48 </p> 49<p> 50 Type <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code> can 51 be used at fixed precision by specifying a non-zero <code class="computeroutput"><span class="identifier">Digits10</span></code> 52 template parameter. The typedefs <code class="computeroutput"><span class="identifier">cpp_dec_float_50</span></code> 53 and <code class="computeroutput"><span class="identifier">cpp_dec_float_100</span></code> provide 54 arithmetic types at 50 and 100 decimal digits precision respectively. Optionally, 55 you can specify an integer type to use for the exponent, this defaults 56 to a 32-bit integer type which is more than large enough for the vast majority 57 of use cases, but larger types such as <code class="computeroutput"><span class="keyword">long</span> 58 <span class="keyword">long</span></code> can also be specified if you 59 need a truly huge exponent range. In any case the ExponentType must be 60 a <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental 61 (built-in)</a> signed integer type at least 2 bytes and 16-bits wide. 62 </p> 63<p> 64 Normally <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code> 65 allocates no memory: all of the space required for its digits are allocated 66 directly within the class. As a result care should be taken not to use 67 the class with too high a digit count as stack space requirements can grow 68 out of control. If that represents a problem then providing an allocator 69 as the final template parameter causes <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code> 70 to dynamically allocate the memory it needs: this significantly reduces 71 the size of <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code> 72 and increases the viable upper limit on the number of digits at the expense 73 of performance. However, please bear in mind that arithmetic operations 74 rapidly become <span class="emphasis"><em>very</em></span> expensive as the digit count grows: 75 the current implementation really isn't optimized or designed for large 76 digit counts. 77 </p> 78<p> 79 There is full standard library and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code> 80 support available for this type. 81 </p> 82<p> 83 Things you should know when using this type: 84 </p> 85<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 86<li class="listitem"> 87 Default constructed <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code>s 88 have a value of zero. 89 </li> 90<li class="listitem"> 91 The radix of this type is 10. As a result it can behave subtly differently 92 from base-2 types. 93 </li> 94<li class="listitem"> 95 The type has a number of internal guard digits over and above those 96 specified in the template argument. Normally these should not be visible 97 to the user. 98 </li> 99<li class="listitem"> 100 The type supports both infinities and NaNs. An infinity is generated 101 whenever the result would overflow, and a NaN is generated for any 102 mathematically undefined operation. 103 </li> 104<li class="listitem"> 105 There is a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code> specialisation for 106 this type. 107 </li> 108<li class="listitem"> 109 Any <code class="computeroutput"><span class="identifier">number</span></code> instantiated 110 on this type, is convertible to any other <code class="computeroutput"><span class="identifier">number</span></code> 111 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_dec_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_dec_float</span><span class="special"><</span><span class="identifier">SomeOtherValue</span><span class="special">></span> <span class="special">></span></code>. 112 Narrowing conversions are truncating and <code class="computeroutput"><span class="keyword">explicit</span></code>. 113 </li> 114<li class="listitem"> 115 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> 116 being thrown if the string can not be interpreted as a valid floating-point 117 number. 118 </li> 119<li class="listitem"> 120 The actual precision of a <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code> 121 is always slightly higher than the number of digits specified in the 122 template parameter, actually how much higher is an implementation detail 123 but is always at least 8 decimal digits. 124 </li> 125<li class="listitem"> 126 Operations involving <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code> 127 are always truncating. However, note that since there are guard digits 128 in effect, in practice this has no real impact on accuracy for most 129 use cases. 130 </li> 131</ul></div> 132<h6> 133<a name="boost_multiprecision.tut.floats.cpp_dec_float.h0"></a> 134 <span class="phrase"><a name="boost_multiprecision.tut.floats.cpp_dec_float.cpp_dec_float_example"></a></span><a class="link" href="cpp_dec_float.html#boost_multiprecision.tut.floats.cpp_dec_float.cpp_dec_float_example">cpp_dec_float 135 example:</a> 136 </h6> 137<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_dec_float</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 138<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> 139<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 140 141<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> 142<span class="special">{</span> 143 <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> 144 145 <span class="comment">// Operations at fixed precision and full numeric_limits support:</span> 146 <span class="identifier">cpp_dec_float_100</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span> 147 <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_dec_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> 148 <span class="comment">// Note that digits10 is the same as digits, since we're base 10! :</span> 149 <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_dec_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> 150 <span class="comment">// We can use any C++ std lib function, lets print all the digits as well:</span> 151 <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_dec_float_100</span><span class="special">>::</span><span class="identifier">max_digits10</span><span class="special">)</span> 152 <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> 153 <span class="comment">// We can also use any function from Boost.Math:</span> 154 <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> 155 <span class="comment">// These even work when the argument is an expression template:</span> 156 <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> 157 <span class="comment">// And since we have an extended exponent range we can generate some really large </span> 158 <span class="comment">// numbers here (4.0238726007709377354370243e+2564):</span> 159 <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_dec_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> 160 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 161<span class="special">}</span> 162</pre> 163</div> 164<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 165<td align="left"></td> 166<td align="right"><div class="copyright-footer">Copyright © 2002-2020 John 167 Maddock and Christopher Kormanyos<p> 168 Distributed under the Boost Software License, Version 1.0. (See accompanying 169 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>) 170 </p> 171</div></td> 172</tr></table> 173<hr> 174<div class="spirit-nav"> 175<a accesskey="p" href="cpp_bin_float.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="gmp_float.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 176</div> 177</body> 178</html> 179
