libs/multiprecision/doc/html/boost_multiprecision/tut/limits/constants.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>std::numeric_limits&lt;&gt; constants</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="../limits.html" title="Numeric Limits">
   9 <link rel="prev" href="../limits.html" title="Numeric Limits">
  10 <link rel="next" href="functions.html" title="std::numeric_limits&lt;&gt; functions">
  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="../limits.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../limits.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="functions.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.limits.constants"></a><a class="link" href="constants.html" title="std::numeric_limits&lt;&gt; constants">std::numeric_limits&lt;&gt;
  28         constants</a>
  29 </h4></div></div></div>
  30 <h5>
  31 <a name="boost_multiprecision.tut.limits.constants.h0"></a>
  32           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.is_specialized"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.is_specialized">is_specialized</a>
  33         </h5>
  34 <p>
  35           <code class="computeroutput"><span class="keyword">true</span></code> for all arithmetic types
  36           (integer, floating and fixed-point) for which <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">numeric_limits</span></code>
  37           is specialized.
  38         </p>
  39 <p>
  40           A typical test is
  41         </p>
  42 <pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">is_specialized</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">)</span>
  43 <span class="special">{</span>
  44   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"type "</span> <span class="special">&lt;&lt;</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()</span>  <span class="special">&lt;&lt;</span> <span class="string">" is not specialized for std::numeric_limits!"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  45 <span class="comment">// ...</span>
  46 <span class="special">}</span>
  47 </pre>
  48 <p>
  49           Typically <code class="computeroutput"><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">is_specialized</span></code>
  50           is <code class="computeroutput"><span class="keyword">true</span></code> for all <code class="computeroutput"><span class="identifier">T</span></code> where the compile-time constant members
  51           of <code class="computeroutput"><span class="identifier">numeric_limits</span></code> are indeed
  52           known at compile time, and don't vary at runtime. For example floating-point
  53           types with runtime-variable precision such as <code class="computeroutput"><span class="identifier">mpfr_float</span></code>
  54           have no <code class="computeroutput"><span class="identifier">numeric_limits</span></code>
  55           specialization as it would be impossible to define all the members at compile
  56           time. In contrast the precision of a type such as <code class="computeroutput"><span class="identifier">mpfr_float_50</span></code>
  57           is known at compile time, and so it <span class="emphasis"><em>does</em></span> have a <code class="computeroutput"><span class="identifier">numeric_limits</span></code> specialization.
  58         </p>
  59 <p>
  60           Note that not all the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code>
  61           member constants and functions are meaningful for all user-defined types
  62           (UDT), such as the decimal and binary multiprecision types provided here.
  63           More information on this is given in the sections below.
  64         </p>
  65 <h5>
  66 <a name="boost_multiprecision.tut.limits.constants.h1"></a>
  67           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.infinity"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.infinity">infinity</a>
  68         </h5>
  69 <p>
  70           For floating-point types, &#8734; is defined wherever possible, but clearly infinity
  71           is meaningless for __arbitrary_precision arithmetic backends, and there
  72           is one floating-point type (GMP's <code class="computeroutput"><span class="identifier">mpf_t</span></code>,
  73           see <a class="link" href="../floats/gmp_float.html" title="gmp_float">gmp_float</a>)
  74           which has no notion of infinity or NaN at all.
  75         </p>
  76 <p>
  77           A typical test whether infinity is implemented is
  78         </p>
  79 <pre class="programlisting"><span class="keyword">if</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">has_infinity</span><span class="special">)</span>
  80 <span class="special">{</span>
  81    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  82 <span class="special">}</span>
  83 </pre>
  84 <p>
  85           and using tests like this is strongly recommended to improve portability.
  86         </p>
  87 <p>
  88           If the backend is switched to a type that does not support infinity then,
  89           without checks like this, there will be trouble.
  90         </p>
  91 <h5>
  92 <a name="boost_multiprecision.tut.limits.constants.h2"></a>
  93           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.is_signed"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.is_signed">is_signed</a>
  94         </h5>
  95 <p>
  96           <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">is_signed</span> <span class="special">==</span>
  97           <span class="keyword">true</span></code> if the type <code class="computeroutput"><span class="identifier">T</span></code>
  98           is signed.
  99         </p>
 100 <p>
 101           For built-in binary types, the sign is held in a single bit, but for other
 102           types (cpp_dec_float and cpp_bin_float) it may be a separate storage element,
 103           usually <code class="computeroutput"><span class="keyword">bool</span></code>.
 104         </p>
 105 <h5>
 106 <a name="boost_multiprecision.tut.limits.constants.h3"></a>
 107           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.is_exact"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.is_exact">is_exact</a>
 108         </h5>
 109 <p>
 110           <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">is_exact</span> <span class="special">==</span>
 111           <span class="keyword">true</span></code> if type T uses exact representations.
 112         </p>
 113 <p>
 114           This is defined as <code class="computeroutput"><span class="keyword">true</span></code> for
 115           all integer types and <code class="computeroutput"><span class="keyword">false</span></code>
 116           for floating-point types.
 117         </p>
 118 <p>
 119           <a href="http://stackoverflow.com/questions/14203654/stdnumeric-limitsis-exact-what-is-a-usable-definition" target="_top">A
 120           usable definition</a> has been discussed.
 121         </p>
 122 <p>
 123           ISO/IEC 10967-1, Language independent arithmetic, noted by the C++ Standard
 124           defines
 125         </p>
 126 <pre class="programlisting"><span class="identifier">A</span> <span class="identifier">floating</span><span class="special">-</span><span class="identifier">point</span> <span class="identifier">type</span> <span class="identifier">F</span> <span class="identifier">shall</span> <span class="identifier">be</span> <span class="identifier">a</span> <span class="identifier">finite</span> <span class="identifier">subset</span> <span class="identifier">of</span> <span class="special">[</span><span class="identifier">real</span><span class="special">].</span>
 127 </pre>
 128 <p>
 129           The important practical distinction is that all integers (up to <code class="computeroutput"><span class="identifier">max</span><span class="special">()</span></code>)
 130           can be stored exactly.
 131         </p>
 132 <p>
 133           <a href="http://en.wikipedia.org/wiki/Rational_number" target="_top">Rational</a>
 134           types using two integer types are also exact.
 135         </p>
 136 <p>
 137           Floating-point types <span class="bold"><strong>cannot store all real values</strong></span>
 138           (those in the set of &#8476;) <span class="bold"><strong>exactly</strong></span>. For example,
 139           0.5 can be stored exactly in a binary floating-point, but 0.1 cannot. What
 140           is stored is the nearest representable real value, that is, rounded to
 141           nearest.
 142         </p>
 143 <p>
 144           Fixed-point types (usually decimal) are also defined as exact, in that
 145           they only store a <span class="bold"><strong>fixed precision</strong></span>, so
 146           half cents or pennies (or less) cannot be stored. The results of computations
 147           are rounded up or down, just like the result of integer division stored
 148           as an integer result.
 149         </p>
 150 <p>
 151           There are number of proposals to <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3407.html" target="_top">add
 152           Decimal floating-point Support to C++</a>.
 153         </p>
 154 <p>
 155           <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2849.pdf" target="_top">Decimal
 156           TR</a>.
 157         </p>
 158 <p>
 159           And also <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html" target="_top">C++
 160           Binary Fixed-Point Arithmetic</a>.
 161         </p>
 162 <h5>
 163 <a name="boost_multiprecision.tut.limits.constants.h4"></a>
 164           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.is_bounded"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.is_bounded">is_bounded</a>
 165         </h5>
 166 <p>
 167           <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">is_bounded</span> <span class="special">==</span>
 168           <span class="keyword">true</span></code> if the set of values represented
 169           by the type <code class="computeroutput"><span class="identifier">T</span></code> is finite.
 170         </p>
 171 <p>
 172           This is <code class="computeroutput"><span class="keyword">true</span></code> for all built-in
 173           integer, fixed and floating-point types, and most multi-precision types.
 174         </p>
 175 <p>
 176           It is only <code class="computeroutput"><span class="keyword">false</span></code> for a few
 177           __arbitrary_precision types like <code class="computeroutput"><span class="identifier">cpp_int</span></code>.
 178         </p>
 179 <p>
 180           Rational and fixed-exponent representations are exact but not integer.
 181         </p>
 182 <h5>
 183 <a name="boost_multiprecision.tut.limits.constants.h5"></a>
 184           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.is_modulo"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.is_modulo">is_modulo</a>
 185         </h5>
 186 <p>
 187           <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">is_modulo</span></code> is defined as <code class="computeroutput"><span class="keyword">true</span></code> if adding two positive values of type
 188           T can yield a result less than either value.
 189         </p>
 190 <p>
 191           <code class="computeroutput"><span class="identifier">is_modulo</span> <span class="special">==</span>
 192           <span class="keyword">true</span></code> means that the type does not
 193           overflow, but, for example, 'wraps around' to zero, when adding one to
 194           the <code class="computeroutput"><span class="identifier">max</span><span class="special">()</span></code>
 195           value.
 196         </p>
 197 <p>
 198           For most built-in integer types, <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;::</span><span class="identifier">is_modulo</span></code>
 199           is <code class="computeroutput"><span class="keyword">true</span></code>.
 200         </p>
 201 <p>
 202           <code class="computeroutput"><span class="keyword">bool</span></code> is the only exception.
 203         </p>
 204 <p>
 205           The modulo behaviour is sometimes useful, but also can be unexpected, and
 206           sometimes undesired, behaviour.
 207         </p>
 208 <p>
 209           Overflow of signed integers can be especially unexpected, possibly causing
 210           change of sign.
 211         </p>
 212 <p>
 213           Boost.Multiprecision integer type <code class="computeroutput"><span class="identifier">cpp_int</span></code>
 214           is not modulo because as an __arbitrary_precision types, it expands to
 215           hold any value that the machine resources permit.
 216         </p>
 217 <p>
 218           However fixed precision <a class="link" href="../ints/cpp_int.html" title="cpp_int">cpp_int</a>'s
 219           may be modulo if they are unchecked (i.e. they behave just like built in
 220           integers), but not if they are checked (overflow causes an exception to
 221           be raised).
 222         </p>
 223 <p>
 224           Built-in and multi-precision floating-point types are normally not modulo.
 225         </p>
 226 <p>
 227           Where possible, overflow is to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>, provided <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;::</span><span class="identifier">has_infinity</span>
 228           <span class="special">==</span> <span class="keyword">true</span></code>.
 229         </p>
 230 <h5>
 231 <a name="boost_multiprecision.tut.limits.constants.h6"></a>
 232           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.radix"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.radix">radix</a>
 233         </h5>
 234 <p>
 235           Constant <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">radix</span></code> returns either 2 (for built-in
 236           and binary types) or 10 (for decimal types).
 237         </p>
 238 <h5>
 239 <a name="boost_multiprecision.tut.limits.constants.h7"></a>
 240           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.digits"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.digits">digits</a>
 241         </h5>
 242 <p>
 243           The number of <code class="computeroutput"><span class="identifier">radix</span></code> digits
 244           that be represented without change:
 245         </p>
 246 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 247 <li class="listitem">
 248               for integer types, the number of <span class="bold"><strong>non-sign bits</strong></span>
 249               in the significand.
 250             </li>
 251 <li class="listitem">
 252               for floating types, the number of <span class="bold"><strong>radix digits</strong></span>
 253               in the significand.
 254             </li>
 255 </ul></div>
 256 <p>
 257           The values include any implicit bit, so for example, for the ubiquious
 258           <code class="computeroutput"><span class="keyword">double</span></code> using 64 bits (<a href="http://en.wikipedia.org/wiki/Double_precision_floating-point_format" target="_top">IEEE
 259           binary64 </a>), <code class="computeroutput"><span class="identifier">digits</span></code>
 260           == 53, even though there are only 52 actual bits of the significand stored
 261           in the representation. The value of <code class="computeroutput"><span class="identifier">digits</span></code>
 262           reflects the fact that there is one implicit bit which is always set to
 263           1.
 264         </p>
 265 <p>
 266           The Boost.Multiprecision binary types do not use an implicit bit, so the
 267           <code class="computeroutput"><span class="identifier">digits</span></code> member reflects
 268           exactly how many bits of precision were requested:
 269         </p>
 270 <pre class="programlisting"><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">53</span><span class="special">,</span> <span class="identifier">digit_base_2</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">float64</span><span class="special">;</span>
 271 <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">113</span><span class="special">,</span> <span class="identifier">digit_base_2</span><span class="special">&gt;</span> <span class="special">&gt;</span>  <span class="identifier">float128</span><span class="special">;</span>
 272 <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">float64</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">==</span> <span class="number">53.</span>
 273 <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">float128</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">==</span> <span class="number">113.</span>
 274 </pre>
 275 <p>
 276           For the most common case of <code class="computeroutput"><span class="identifier">radix</span>
 277           <span class="special">==</span> <span class="number">2</span></code>,
 278           <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span></code> is the number of bits in the representation,
 279           not counting any sign bit.
 280         </p>
 281 <p>
 282           For a decimal integer type, when <code class="computeroutput"><span class="identifier">radix</span>
 283           <span class="special">==</span> <span class="number">10</span></code>,
 284           it is the number of decimal digits.
 285         </p>
 286 <h5>
 287 <a name="boost_multiprecision.tut.limits.constants.h8"></a>
 288           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.digits10"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.digits10">digits10</a>
 289         </h5>
 290 <p>
 291           Constant <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits10</span></code> returns the number of decimal
 292           digits that can be represented without change or loss.
 293         </p>
 294 <p>
 295           For example, <code class="computeroutput"><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">char</span><span class="special">&gt;::</span><span class="identifier">digits10</span></code> is 2.
 296         </p>
 297 <p>
 298           This somewhat inscrutable definition means that an <code class="computeroutput"><span class="keyword">unsigned</span>
 299           <span class="keyword">char</span></code> can hold decimal values <code class="computeroutput"><span class="number">0.</span><span class="special">.</span><span class="number">99</span></code>
 300           without loss of precision or accuracy, usually from truncation.
 301         </p>
 302 <p>
 303           Had the definition been 3 then that would imply it could hold 0..999, but
 304           as we all know, an 8-bit <code class="computeroutput"><span class="keyword">unsigned</span>
 305           <span class="keyword">char</span></code> can only hold 0..255, and an
 306           attempt to store 256 or more will involve loss or change.
 307         </p>
 308 <p>
 309           For bounded integers, it is thus <span class="bold"><strong>one less</strong></span>
 310           than number of decimal digits you need to display the biggest integer
 311           <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">max</span><span class="special">()</span></code>.
 312           This value can be used to predict the layout width required for
 313         </p>
 314 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span>
 315   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">short</span><span class="special">&gt;::</span><span class="identifier">digits10</span> <span class="special">+</span><span class="number">1</span> <span class="special">+</span><span class="number">1</span><span class="special">)</span> <span class="comment">// digits10+1, and +1 for sign.</span>
 316   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">showpos</span> <span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">short</span><span class="special">&gt;::</span><span class="identifier">max</span><span class="special">)()</span> <span class="comment">// +32767</span>
 317   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 318   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">short</span><span class="special">&gt;::</span><span class="identifier">digits10</span> <span class="special">+</span><span class="number">1</span> <span class="special">+</span><span class="number">1</span><span class="special">)</span>
 319   <span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">short</span><span class="special">&gt;::</span><span class="identifier">min</span><span class="special">)()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>   <span class="comment">// -32767</span>
 320 </pre>
 321 <p>
 322           For example, <code class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">short</span></code>
 323           is often stored in 16 bits, so the maximum value is 0xFFFF or 65535.
 324         </p>
 325 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span>
 326   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">short</span><span class="special">&gt;::</span><span class="identifier">digits10</span> <span class="special">+</span><span class="number">1</span> <span class="special">+</span><span class="number">1</span><span class="special">)</span> <span class="comment">// digits10+1, and +1 for sign.</span>
 327   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">showpos</span> <span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">short</span><span class="special">&gt;::</span><span class="identifier">max</span><span class="special">)()</span> <span class="comment">//  65535</span>
 328   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 329   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">short</span><span class="special">&gt;::</span><span class="identifier">digits10</span> <span class="special">+</span><span class="number">1</span> <span class="special">+</span><span class="number">1</span><span class="special">)</span> <span class="comment">// digits10+1, and +1 for sign.</span>
 330   <span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">short</span><span class="special">&gt;::</span><span class="identifier">min</span><span class="special">)()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>   <span class="comment">//      0</span>
 331 </pre>
 332 <p>
 333           For bounded floating-point types, if we create a <code class="computeroutput"><span class="keyword">double</span></code>
 334           with a value with <code class="computeroutput"><span class="identifier">digits10</span></code>
 335           (usually 15) decimal digits, <code class="computeroutput"><span class="number">1e15</span></code>
 336           or <code class="computeroutput"><span class="number">1000000000000000</span></code> :
 337         </p>
 338 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">);</span>
 339 <span class="keyword">double</span> <span class="identifier">d</span> <span class="special">=</span>  <span class="number">1e15</span><span class="special">;</span>
 340 <span class="keyword">double</span> <span class="identifier">dp1</span> <span class="special">=</span> <span class="identifier">d</span><span class="special">+</span><span class="number">1</span><span class="special">;</span>
 341 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">d</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span> <span class="special">&lt;&lt;</span> <span class="identifier">dp1</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 342 <span class="comment">// 1000000000000000</span>
 343 <span class="comment">// 1000000000000001</span>
 344 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>  <span class="identifier">dp1</span> <span class="special">-</span> <span class="identifier">d</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1</span>
 345 </pre>
 346 <p>
 347           and we can increment this value to <code class="computeroutput"><span class="number">1000000000000001</span></code>
 348           as expected and show the difference too.
 349         </p>
 350 <p>
 351           But if we try to repeat this with more than <code class="computeroutput"><span class="identifier">digits10</span></code>
 352           digits,
 353         </p>
 354 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">);</span>
 355 <span class="keyword">double</span> <span class="identifier">d</span> <span class="special">=</span>  <span class="number">1e16</span><span class="special">;</span>
 356 <span class="keyword">double</span> <span class="identifier">dp1</span> <span class="special">=</span> <span class="identifier">d</span><span class="special">+</span><span class="number">1</span><span class="special">;</span>
 357 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">d</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span> <span class="special">&lt;&lt;</span> <span class="identifier">dp1</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 358 <span class="comment">// 10000000000000000</span>
 359 <span class="comment">// 10000000000000000</span>
 360   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">dp1</span> <span class="special">-</span> <span class="identifier">d</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 0 !!!</span>
 361 </pre>
 362 <p>
 363           then we find that when we add one it has no effect, and display show that
 364           there is loss of precision. See <a href="http://en.wikipedia.org/wiki/Loss_of_significance" target="_top">Loss
 365           of significance or cancellation error</a>.
 366         </p>
 367 <p>
 368           So <code class="computeroutput"><span class="identifier">digits10</span></code> is the number
 369           of decimal digits <span class="bold"><strong>guaranteed</strong></span> to be correct.
 370         </p>
 371 <p>
 372           For example, 'round-tripping' for <code class="computeroutput"><span class="keyword">double</span></code>:
 373         </p>
 374 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 375 <li class="listitem">
 376               If a decimal string with at most <code class="computeroutput"><span class="identifier">digits10</span></code>(
 377               == 15) significant decimal digits is converted to <code class="computeroutput"><span class="keyword">double</span></code>
 378               and then converted back to the same number of significant decimal digits,
 379               then the final string will match the original 15 decimal digit string.
 380             </li>
 381 <li class="listitem">
 382               If a <code class="computeroutput"><span class="keyword">double</span></code> floating-point
 383               number is converted to a decimal string with at least 17 decimal digits
 384               and then converted back to <code class="computeroutput"><span class="keyword">double</span></code>,
 385               then the result will be binary identical to the original <code class="computeroutput"><span class="keyword">double</span></code> value.
 386             </li>
 387 </ul></div>
 388 <p>
 389           For most purposes, you will much more likely want <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;::</span><span class="identifier">max_digits10</span></code>,
 390           the number of decimal digits that ensure that a change of one least significant
 391           bit (ULP) produces a different decimal digits string.
 392         </p>
 393 <p>
 394           For the most common <code class="computeroutput"><span class="keyword">double</span></code>
 395           floating-point type,<code class="computeroutput"><span class="identifier">max_digits10</span></code>
 396           is <code class="computeroutput"><span class="identifier">digits10</span><span class="special">+</span><span class="number">2</span></code>, but you should use C++11 <code class="computeroutput"><span class="identifier">max_digits10</span></code> where possible (see <a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.max_digits10">below</a>).
 397         </p>
 398 <h5>
 399 <a name="boost_multiprecision.tut.limits.constants.h9"></a>
 400           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.max_digits10"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.max_digits10">max_digits10</a>
 401         </h5>
 402 <p>
 403           <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span></code> was added for floating-point
 404           because <code class="computeroutput"><span class="identifier">digits10</span></code> decimal
 405           digits are insufficient to show a least significant bit (ULP) change giving
 406           puzzling displays like
 407         </p>
 408 <pre class="programlisting"><span class="number">0.666666666666667</span> <span class="special">!=</span> <span class="number">0.666666666666667</span>
 409 </pre>
 410 <p>
 411           from failure to 'round-trip', for example:
 412         </p>
 413 <pre class="programlisting"><span class="keyword">double</span> <span class="identifier">write</span> <span class="special">=</span> <span class="number">2.</span><span class="special">/</span><span class="number">3</span><span class="special">;</span> <span class="comment">// Any arbitrary value that cannot be represented exactly.</span>
 414 <span class="keyword">double</span> <span class="identifier">read</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 415 <span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span> <span class="identifier">s</span><span class="special">;</span>
 416 <span class="identifier">s</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">digits10</span><span class="special">);</span> <span class="comment">// or `float64_t` for 64-bit IEE754 double.</span>
 417 <span class="identifier">s</span> <span class="special">&lt;&lt;</span> <span class="identifier">write</span><span class="special">;</span>
 418 <span class="identifier">s</span> <span class="special">&gt;&gt;</span> <span class="identifier">read</span><span class="special">;</span>
 419 <span class="keyword">if</span><span class="special">(</span><span class="identifier">read</span> <span class="special">!=</span> <span class="identifier">write</span><span class="special">)</span>
 420 <span class="special">{</span>
 421   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</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">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">digits10</span><span class="special">)</span>
 422     <span class="special">&lt;&lt;</span> <span class="identifier">read</span> <span class="special">&lt;&lt;</span> <span class="string">" != "</span> <span class="special">&lt;&lt;</span> <span class="identifier">write</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 423 <span class="special">}</span>
 424 </pre>
 425 <p>
 426           If you wish to ensure that a change of one least significant bit (ULP)
 427           produces a different decimal digits string, then <code class="computeroutput"><span class="identifier">max_digits10</span></code>
 428           is the precision to use.
 429         </p>
 430 <p>
 431           For example:
 432         </p>
 433 <pre class="programlisting"><span class="keyword">double</span> <span class="identifier">pi</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">double_constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">;</span>
 434 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">);</span>
 435 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">pi</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 3.1415926535897931</span>
 436 </pre>
 437 <p>
 438           will display &#960; to the maximum possible precision using a <code class="computeroutput"><span class="keyword">double</span></code>.
 439         </p>
 440 <p>
 441           and similarly for a much higher precision type:
 442         </p>
 443 <pre class="programlisting"><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>
 444
 445 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_dec_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_dec_float_50</span><span class="special">;</span> <span class="comment">// 50 decimal digits.</span>
 446
 447 <span class="keyword">using</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_50</span><span class="special">;</span>
 448
 449 <span class="identifier">cpp_dec_float_50</span> <span class="identifier">pi</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">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">&lt;</span><span class="identifier">cpp_dec_float_50</span><span class="special">&gt;();</span>
 450 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">cpp_dec_float_50</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">);</span>
 451 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">pi</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 452 <span class="comment">// 3.141592653589793238462643383279502884197169399375105820974944592307816406</span>
 453 </pre>
 454 <p>
 455           For integer types, <code class="computeroutput"><span class="identifier">max_digits10</span></code>
 456           is implementation-dependent, but is usually <code class="computeroutput"><span class="identifier">digits10</span>
 457           <span class="special">+</span> <span class="number">2</span></code>.
 458           This is the output field-width required for the maximum value of the type
 459           T <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">max</span><span class="special">()</span></code>
 460           <span class="emphasis"><em>including a sign and a space</em></span>.
 461         </p>
 462 <p>
 463           So this will produce neat columns.
 464         </p>
 465 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">)</span> <span class="special">...</span>
 466 </pre>
 467 <p>
 468           The extra two or three least-significant digits are 'noisy' and may be
 469           junk, but if you want to 'round-trip' - printing a value out as a decimal
 470           digit string and reading it back in - (most commonly during serialization
 471           and de-serialization) you must use <code class="computeroutput"><span class="identifier">os</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">)</span></code>.
 472         </p>
 473 <div class="note"><table border="0" summary="Note">
 474 <tr>
 475 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 476 <th align="left">Note</th>
 477 </tr>
 478 <tr><td align="left" valign="top"><p>
 479             For Microsoft Visual Studio 2010, <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span></code>
 480             is wrongly defined as 8. It should be 9.
 481           </p></td></tr>
 482 </table></div>
 483 <div class="note"><table border="0" summary="Note">
 484 <tr>
 485 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 486 <th align="left">Note</th>
 487 </tr>
 488 <tr><td align="left" valign="top">
 489 <p>
 490             For Microsoft Visual Studio before 2013 and the default floating-point
 491             format, a small range of double-precision floating-point values with
 492             a significand of approximately 0.0001 to 0.004 and exponent values of
 493             1010 to 1014 do not round-trip exactly being off by one least significant
 494             bit, for probably every third value of the significand.
 495           </p>
 496 <p>
 497             A workaround is using the scientific or exponential format <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">scientific</span></code>.
 498           </p>
 499 <p>
 500             Other compilers also fail to implement round-tripping entirely fault-free,
 501             for example, see <a href="https://www.exploringbinary.com/incorrectly-rounded-conversions-in-gcc-and-glibc/" target="_top">Incorrectly
 502             Rounded Conversions in GCC and GLIBC</a>.
 503           </p>
 504 <p>
 505             For more details see <a href="https://www.exploringbinary.com/incorrect-round-trip-conversions-in-visual-c-plus-plus/" target="_top">Incorrect
 506             Round-Trip Conversions in Visual C++</a>, and references therein
 507             and <a href="https://arxiv.org/pdf/1310.8121.pdf" target="_top">Easy Accurate Reading
 508             and Writing of Floating-Point Numbers, Aubrey Jaffer (August 2018)</a>.
 509           </p>
 510 <p>
 511             Microsoft VS2017 and other recent compilers, now use the <a href="https://doi.org/10.1145/3192366.3192369" target="_top">Ryu
 512             fast float-to-string conversion by Ulf Adams</a> algorithm, claimed
 513             to be both exact and fast for 32 and 64-bit floating-point numbers.
 514           </p>
 515 </td></tr>
 516 </table></div>
 517 <div class="note"><table border="0" summary="Note">
 518 <tr>
 519 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 520 <th align="left">Note</th>
 521 </tr>
 522 <tr><td align="left" valign="top"><p>
 523             BOOST_NO_CXX11_NUMERIC_LIMITS is a suitable feature-test macro to determine
 524             if <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span></code> is implemented on any
 525             platform.
 526           </p></td></tr>
 527 </table></div>
 528 <div class="note"><table border="0" summary="Note">
 529 <tr>
 530 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 531 <th align="left">Note</th>
 532 </tr>
 533 <tr><td align="left" valign="top"><p>
 534             <span class="emphasis"><em>requires cxx11_numeric_limits</em></span> is a suitable test
 535             for use of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span></code> to control if a target
 536             in a jamfile used by a Boost B2/bjam program is built, or not.
 537           </p></td></tr>
 538 </table></div>
 539 <p>
 540           If <code class="computeroutput"><span class="identifier">max_digits10</span></code> is not
 541           available, you should use the <a href="http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF" target="_top">Kahan
 542           formula for floating-point type T</a>.
 543         </p>
 544 <p>
 545           In C++, the equations for what Kahan (on page 4) describes as 'at least'
 546           and 'at most' are:
 547         </p>
 548 <pre class="programlisting"><span class="keyword">static</span> <span class="keyword">long</span> <span class="keyword">double</span> <span class="keyword">const</span> <span class="identifier">log10Two</span> <span class="special">=</span> <span class="number">0.30102999566398119521373889472449L</span><span class="special">;</span> <span class="comment">// log10(2.)</span>
 549
 550 <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">floor</span><span class="special">((</span><span class="identifier">significand_digits</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">log10Two</span><span class="special">));</span> <span class="comment">// == digits10  - 'at least' .</span>
 551 <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">ceil</span><span class="special">(</span><span class="number">1</span> <span class="special">+</span> <span class="identifier">significand_digits</span> <span class="special">*</span> <span class="identifier">log10Two</span><span class="special">));</span> <span class="comment">// == max_digits10  - 'at most'.</span>
 552 </pre>
 553 <p>
 554           Unfortunately, these cannot be evaluated (at least by C++03) at <span class="bold"><strong>compile-time</strong></span>. So the following expression is often
 555           used instead.
 556         </p>
 557 <pre class="programlisting"><span class="identifier">max_digits10</span> <span class="special">=</span> <span class="number">2</span> <span class="special">+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">*</span> <span class="number">3010U</span><span class="special">/</span><span class="number">10000U</span><span class="special">;</span>
 558
 559 <span class="comment">// == 2 + std::numeric_limits&lt;T&gt;::digits for double and 64-bit long double.</span>
 560 <span class="comment">// == 3 + std::numeric_limits&lt;T&gt;::digits for float,  80-bit long-double and __float128.</span>
 561 </pre>
 562 <p>
 563           often the actual values are computed for the C limits macros:
 564         </p>
 565 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">FLT_MAXDIG10</span> <span class="special">(</span><span class="number">2</span><span class="special">+</span><span class="identifier">FLT_MANT_DIG</span> <span class="special">*</span> <span class="number">3010U</span><span class="special">/</span><span class="number">10000U</span><span class="special">)</span>  <span class="comment">// 9</span>
 566 <span class="preprocessor">#define</span> <span class="identifier">DBL_MAXDIG10</span> <span class="special">(</span><span class="number">2</span><span class="special">+</span> <span class="special">(</span><span class="identifier">DBL_MANT_DIG</span> <span class="special">*</span> <span class="number">3010U</span><span class="special">)/</span><span class="number">10000U</span><span class="special">)</span> <span class="comment">// 17</span>
 567 <span class="preprocessor">#define</span> <span class="identifier">LDBL_MAXDIG10</span> <span class="special">(</span><span class="number">2</span><span class="special">+</span> <span class="special">(</span><span class="identifier">LDBL_MANT_DIG</span> <span class="special">*</span> <span class="number">3010U</span><span class="special">)/</span><span class="number">10000U</span><span class="special">)</span> <span class="comment">// 17 for MSVC, 18 for others.</span>
 568 </pre>
 569 <p>
 570           The factor 3010U/10000U is <span class="emphasis"><em>log<sub>10</sub>(2) = 0.3010</em></span> that
 571           can be evaluated at compile-time using only <code class="computeroutput"><span class="keyword">short</span>
 572           <span class="keyword">unsigned</span> <span class="keyword">int</span></code>s
 573           to be a desirable <code class="computeroutput"><span class="keyword">const</span></code> or
 574           <code class="computeroutput"><span class="keyword">constexpr</span></code> (and usually also
 575           <code class="computeroutput"><span class="keyword">static</span></code>).
 576         </p>
 577 <p>
 578           Boost macros allow this to be done portably, see <a href="http://www.boost.org/doc/libs/1_58_0/libs/config/doc/html/boost_config/boost_macro_reference.html" target="_top">BOOST_CONSTEXPR_OR_CONST
 579           or BOOST_STATIC_CONSTEXPR</a>.
 580         </p>
 581 <p>
 582           (See also <a href="http://www.loria.fr/~zimmerma/mca/mca-cup-0.5.9.pdf" target="_top">Richard
 583           P. Brent and Paul Zimmerman, Modern Computer Arithmetic</a> Equation
 584           3.8 on page 116).
 585         </p>
 586 <p>
 587           For example, to be portable (including obselete platforms) for type <code class="computeroutput"><span class="identifier">T</span></code> where <code class="computeroutput"><span class="identifier">T</span></code>
 588           may be: <code class="computeroutput"><span class="keyword">float</span></code>, <code class="computeroutput"><span class="keyword">double</span></code>, <code class="computeroutput"><span class="keyword">long</span>
 589           <span class="keyword">double</span></code>, <code class="computeroutput"><span class="number">128</span><span class="special">-</span><span class="identifier">bit</span> <span class="identifier">quad</span> <span class="identifier">type</span></code>,
 590           <code class="computeroutput"><span class="identifier">cpp_bin_float_50</span></code> ...
 591         </p>
 592 <pre class="programlisting">  <span class="keyword">typedef</span> <span class="keyword">float</span> <span class="identifier">T</span><span class="special">;</span>
 593
 594 <span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_NO_CXX11_NUMERIC_LIMITS</span>
 595    <span class="comment">// No max_digits10 implemented.</span>
 596     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">max_digits10</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;());</span>
 597 <span class="preprocessor">#else</span>
 598   <span class="preprocessor">#if</span><span class="special">(</span><span class="identifier">_MSC_VER</span> <span class="special">&lt;=</span> <span class="number">1600</span><span class="special">)</span>
 599    <span class="comment">//  Wrong value for std::numeric_limits&lt;float&gt;::max_digits10.</span>
 600     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">max_digits10</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;());</span>
 601   <span class="preprocessor">#else</span> <span class="comment">// Use the C++11 max_digits10.</span>
 602      <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">);</span>
 603   <span class="preprocessor">#endif</span>
 604 <span class="preprocessor">#endif</span>
 605
 606   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"std::cout.precision(max_digits10) = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 9</span>
 607
 608   <span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1.2345678901234567889</span><span class="special">;</span>
 609
 610   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"x = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">x</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">//</span>
 611 </pre>
 612 <p>
 613           which should output:
 614         </p>
 615 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">max_digits10</span><span class="special">)</span> <span class="special">=</span> <span class="number">9</span>
 616 <span class="identifier">x</span> <span class="special">=</span> <span class="number">1.23456789</span>
 617 </pre>
 618 <h5>
 619 <a name="boost_multiprecision.tut.limits.constants.h10"></a>
 620           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.round_style"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.round_style">round_style</a>
 621         </h5>
 622 <p>
 623           The rounding style determines how the result of floating-point operations
 624           is treated when the result cannot be <span class="bold"><strong>exactly represented</strong></span>
 625           in the significand. Various rounding modes may be provided:
 626         </p>
 627 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 628 <li class="listitem">
 629               round to nearest up or down (default for floating-point types).
 630             </li>
 631 <li class="listitem">
 632               round up (toward positive infinity).
 633             </li>
 634 <li class="listitem">
 635               round down (toward negative infinity).
 636             </li>
 637 <li class="listitem">
 638               round toward zero (integer types).
 639             </li>
 640 <li class="listitem">
 641               no rounding (if decimal radix).
 642             </li>
 643 <li class="listitem">
 644               rounding mode is not determinable.
 645             </li>
 646 </ul></div>
 647 <p>
 648           For integer types, <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">round_style</span></code>
 649           is always towards zero, so
 650         </p>
 651 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">round_style</span> <span class="special">==</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">round_to_zero</span><span class="special">;</span>
 652 </pre>
 653 <p>
 654           A decimal type, <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code>
 655           rounds in no particular direction, which is to say it doesn't round at
 656           all. And since there are several guard digits, it's not really the same
 657           as truncation (round toward zero) either.
 658         </p>
 659 <p>
 660           For floating-point types, it is normal to round to nearest.
 661         </p>
 662 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">round_style</span> <span class="special">==</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">round_to_nearest</span><span class="special">;</span>
 663 </pre>
 664 <p>
 665           See function <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">round_error</span></code> for the maximum error (in
 666           ULP) that rounding can cause.
 667         </p>
 668 <h5>
 669 <a name="boost_multiprecision.tut.limits.constants.h11"></a>
 670           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.has_denorm_loss"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.has_denorm_loss">has_denorm_loss</a>
 671         </h5>
 672 <p>
 673           <code class="computeroutput"><span class="keyword">true</span></code> if a loss of precision
 674           is detected as a <a href="http://en.wikipedia.org/wiki/Denormalization" target="_top">denormalization</a>
 675           loss, rather than an inexact result.
 676         </p>
 677 <p>
 678           Always <code class="computeroutput"><span class="keyword">false</span></code> for integer types.
 679         </p>
 680 <p>
 681           <code class="computeroutput"><span class="keyword">false</span></code> for all types which
 682           do not have <code class="computeroutput"><span class="identifier">has_denorm</span></code>
 683           == <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">denorm_present</span></code>.
 684         </p>
 685 <h5>
 686 <a name="boost_multiprecision.tut.limits.constants.h12"></a>
 687           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.denorm_style"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.denorm_style">denorm_style</a>
 688         </h5>
 689 <p>
 690           <a href="http://en.wikipedia.org/wiki/Denormal_number" target="_top">Denormalized
 691           values</a> are representations with a variable number of exponent bits
 692           that can permit gradual underflow, so that, if type T is <code class="computeroutput"><span class="keyword">double</span></code>.
 693         </p>
 694 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">denorm_min</span><span class="special">()</span> <span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">min</span><span class="special">()</span>
 695 </pre>
 696 <p>
 697           A type may have any of the following <code class="computeroutput"><span class="keyword">enum</span>
 698           <span class="identifier">float_denorm_style</span></code> values:
 699         </p>
 700 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 701 <li class="listitem">
 702               <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">denorm_absent</span></code>, if it does not allow
 703               denormalized values. (Always used for all integer and exact types).
 704             </li>
 705 <li class="listitem">
 706               <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">denorm_present</span></code>, if the floating-point
 707               type allows denormalized values.
 708             </li>
 709 <li class="listitem">
 710               <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">denorm_indeterminate</span></code>, if indeterminate
 711               at compile time.
 712             </li>
 713 </ul></div>
 714 <h5>
 715 <a name="boost_multiprecision.tut.limits.constants.h13"></a>
 716           <span class="phrase"><a name="boost_multiprecision.tut.limits.constants.tinyness_before_rounding"></a></span><a class="link" href="constants.html#boost_multiprecision.tut.limits.constants.tinyness_before_rounding">Tinyness
 717           before rounding</a>
 718         </h5>
 719 <p>
 720           <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">tinyness_before</span></code>
 721         </p>
 722 <p>
 723           <code class="computeroutput"><span class="keyword">true</span></code> if a type can determine
 724           that a value is too small to be represent as a normalized value before
 725           rounding it.
 726         </p>
 727 <p>
 728           Generally true for <code class="computeroutput"><span class="identifier">is_iec559</span></code>
 729           floating-point built-in types, but false for integer types.
 730         </p>
 731 <p>
 732           Standard-compliant IEEE 754 floating-point implementations may detect the
 733           floating-point underflow at three predefined moments:
 734         </p>
 735 <div class="orderedlist"><ol class="orderedlist" type="1">
 736 <li class="listitem">
 737               After computation of a result with absolute value smaller than <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">min</span><span class="special">()</span></code>,
 738               such implementation detects <span class="emphasis"><em>tinyness before rounding</em></span>
 739               (e.g. UltraSparc).
 740             </li>
 741 <li class="listitem">
 742               After rounding of the result to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span></code>
 743               bits, if the result is tiny, such implementation detects <span class="emphasis"><em>tinyness
 744               after rounding</em></span> (e.g. SuperSparc).
 745             </li>
 746 <li class="listitem">
 747               If the conversion of the rounded tiny result to subnormal form resulted
 748               in the loss of precision, such implementation detects <span class="emphasis"><em>denorm
 749               loss</em></span>.
 750             </li>
 751 </ol></div>
 752 </div>
 753 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 754 <td align="left"></td>
 755 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2019 John Maddock
 756       and Christopher Kormanyos<p>
 757         Distributed under the Boost Software License, Version 1.0. (See accompanying
 758         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>)
 759       </p>
 760 </div></td>
 761 </tr></table>
 762 <hr>
 763 <div class="spirit-nav">
 764 <a accesskey="p" href="../limits.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../limits.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="functions.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 765 </div>
 766 </body>
 767 </html>