1 [/cstdfloat.qbk Specified-width floating-point typedefs]
3 [def __IEEE754 [@http://en.wikipedia.org/wiki/IEEE_floating_point IEEE_floating_point]]
4 [def __N3626 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3626.pdf N3626]]
5 [def __N1703 [@http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1703.pdf N1703]]
7 [import ../../example/cstdfloat_example.cpp]
8 [import ../../example/normal_tables.cpp]
9 [/Removed as unhelpful for C++ users, but might have use as a check that quadmath is available and linked OK.]
10 [/import ../../example/quadmath_snprintf.c]
12 [section:specified_typedefs Overview]
14 The header `<boost/cstdfloat.hpp>` provides [*optional]
15 standardized floating-point `typedef`s having [*specified widths].
16 These are useful for writing portable code because they
17 should behave identically on all platforms.
18 These `typedef`s are the floating-point analog of specified-width integers in `<cstdint>` and `stdint.h`.
20 The `typedef`s are based on __N3626
21 proposed for a new C++14 standard header `<cstdfloat>` and
22 __N1703 proposed for a new C language standard header `<stdfloat.h>`.
24 All `typedef`s are in `namespace boost` (would be in namespace `std` if eventually standardized).
26 The `typedef`s include `float16_t, float32_t, float64_t, float80_t, float128_t`,
27 their corresponding least and fast types,
28 and the corresponding maximum-width type.
29 The `typedef`s are based on underlying built-in types
30 such as `float`, `double`, or `long double`, or the proposed __short_float,
31 or based on other compiler-specific non-standardized types such as `__float128`.
32 The underlying types of these `typedef`s must conform with
33 the corresponding specifications of binary16, binary32, binary64,
34 and binary128 in __IEEE754 floating-point format, and
35 `std::numeric_limits<>::is_iec559 == true`.
37 The 128-bit floating-point type (of great interest in scientific and
38 numeric programming) is not required in the Boost header,
39 and may not be supplied for all platforms/compilers, because compiler
40 support for a 128-bit floating-point type is not mandated by either
41 the C standard or the C++ standard.
43 If 128-bit floating-point is supported, then including `boost/cstdfloat.hpp`
44 provides a [*native] 128-bit type, and
45 includes other headers in folder `boost/math/cstdfloat` that provide C++
46 quad support for __C_math in `<cmath>`, `<limits>`, `<iostream>`, `<complex>`,
47 and the available floating-point types.
49 One can also, more robustly, include `boost/multiprecision/float128.hpp`
50 and this provides a thin wrapper selecting the appropriate 128-bit native type
51 from `cstdfloat` if available, or else a 128-bit multiprecision type.
53 See [link math_toolkit.examples.je_lambda Jahnke-Emden-Lambda function example]
54 for an example using both a `<cmath>` function and a Boost.Math function
55 to evaluate a moderately interesting function, the
56 [@http://mathworld.wolfram.com/LambdaFunction.html Jahnke-Emden-Lambda function]
57 and [link math_toolkit.examples.normal_table normal distribution]
58 as an example of a statistical distribution from Boost.Math.
60 [endsect] [/section:specified_typedefs Overview]
62 [section:rationale Rationale]
64 The implementation of `<boost/cstdfloat.hpp>` is designed to utilize `<float.h>`,
65 defined in the 1989 C standard. The preprocessor is used to query certain
66 preprocessor definitions in `<float.h>` such as FLT_MAX, DBL_MAX, etc.
67 Based on the results of these queries, an attempt is made to automatically
68 detect the presence of built-in floating-point types having specified widths.
69 An unequivocal test requiring conformance with __IEEE754 (IEC599) based on
70 [@ http://en.cppreference.com/w/cpp/types/numeric_limits/is_iec559 `std::numeric_limits<>::is_iec559`]
71 is performed with `BOOST_STATIC_ASSERT`.
73 In addition, this Boost implementation `<boost/cstdfloat.hpp>`
74 supports an 80-bit floating-point `typedef` if it can be detected,
75 and a 128-bit floating-point `typedef` if it can be detected,
76 provided that the underlying types conform with
77 [@http://en.wikipedia.org/wiki/Extended_precision IEEE-754 precision extension]
78 (provided `std::numeric_limits<>::is_iec559 == true` for this type).
80 The header `<boost/cstdfloat.hpp>` makes the standardized floating-point
81 `typedef`s safely available in `namespace boost` without placing any names
82 in `namespace std`. The intention is to complement rather than compete
83 with a potential future C/C++ Standard Library that may contain these `typedef`s.
84 Should some future C/C++ standard include `<stdfloat.h>` and `<cstdfloat>`,
85 then `<boost/cstdfloat.hpp>` will continue to function, but will become redundant
86 and may be safely deprecated.
88 Because `<boost/cstdfloat.hpp>` is a Boost header, its name conforms to the
89 boost header naming conventions, not the C++ Standard Library header
93 `<boost/cstdfloat.hpp>` [*cannot synthesize or create
94 a `typedef` if the underlying type is not provided by the compiler].
95 For example, if a compiler does not have an underlying floating-point
96 type with 128 bits (highly sought-after in scientific and numeric programming),
97 then `float128_t` and its corresponding least and fast types are [*not]
98 provided by `<boost/cstdfloat.hpp`>.]
100 [warning If `<boost/cstdfloat.hpp>` uses a compiler-specific non-standardized type
101 ([*not] derived from `float, double,` or `long double`) for one or more
102 of its floating-point `typedef`s, then there is no guarantee that
103 specializations of `numeric_limits<>` will be available for these types.
104 Typically, specializations of `numeric_limits<>` will only be available for these
105 types if the compiler itself supports corresponding specializations
106 for the underlying type(s), exceptions are GCC's `__float128` type and
107 Intel's `_Quad` type which are explicitly supported via our own code.]
110 As an implementation artifact, certain C macro names from `<float.h>`
111 may possibly be visible to users of `<boost/cstdfloat.hpp>`.
112 Don't rely on using these macros; they are not part of any Boost-specified interface.
113 Use `std::numeric_limits<>` for floating-point ranges, etc. instead.]
115 [tip For best results, `<boost/cstdfloat.hpp>` should be `#include`d before
116 other headers that define generic code making use of standard library functions
119 This is because `<boost/cstdfloat.hpp>` may define overloads of
120 standard library functions where a non-standard type (i.e. other than
121 `float`, `double`, or `long double`) is used for one of the specified
122 width types. If generic code (for example in another Boost.Math header)
123 calls a standard library function, then the correct overload will only be
124 found if these overloads are defined prior to the point of use.
125 See [link math_toolkit.float128.overloading overloading template functions with float128_t]
126 and the implementation of `cstdfloat.hpp` for more details.
128 For this reason, making `#include <boost/cstdfloat.hpp>` the [*first
129 include] is usually best.
131 [endsect] [/section:rationale Rationale]
133 [section:exact_typdefs Exact-Width Floating-Point `typedef`s]
135 The `typedef float#_t`, with # replaced by the width, designates a
136 floating-point type of exactly # bits. For example `float32_t` denotes
137 a single-precision floating-point type with approximately
138 7 decimal digits of precision (equivalent to binary32 in __IEEE754).
140 Floating-point types in C and C++ are specified to be allowed to have
141 (optionally) implementation-specific widths and formats.
142 However, if a platform supports underlying
143 floating-point types (conformant with __IEEE754) with widths of
144 16, 32, 64, 80, 128 bits, or any combination thereof,
145 then `<boost/cstdfloat.hpp>` does provide the corresponding `typedef`s
146 `float16_t, float32_t, float64_t, float80_t, float128_t,`
147 their corresponding least and fast types,
148 and the corresponding maximum-width type.
150 [h4 How to tell which widths are supported]
152 The definition (or not) of a
153 [link math_toolkit.macros floating-point constant macro]
154 is a way to test if a [*specific width floating-point] is available on a platform.
156 #if defined(BOOST_FLOAT16_C)
157 // Can use boost::float16_t, perhaps a proposed __short_float.
158 // P0192R1, Adding Fundamental Type for Short Float,
159 // Boris Fomitchev, Sergei Nikolaev, Olivier Giroux, Lawrence Crowl, 2016 Feb14
160 // http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2016.pdf
163 #if defined(BOOST_FLOAT32_C)
164 // Can use boost::float32_t, usually type `float`.
167 #if defined(BOOST_FLOAT64_C)
168 // Can use boost::float64_t, usually type `double`, and sometimes also type `long double`.
171 #if defined(BOOST_FLOAT80_C)
172 // Can use boost::float80_t, sometimes type `long double`.
175 #if defined(BOOST_FLOAT128_C)
176 // Can use boost::float128_t. Sometimes type `__float128` or `_Quad`.
179 This can be used to write code which will compile and run (albeit differently) on several platforms.
180 Without these tests, if a width, say `float128_t` is not supported, then compilation would fail.
181 (It is, of course, rare for `float64_t` or `float32_t` not to be supported).
183 The number of bits in just the significand can be determined using:
185 std::numeric_limits<boost::floatmax_t>::digits
187 and from this one can safely infer the total number of bits because the type must be IEEE754 format,
188 `std::numeric_limits<boost::floatmax_t>::is_iec559 == true`,
189 so, for example, if `std::numeric_limits<boost::floatmax_t>::digits == 113`,
190 then `floatmax_t` must be` float128_t`.
192 The [*total] number of bits using `floatmax_t` can be found thus:
196 and the number of 'guaranteed' decimal digits using
198 std::numeric_limits<boost::floatmax_t>::digits10
200 and the maximum number of possibly significant decimal digits using
202 std::numeric_limits<boost::floatmax_t>::max_digits10
204 [tip `max_digits10` is not always supported,
205 but can be calculated at compile-time using the Kahan formula,
206 `2 + binary_digits * 0.3010` which can be calculated [*at compile time] using
207 `2 + binary_digits * 3010/10000`.
210 [note One could test that
212 std::is_same<boost::floatmax_t, boost::float128_t>::value == true
214 but this would fail to compile on a platform where `boost::float128_t` is not defined.
215 So it is better to use the MACROs `BOOST_FLOATnnn_C`. ]
217 [endsect] [/section:exact_typdefs Exact-Width Floating-Point `typedef`s]
219 [section:minimum_typdefs Minimum-width floating-point `typedef`s]
221 The `typedef float_least#_t`, with # replaced by the width, designates a
222 floating-point type with a [*width of at least # bits], such that no
223 floating-point type with lesser size has at least the specified width.
224 Thus, `float_least32_t` denotes the smallest floating-point type with
225 a width of at least 32 bits.
227 Minimum-width floating-point types are provided for all existing
228 exact-width floating-point types on a given platform.
230 For example, if a platform supports `float32_t` and `float64_t`,
231 then `float_least32_t` and `float_least64_t` will also be supported, etc.
233 [endsect] [/section:minimum_typdefs Minimum-width floating-point `typedef`s]
235 [section:fastest_typdefs Fastest floating-point `typedef`s]
237 The `typedef float_fast#_t`, with # replaced by the width, designates
238 the [*fastest] floating-point type with a [*width of at least # bits].
240 There is no absolute guarantee that these types are the fastest for all purposes.
241 In any case, however, they satisfy the precision and width requirements.
243 Fastest minimum-width floating-point types are provided for all existing
244 exact-width floating-point types on a given platform.
246 For example, if a platform supports `float32_t` and `float64_t`,
247 then `float_fast32_t` and `float_fast64_t` will also be supported, etc.
249 [endsect] [/section:fastest_typdefs Fastest floating-point `typedef`s]
251 [section:greatest_typdefs Greatest-width floating-point typedef]
253 The `typedef floatmax_t` designates a floating-point type capable of representing
254 any value of any floating-point type in a given platform most precisely.
256 The greatest-width `typedef` is provided for all platforms, but, of course, the size may vary.
258 To provide floating-point [*constants] most precisely representable for a `floatmax_t` type,
259 use the macro `BOOST_FLOATMAX_C`.
261 For example, replace a constant `123.4567890123456789012345678901234567890` with
263 BOOST_FLOATMAX_C(123.4567890123456789012345678901234567890)
265 If, for example, `floatmax_t` is `float64_t` then the result will be equivalent to a `long double` suffixed with L,
266 but if `floatmax_t` is `float128_t` then the result will be equivalent to a `quad type` suffixed with Q
267 (assuming, of course, that `float128_t` (`__float128` or `Quad`) is supported).
269 If we display with `max_digits10`, the maximum possibly significant decimal digits:
273 then on a 128-bit platform (GCC 4.8.1 or higher with quadmath):
277 [endsect] [/section:greatest_typdefs Greatest-width floating-point typedef]
279 [section:macros Floating-Point Constant Macros]
281 All macros of the type `BOOST_FLOAT16_C, BOOST_FLOAT32_C, BOOST_FLOAT64_C,
282 BOOST_FLOAT80_C, BOOST_FLOAT128_C, ` and `BOOST_FLOATMAX_C`
283 are always defined after inclusion of `<boost/cstdfloat.hpp>`.
285 [cstdfloat_constant_2]
287 [tip Boost.Math provides many constants 'built-in', so always use Boost.Math constants if available, for example:]
289 [cstdfloat_constant_1]
291 from [@../../example/cstdfloat_example.cpp cstdfloat_example.cpp].
293 See the complete list of __constants.
295 [endsect] [/section:macros Floating-Point Constant Macros]
297 [section:examples Examples]
299 [h3:je_lambda Jahnke-Emden-Lambda function]
301 The following code uses `<boost/cstdfloat.hpp>` in combination with
302 `<boost/math/special_functions.hpp>` to compute a simplified
304 [@http://mathworld.wolfram.com/LambdaFunction.html Jahnke-Emden-Lambda function].
305 Here, we specify a floating-point type with [*exactly 64 bits] (i.e., `float64_t`).
306 If we were to use, for instance, built-in `double`,
307 then there would be no guarantee that the code would
308 behave identically on all platforms. With `float64_t` from
309 `<boost/cstdfloat.hpp>`, however, it is very likely to be identical.
311 Using `float64_t`, we know that
312 this code is as portable as possible and uses a floating-point type
313 with approximately 15 decimal digits of precision,
314 regardless of the compiler or version or operating system.
316 [cstdfloat_example_1]
317 [cstdfloat_example_2]
318 [cstdfloat_example_3]
320 For details, see [@../../example/cstdfloat_example.cpp cstdfloat_example.cpp]
321 - a extensive example program.
323 [h3:normal_table Normal distribution table]
325 This example shows printing tables of a normal distribution's PDF and CDF,
326 using `boost::math` implementation of normal distribution.
328 A function templated on floating-point type prints a table for a range of standard variate z values.
330 The example shows use of the specified-width typedefs to either use a specific width,
331 or to use the maximum available on the platform, perhaps a high as 128-bit.
333 The number of digits displayed is controlled by the precision of the type,
334 so there are no spurious insignificant decimal digits:
336 float_32_t 0 0.39894228
337 float_128_t 0 0.398942280401432702863218082711682655
339 Some sample output for two different platforms is appended to the code at
340 [@../../example/normal_tables.cpp normal_tables.cpp].
344 [endsect] [/section:examples examples]
346 [section:float128_hints Hints on using float128 (and __float128)]
348 [h5:different_float128 __float128 versus float128]
349 * __float128 is the (optionally) compiler supplied hardware type,
350 it's an C-ish extension to C++ and there is only
351 minimal support for it in normal C++
352 (no IO streams or `numeric_limits` support,
353 function names in libquadmath all have different names to the
355 So you can program type `__float128` directly, but it's harder work.
357 * Type `float128` uses __float128 and makes it C++ and generic code friendly,
358 with all the usual standard `iostream`, `numeric_limits`, `complex` in namspace `std::` available,
359 so strongly recommended for C++ use.
363 * Make sure you declare variables with the correct type, here `float128`.
364 * Make sure that if you pass a variable to a function then it is casted to `float128`.
365 * Make sure you declare literals with the correct suffix - otherwise
366 they'll be treated as type `double` with catastrophic loss of precision.
367 So make sure they have a Q suffix for 128-bit floating-point literals.
368 * All the std library functions, cmath functions, plus all the constants, and special
369 functions from Boost.Math should then just work.
370 * Make sure std lib functions are called [*unqualified] so that the correct
371 overload is found via __ADL. So write
375 * In general, try not to reinvent stuff - using constants from
376 Boost.Math is probably less error prone than declaring your own,
377 likewise the special functions etc.
379 Some examples of what can go horribly and silently wrong are at
380 [@../../example/float128_example.cpp float128_example.cpp].
382 [endsect] [/section:float128_hints Hints on using float128]
384 [section:float128 Implementation of Float128 type]
386 Since few compilers implement a true 128-bit floating-point, and language features like the suffix Q
387 (which may need an option `-fext-numeric-literals` to enable),
388 and C++ Standard library functions are as-yet missing or incomplete in C++11,
389 this Boost.Math implementation wraps `__float128` provided by the GCC compiler
390 [@https://gcc.gnu.org/onlinedocs/gcc/Floating-Types.html GCC floating-point types]
391 or the `_Quad` type provided by the Intel compiler.
393 This is provided to in order to demonstrate, and users to evaluate, the feasibility and benefits of higher-precision floating-point,
394 especially to allow use of the full <cmath> and Boost.Math library of functions and distributions at high precision.
396 (It is also possible to use Boost.Math with Boost.Multiprecision decimal and binary, but since these are entirely software solutions,
397 allowing much higher precision or arbitrary precision, they are likely to be slower).
399 We also provide (we believe full) support for `<limits>, <cmath>`, I/O stream operations in `<iostream>`, and `<complex>`.
401 As a prototype for a future C++ standard, we place all these in `namespace std`.
402 This contravenes the existing C++ standard of course, so selecting any compiler that promises to check conformance will fail.
404 [tip For GCC, compile with `-std=gnu++11` or `-std=gnu++03` and do not use `-std=stdc++11` or any 'strict' options, as
405 these turn off full support for `__float128`. These requirements also apply to the Intel compiler on Linux, for
406 Intel on Windows you need to compile with `-Qoption,cpp,--extended_float_type -DBOOST_MATH_USE_FLOAT128` in order to
407 activate 128-bit floating point support.]
409 The `__float128` type is provided by the [@http://gcc.gnu.org/onlinedocs/libquadmath/ libquadmath library] on GCC or
410 by Intel's FORTRAN library with Intel C++. THey also provide a full set of `<cmath>` functions in `namespace std`.
412 [h4 Using C __float128 quadmath type]
414 [quadmath_snprintf_1]
416 The source code is at [@../../example/quadmath_snprintf.c quadmath_snprintf.c].
418 [h4 Using C++ `float128` quadmath type]
420 For C++ programs, you will want to use the C++ type `float128`
422 See example at [@../../example/cstdfloat_example.cpp cstdfloat_example.cpp].
424 A typical invocation of the compiler is
426 g++ -O3 -std=gnu++11 test.cpp -I/c/modular-boost -lquadmath -o test.exe
428 [tip If you are trying to use the develop branch of Boost.Math, then make `-I/c/modular-boost/libs/math/include` the [*first] include directory.]
430 g++ -O3 -std=gnu++11 test.cpp -I/c/modular-boost/libs/math/include -I/c/modular-boost -lquadmath -o test.exe
432 [note So far, the only missing detail that we had noted was in trying to use `<typeinfo>`,
433 for example for `std::cout << typeid<__float_128>.name();`.
435 Link fails: undefined reference to typeinfo for __float128.
437 See [@http://gcc.gnu.org/bugzilla/show_bug.cgi?id=43622 GCC Bug 43622 - no C++ typeinfo for __float128].
438 But this is reported (Marc Glisse 2015-04-04 ) fixed in GCC 5 (and above).
440 For example, with GCC6.1.1 this works as expected to a [*mangled] string name, and output (if possible - not always).
442 const std::type_info& tifu128 = typeid(__float128); // OK.
443 //std::cout << tifu128.name() << std::endl; // On GCC, aborts (because not printable string).
444 //std::cout << typeid(__float128).name() << std::endl; // Aborts - string name cannot be output.
446 const std::type_info& tif128 = typeid(float128); // OK.
447 std::cout << tif128.name() << std::endl; // OK.
448 std::cout << typeid(float128).name() << std::endl; // OK.
450 const std::type_info& tpi = typeid(pi1); // OK GCC 6.1.1 (from GCC 5 according to http://gcc.gnu.org/bugzilla/show_bug.cgi?id=43622)
451 std::cout << tpi.name() << std::endl; // Output mangled name:
453 // N5boost14multiprecision6numberINS0_8backends16float128_backendELNS0_26expression_template_optionE0EEE
458 [section:overloading Overloading template functions with float128_t]
460 An artifact of providing C++ standard library support for
461 quadmath may mandate the inclusion of `<boost/cstdfloat.hpp>`
462 [*before] the inclusion of other headers.
464 Consider a function that calls `fabs(x)` and has previously injected `std::fabs()`
465 into local scope via a `using` directive:
468 bool unsigned_compare(T a, T b)
471 return fabs(a) == fabs(b);
474 In this function, the correct overload of `fabs` may be found via
475 [@http://en.wikipedia.org/wiki/Argument-dependent_name_lookup argument-dependent-lookup (ADL)]
476 or by calling one of the `std::fabs` overloads. There is a key difference between them
477 however: an overload in the same namespace as T and found via ADL need ['[*not be defined at the
478 time the function is declared]]. However, all the types declared in `<boost/cstdfloat.hpp>` are
479 fundamental types, so for these types we are relying on finding an overload declared in namespace `std`.
480 In that case however, ['[*all such overloads must be declared prior to the definition of function
481 `unsigned_compare` otherwise they are not considered]].
483 In the event that `<boost/cstdfloat.hpp>` has been included [*after] the
484 definition of the above function, the correct overload of `fabs`, while present, is simply
485 not considered as part of the overload set.
486 So the compiler tries to downcast the `float128_t` argument first to
487 `long double`, then to `double`, then to `float`;
488 the compilation fails because the result is ambiguous.
489 However the compiler error message will appear cruelly inscrutable,
490 at an apparently irelevant line number and making no mention of `float128`:
491 the word ['ambiguous] is the clue to what is wrong.
493 Provided you `#include <boost/cstdfloat.hpp>` [*before] the inclusion
494 of the any header containing generic floating point code (such as other
495 Boost.Math headers, then the compiler
496 will know about and use the `std::fabs(std::float128_t)`
497 that we provide in `#include <boost/cstdfloat.hpp>`.
501 [section:exp_function Exponential function]
503 There was a bug when using any quadmath `expq` function on GCC :
504 [@http://gcc.gnu.org/bugzilla/show_bug.cgi?id=60349 GCC bug #60349]
506 [@http://sourceforge.net/p/mingw-w64/bugs/368/ mingw-64 bug #368].
508 To work round this defect, an alternative implementation of 128-bit exp
509 was temporarily provided by `boost/cstdfloat.hpp`.
511 The mingw bug was fixed at 2014-03-12 and GCC 6.1.1 now works as expected.
513 [tip It is essential to link to the quadmath library].
515 [endsect] [/section:exp_function exp function]
517 [section:typeinfo `typeinfo`]
519 For GCC 4.8.1 it was not yet possible to use `typeinfo` for `float_128` on GCC:
520 see [@http://gcc.gnu.org/bugzilla/show_bug.cgi?id=43622 GCC 43622].
522 So this code (to display the mangled name)
523 failed to link `undefined reference to typeinfo for __float128`
525 std::cout << typeid(boost::float128_t).name() << std::endl;
527 This prevent using the existing tests for Boost.Math distributions,
528 (unless a few lines are commented out)
529 and if a MACRO BOOST_MATH_INSTRUMENT controlling them is defined
530 then some diagnostic displays in Boost.Math will not work.
532 However this was only used for display purposes
533 and could be commented out until this was fixed in GCC 5.
535 [tip Not all managed names can be [*displayed] using `std::cout`.]
537 [endsect] [/section:typeinfo `typeinfo`]
540 [endsect] [/section:float128 Float128 type]
543 Copyright 2014 Christopher Kormanyos, John Maddock and Paul A. Bristow.
544 Distributed under the Boost Software License, Version 1.0.
545 (See accompanying file LICENSE_1_0.txt or copy at
546 http://www.boost.org/LICENSE_1_0.txt).