boost/math
2
0
Fork 0
mirror of https://github.com/boostorg/math.git synced 2026-01-19 04:22:09 +00:00
Code Issues Projects Releases Wiki Activity
Files
develop
math/doc/html/math_toolkit/exact_typdefs.html
jzmaddock 4c2cdc2cf6 Regenerate docs.
2024-08-06 13:18:32 +01:00

175 lines
16 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Exact-Width Floating-Point typedefs</title>
<link rel="stylesheet" href="../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Math Toolkit 4.2.1">
<link rel="up" href="../cstdfloat.html" title="Chapter 3. Specified-width floating-point typedefs">
<link rel="prev" href="rationale.html" title="Rationale">
<link rel="next" href="minimum_typdefs.html" title="Minimum-width floating-point typedefs">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cstdfloat.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="minimum_typdefs.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="math_toolkit.exact_typdefs"></a><a class="link" href="exact_typdefs.html" title="Exact-Width Floating-Point typedefs">Exact-Width Floating-Point
<code class="computeroutput"><span class="keyword">typedef</span></code>s</a>
</h2></div></div></div>
<p>
The <code class="computeroutput"><span class="keyword">typedef</span> <span class="keyword">float</span><span class="special">#</span><span class="identifier">_t</span></code>, with
# replaced by the width, designates a floating-point type of exactly # bits.
For example <code class="computeroutput"><span class="identifier">float32_t</span></code> denotes
a single-precision floating-point type with approximately 7 decimal digits
of precision (equivalent to binary32 in <a href="http://en.wikipedia.org/wiki/IEEE_floating_point" target="_top">IEEE_floating_point</a>).
</p>
<p>
Floating-point types in C and C++ are specified to be allowed to have (optionally)
implementation-specific widths and formats. However, if a platform supports
underlying floating-point types (conformant with <a href="http://en.wikipedia.org/wiki/IEEE_floating_point" target="_top">IEEE_floating_point</a>)
with widths of 16, 32, 64, 80, 128 bits, or any combination thereof, then
<code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">cstdfloat</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
does provide the corresponding <code class="computeroutput"><span class="keyword">typedef</span></code>s
<code class="computeroutput"><span class="identifier">float16_t</span><span class="special">,</span>
<span class="identifier">float32_t</span><span class="special">,</span>
<span class="identifier">float64_t</span><span class="special">,</span>
<span class="identifier">float80_t</span><span class="special">,</span>
<span class="identifier">float128_t</span><span class="special">,</span></code>
their corresponding least and fast types, and the corresponding maximum-width
type.
</p>
<h5>
<a name="math_toolkit.exact_typdefs.h0"></a>
<span class="phrase"><a name="math_toolkit.exact_typdefs.how_to_tell_which_widths_are_sup"></a></span><a class="link" href="exact_typdefs.html#math_toolkit.exact_typdefs.how_to_tell_which_widths_are_sup">How to
tell which widths are supported</a>
</h5>
<p>
The definition (or not) of a <a class="link" href="macros.html" title="Floating-Point Constant Macros">floating-point
constant macro</a> is a way to test if a <span class="bold"><strong>specific
width floating-point</strong></span> is available on a platform.
</p>
<pre class="programlisting"><span class="preprocessor">#if</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">BOOST_FLOAT16_C</span><span class="special">)</span>
<span class="comment">// Can use boost::float16_t, perhaps a proposed __short_float.</span>
<span class="comment">// P0192R1, Adding Fundamental Type for Short Float,</span>
<span class="comment">// Boris Fomitchev, Sergei Nikolaev, Olivier Giroux, Lawrence Crowl, 2016 Feb14</span>
<span class="comment">// http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2016.pdf</span>
<span class="preprocessor">#endif</span>
<span class="preprocessor">#if</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">BOOST_FLOAT32_C</span><span class="special">)</span>
<span class="comment">// Can use boost::float32_t, usually type `float`.</span>
<span class="preprocessor">#endif</span>
<span class="preprocessor">#if</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">BOOST_FLOAT64_C</span><span class="special">)</span>
<span class="comment">// Can use boost::float64_t, usually type `double`, and sometimes also type `long double`.</span>
<span class="preprocessor">#endif</span>
<span class="preprocessor">#if</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">BOOST_FLOAT80_C</span><span class="special">)</span>
<span class="comment">// Can use boost::float80_t, sometimes type `long double`.</span>
<span class="preprocessor">#endif</span>
<span class="preprocessor">#if</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">BOOST_FLOAT128_C</span><span class="special">)</span>
<span class="comment">// Can use boost::float128_t. Sometimes type `__float128` or `_Quad`.</span>
<span class="preprocessor">#endif</span>
</pre>
<p>
This can be used to write code which will compile and run (albeit differently)
on several platforms. Without these tests, if a width, say <code class="computeroutput"><span class="identifier">float128_t</span></code>
is not supported, then compilation would fail. (It is, of course, rare for
<code class="computeroutput"><span class="identifier">float64_t</span></code> or <code class="computeroutput"><span class="identifier">float32_t</span></code> not to be supported).
</p>
<p>
The number of bits in just the significand can be determined using:
</p>
<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">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">digits</span>
</pre>
<p>
and from this one can safely infer the total number of bits because the type
must be IEEE754 format, <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">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">is_iec559</span>
<span class="special">==</span> <span class="keyword">true</span></code>,
so, for example, 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="identifier">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">==</span> <span class="number">113</span></code>, then
<code class="computeroutput"><span class="identifier">floatmax_t</span></code> must be<code class="computeroutput"> <span class="identifier">float128_t</span></code>.
</p>
<p>
The <span class="bold"><strong>total</strong></span> number of bits using <code class="computeroutput"><span class="identifier">floatmax_t</span></code> can be found thus:
</p>
<pre class="programlisting"><span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">fpbits</span> <span class="special">=</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">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">==</span> <span class="number">113</span><span class="special">)</span> <span class="special">?</span> <span class="number">128</span> <span class="special">:</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">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">==</span> <span class="number">64</span><span class="special">)</span> <span class="special">?</span> <span class="number">80</span> <span class="special">:</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">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">==</span> <span class="number">53</span><span class="special">)</span> <span class="special">?</span> <span class="number">64</span> <span class="special">:</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">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">==</span> <span class="number">24</span><span class="special">)</span> <span class="special">?</span> <span class="number">32</span> <span class="special">:</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">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">==</span> <span class="number">11</span><span class="special">)</span> <span class="special">?</span> <span class="number">16</span> <span class="special">:</span>
<span class="number">0</span><span class="special">;</span> <span class="comment">// Unknown - not IEEE754 format.</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fpbits</span> <span class="special">&lt;&lt;</span> <span class="string">" bits."</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>
</pre>
<p>
and the number of 'guaranteed' decimal digits using
</p>
<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">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">digits10</span>
</pre>
<p>
and the maximum number of possibly significant decimal digits using
</p>
<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">boost</span><span class="special">::</span><span class="identifier">floatmax_t</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span>
</pre>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
<code class="computeroutput"><span class="identifier">max_digits10</span></code> is not always
supported, but can be calculated at compile-time using the Kahan formula,
<code class="computeroutput"><span class="number">2</span> <span class="special">+</span>
<span class="identifier">binary_digits</span> <span class="special">*</span>
<span class="number">0.3010</span></code> which can be calculated <span class="bold"><strong>at compile time</strong></span> using <code class="computeroutput"><span class="number">2</span>
<span class="special">+</span> <span class="identifier">binary_digits</span>
<span class="special">*</span> <span class="number">3010</span><span class="special">/</span><span class="number">10000</span></code>.
</p></td></tr>
</table></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>
One could test that
</p>
<p>
std::is_same&lt;boost::floatmax_t, boost::float128_t&gt;::value == true
</p>
<p>
but this would fail to compile on a platform where <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">float128_t</span></code>
is not defined. So it is better to use the MACROs <code class="computeroutput"><span class="identifier">BOOST_FLOATnnn_C</span></code>.
</p>
</td></tr>
</table></div>
</div>
<div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
Walker and Xiaogang Zhang<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cstdfloat.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="minimum_typdefs.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink