1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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.12.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"> 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="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> 24</div> 25<div class="section"> 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> 29<p> 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>. 39 </p> 40<p> 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). 46 </p> 47<p> 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. 56 </p> 57<p> 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. 61 </p> 62<div class="note"><table border="0" summary="Note"> 63<tr> 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> 66</tr> 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>>. 74 </p></td></tr> 75</table></div> 76<div class="warning"><table border="0" summary="Warning"> 77<tr> 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> 80</tr> 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. 94 </p></td></tr> 95</table></div> 96<div class="warning"><table border="0" summary="Warning"> 97<tr> 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> 100</tr> 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. 107 </p></td></tr> 108</table></div> 109<div class="tip"><table border="0" summary="Tip"> 110<tr> 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> 113</tr> 114<tr><td align="left" valign="top"> 115<p> 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>. 120 </p> 121<p> 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. 130 </p> 131<p> 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. 135 </p> 136</td></tr> 137</table></div> 138</div> 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>) 148 </p> 149</div></td> 150</tr></table> 151<hr> 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> 154</div> 155</body> 156</html> 157
