generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
boost/libs/math/doc/html/math_toolkit/rationale.html
Edouard DUPIN d0115b733d [DEV] add v1.76.0
2021-10-05 21:37:46 +02:00

157 lines
15 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>Rationale</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 3.0.0">
<link rel="up" href="../cstdfloat.html" title="Chapter 3. Specified-width floating-point typedefs">
<link rel="prev" href="specified_typedefs.html" title="Overview">
<link rel="next" href="exact_typdefs.html" title="Exact-Width Floating-Point typedefs">
</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="specified_typedefs.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="exact_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.rationale"></a><a class="link" href="rationale.html" title="Rationale">Rationale</a>
</h2></div></div></div>
<p>
The implementation of <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>
is designed to utilize <code class="computeroutput"><span class="special">&lt;</span><span class="keyword">float</span><span class="special">.</span><span class="identifier">h</span><span class="special">&gt;</span></code>,
defined in the 1989 C standard. The preprocessor is used to query certain preprocessor
definitions in <code class="computeroutput"><span class="special">&lt;</span><span class="keyword">float</span><span class="special">.</span><span class="identifier">h</span><span class="special">&gt;</span></code>
such as FLT_MAX, DBL_MAX, etc. Based on the results of these queries, an attempt
is made to automatically detect the presence of built-in floating-point types
having specified widths. An unequivocal test requiring conformance with <a href="http://en.wikipedia.org/wiki/IEEE_floating_point" target="_top">IEEE_floating_point</a>
(IEC599) based on <a href="http://en.cppreference.com/w/cpp/types/numeric_limits/is_iec559" target="_top"><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_iec559</span></code></a>
is performed with <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span></code>.
</p>
<p>
In addition, this Boost implementation <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>
supports an 80-bit floating-point <code class="computeroutput"><span class="keyword">typedef</span></code>
if it can be detected, and a 128-bit floating-point <code class="computeroutput"><span class="keyword">typedef</span></code>
if it can be detected, provided that the underlying types conform with <a href="http://en.wikipedia.org/wiki/Extended_precision" target="_top">IEEE-754 precision extension</a>
(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">is_iec559</span> <span class="special">==</span> <span class="keyword">true</span></code> for this type).
</p>
<p>
The header <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>
makes the standardized floating-point <code class="computeroutput"><span class="keyword">typedef</span></code>s
safely available in <code class="computeroutput"><span class="keyword">namespace</span> <span class="identifier">boost</span></code> without placing any names in <code class="computeroutput"><span class="keyword">namespace</span> <span class="identifier">std</span></code>.
The intention is to complement rather than compete with a potential future
C/C++ Standard Library that may contain these <code class="computeroutput"><span class="keyword">typedef</span></code>s.
Should some future C/C++ standard include <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">stdfloat</span><span class="special">.</span><span class="identifier">h</span><span class="special">&gt;</span></code> and
<code class="computeroutput"><span class="special">&lt;</span><span class="identifier">cstdfloat</span><span class="special">&gt;</span></code>, 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>
will continue to function, but will become redundant and may be safely deprecated.
</p>
<p>
Because <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>
is a Boost header, its name conforms to the boost header naming conventions,
not the C++ Standard Library header naming conventions.
</p>
<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>
<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>
<span class="bold"><strong>cannot synthesize or create a <code class="computeroutput"><span class="keyword">typedef</span></code>
if the underlying type is not provided by the compiler</strong></span>. For example,
if a compiler does not have an underlying floating-point type with 128 bits
(highly sought-after in scientific and numeric programming), then <code class="computeroutput"><span class="identifier">float128_t</span></code> and its corresponding least
and fast types are <span class="bold"><strong>not</strong></span> provided by <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></code>&gt;.
</p></td></tr>
</table></div>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
If <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>
uses a compiler-specific non-standardized type (<span class="bold"><strong>not</strong></span>
derived from <code class="computeroutput"><span class="keyword">float</span><span class="special">,</span>
<span class="keyword">double</span><span class="special">,</span></code>
or <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>)
for one or more of its floating-point <code class="computeroutput"><span class="keyword">typedef</span></code>s,
then there is no guarantee that specializations of <code class="computeroutput"><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;</span></code> will be available for these types.
Typically, specializations of <code class="computeroutput"><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;</span></code> will only be available for these
types if the compiler itself supports corresponding specializations for the
underlying type(s), exceptions are GCC's <code class="computeroutput"><span class="identifier">__float128</span></code>
type and Intel's <code class="computeroutput"><span class="identifier">_Quad</span></code> type
which are explicitly supported via our own code.
</p></td></tr>
</table></div>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
As an implementation artifact, certain C macro names from <code class="computeroutput"><span class="special">&lt;</span><span class="keyword">float</span><span class="special">.</span><span class="identifier">h</span><span class="special">&gt;</span></code> may possibly be visible to users of
<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>.
Don't rely on using these macros; they are not part of any Boost-specified
interface. Use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;</span></code>
for floating-point ranges, etc. instead.
</p></td></tr>
</table></div>
<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>
For best results, <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>
should be <code class="computeroutput"><span class="preprocessor">#include</span></code>d before
other headers that define generic code making use of standard library functions
defined in &lt;cmath&gt;.
</p>
<p>
This is because <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>
may define overloads of standard library functions where a non-standard type
(i.e. other than <code class="computeroutput"><span class="keyword">float</span></code>, <code class="computeroutput"><span class="keyword">double</span></code>, or <code class="computeroutput"><span class="keyword">long</span>
<span class="keyword">double</span></code>) is used for one of the specified
width types. If generic code (for example in another Boost.Math header) calls
a standard library function, then the correct overload will only be found
if these overloads are defined prior to the point of use. See <a class="link" href="float128/overloading.html" title="Overloading template functions with float128_t">overloading
template functions with float128_t</a> and the implementation of <code class="computeroutput"><span class="identifier">cstdfloat</span><span class="special">.</span><span class="identifier">hpp</span></code> for more details.
</p>
<p>
For this reason, making <code class="computeroutput"><span class="preprocessor">#include</span>
<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>
the <span class="bold"><strong>first include</strong></span> is usually best.
</p>
</td></tr>
</table></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><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></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="specified_typedefs.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="exact_typdefs.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink