3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Rationale</title>
5 <link rel="stylesheet" href="../math.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="../index.html" title="Math Toolkit 2.11.0">
8 <link rel="up" href="../cstdfloat.html" title="Chapter 3. Specified-width floating-point typedefs">
9 <link rel="prev" href="specified_typedefs.html" title="Overview">
10 <link rel="next" href="exact_typdefs.html" title="Exact-Width Floating-Point typedefs">
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>
22 <div class="spirit-nav">
23 <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>
26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
27 <a name="math_toolkit.rationale"></a><a class="link" href="rationale.html" title="Rationale">Rationale</a>
28 </h2></div></div></div>
30 The implementation of <code class="computeroutput"><span class="special"><</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">></span></code>
31 is designed to utilize <code class="computeroutput"><span class="special"><</span><span class="keyword">float</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code>,
32 defined in the 1989 C standard. The preprocessor is used to query certain preprocessor
33 definitions in <code class="computeroutput"><span class="special"><</span><span class="keyword">float</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code>
34 such as FLT_MAX, DBL_MAX, etc. Based on the results of these queries, an attempt
35 is made to automatically detect the presence of built-in floating-point types
36 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>
37 (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"><>::</span><span class="identifier">is_iec559</span></code></a>
38 is performed with <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span></code>.
41 In addition, this Boost implementation <code class="computeroutput"><span class="special"><</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">></span></code>
42 supports an 80-bit floating-point <code class="computeroutput"><span class="keyword">typedef</span></code>
43 if it can be detected, and a 128-bit floating-point <code class="computeroutput"><span class="keyword">typedef</span></code>
44 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>
45 (provided <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><>::</span><span class="identifier">is_iec559</span> <span class="special">==</span> <span class="keyword">true</span></code> for this type).
48 The header <code class="computeroutput"><span class="special"><</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">></span></code>
49 makes the standardized floating-point <code class="computeroutput"><span class="keyword">typedef</span></code>s
50 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>.
51 The intention is to complement rather than compete with a potential future
52 C/C++ Standard Library that may contain these <code class="computeroutput"><span class="keyword">typedef</span></code>s.
53 Should some future C/C++ standard include <code class="computeroutput"><span class="special"><</span><span class="identifier">stdfloat</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code> and
54 <code class="computeroutput"><span class="special"><</span><span class="identifier">cstdfloat</span><span class="special">></span></code>, then <code class="computeroutput"><span class="special"><</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">></span></code>
55 will continue to function, but will become redundant and may be safely deprecated.
58 Because <code class="computeroutput"><span class="special"><</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">></span></code>
59 is a Boost header, its name conforms to the boost header naming conventions,
60 not the C++ Standard Library header naming conventions.
62 <div class="note"><table border="0" summary="Note">
64 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
65 <th align="left">Note</th>
67 <tr><td align="left" valign="top"><p>
68 <code class="computeroutput"><span class="special"><</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">></span></code>
69 <span class="bold"><strong>cannot synthesize or create a <code class="computeroutput"><span class="keyword">typedef</span></code>
70 if the underlying type is not provided by the compiler</strong></span>. For example,
71 if a compiler does not have an underlying floating-point type with 128 bits
72 (highly sought-after in scientific and numeric programming), then <code class="computeroutput"><span class="identifier">float128_t</span></code> and its corresponding least
73 and fast types are <span class="bold"><strong>not</strong></span> provided by <code class="computeroutput"><span class="special"><</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>>.
76 <div class="warning"><table border="0" summary="Warning">
78 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
79 <th align="left">Warning</th>
81 <tr><td align="left" valign="top"><p>
82 If <code class="computeroutput"><span class="special"><</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">></span></code>
83 uses a compiler-specific non-standardized type (<span class="bold"><strong>not</strong></span>
84 derived from <code class="computeroutput"><span class="keyword">float</span><span class="special">,</span>
85 <span class="keyword">double</span><span class="special">,</span></code>
86 or <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>)
87 for one or more of its floating-point <code class="computeroutput"><span class="keyword">typedef</span></code>s,
88 then there is no guarantee that specializations of <code class="computeroutput"><span class="identifier">numeric_limits</span><span class="special"><></span></code> will be available for these types.
89 Typically, specializations of <code class="computeroutput"><span class="identifier">numeric_limits</span><span class="special"><></span></code> will only be available for these
90 types if the compiler itself supports corresponding specializations for the
91 underlying type(s), exceptions are GCC's <code class="computeroutput"><span class="identifier">__float128</span></code>
92 type and Intel's <code class="computeroutput"><span class="identifier">_Quad</span></code> type
93 which are explicitly supported via our own code.
96 <div class="warning"><table border="0" summary="Warning">
98 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
99 <th align="left">Warning</th>
101 <tr><td align="left" valign="top"><p>
102 As an implementation artifact, certain C macro names from <code class="computeroutput"><span class="special"><</span><span class="keyword">float</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code> may possibly be visible to users of
103 <code class="computeroutput"><span class="special"><</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">></span></code>.
104 Don't rely on using these macros; they are not part of any Boost-specified
105 interface. Use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><></span></code>
106 for floating-point ranges, etc. instead.
109 <div class="tip"><table border="0" summary="Tip">
111 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../doc/src/images/tip.png"></td>
112 <th align="left">Tip</th>
114 <tr><td align="left" valign="top">
116 For best results, <code class="computeroutput"><span class="special"><</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">></span></code>
117 should be <code class="computeroutput"><span class="preprocessor">#include</span></code>d before
118 other headers that define generic code making use of standard library functions
119 defined in <cmath>.
122 This is because <code class="computeroutput"><span class="special"><</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">></span></code>
123 may define overloads of standard library functions where a non-standard type
124 (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>
125 <span class="keyword">double</span></code>) is used for one of the specified
126 width types. If generic code (for example in another Boost.Math header) calls
127 a standard library function, then the correct overload will only be found
128 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
129 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.
132 For this reason, making <code class="computeroutput"><span class="preprocessor">#include</span>
133 <span class="special"><</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">></span></code>
134 the <span class="bold"><strong>first include</strong></span> is usually best.
139 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
140 <td align="left"></td>
141 <td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar
142 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
143 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
144 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
145 Daryle Walker and Xiaogang Zhang<p>
146 Distributed under the Boost Software License, Version 1.0. (See accompanying
147 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>)
152 <div class="spirit-nav">
153 <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>