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.77.1">
7 <link rel=
"home" href=
"../index.html" title=
"Math Toolkit 2.5.1">
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-
2010,
2012-
2014 Nikhar Agrawal,
142 Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
143 Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R
åde, Gautam Sewani,
144 Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang
<p>
145 Distributed under the Boost Software License, Version
1.0. (See accompanying
146 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>)
151 <div class=
"spirit-nav">
152 <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>