[/cstdfloat.qbk Specified-width floating-point typedefs] [def __IEEE754 [@http://en.wikipedia.org/wiki/IEEE_floating_point IEEE_floating_point]] [def __N3626 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3626.pdf N3626]] [def __N1703 [@http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1703.pdf N1703]] [import ../../example/cstdfloat_example.cpp] [import ../../example/normal_tables.cpp] [section:overview Overview] The header `` provides [*optional] standardized floating-point `typedef`s having [*specified widths]. These are useful for writing portable code because they should behave identically on all platforms. These `typedef`s are the floating-point analog of specified-width integers in `` and `stdint.h`. The `typedef`s are based on __N3626 proposed for a new C++14 standard header `` and __N1703 proposed for a new C language standard header ``. All `typedef`s are in `namespace boost` (would be in namespace `std` if eventually standardized). The `typedef`s include `float16_t, float32_t, float64_t, float80_t, float128_t`, their corresponding least and fast types, and the corresponding maximum-width type. The `typedef`s are based on underlying built-in types such as `float`, `double`, or `long double`, or based on other compiler-specific non-standardized types such as `__float128`. The underlying types of these `typedef`s must conform with the corresponding specifications of binary16, binary32, binary64, and binary128 in __IEEE754 floating-point format. The 128-bit floating-point type (of great interest in scientific and numeric programming) is not required in the Boost header, and may not be supplied for all platforms/compilers, because compiler support for a 128-bit floating-point type is not mandated by either the C standard or the C++ standard. See [link math_toolkit.examples.je_lambda Jahnke-Emden-Lambda function example] for an example using both a CMath function and a Boost.Math function to evaluate a moderately interesting function, the [@http://mathworld.wolfram.com/LambdaFunction.html Jahnke-Emden-Lambda function] and [link math_toolkit.examples.normal_table normal distribution] an example of a statistical distribution from Boost.Math [endsect] [/section:overview Overview] [section:rationale Rationale] The implementation of `` is designed to utilize ``, defined in the 1989 C standard. The preprocessor is used to query certain preprocessor definitions in `` 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 regarding conformance with __IEEE754 (IEC599) based on [@ http://en.cppreference.com/w/cpp/types/numeric_limits/is_iec559 `std::numeric_limits<>::is_iec559`] is performed with `BOOST_STATIC_ASSERT`. In addition, this Boost implementation `` supports an 80-bit floating-point `typedef` if it can be detected, and a 128-bit floating-point `typedef` if it can be detected, provided that the underlying types conform with [@http://en.wikipedia.org/wiki/Extended_precision IEEE-754 precision extension] (if`std::numeric_limits<>::is_iec559` is true for this type). The header `` makes the standardized floating-point `typedef`s safely available in `namespace boost` without placing any names in `namespace std`. The intention is to complement rather than compete with a potential future C/C++ Standard Library that may contain these `typedef`s. Should some future C/C++ standard include `` and ``, then `` will continue to function, but will become redundant and may be safely deprecated. Because `` is a Boost header, its name conforms to the boost header naming conventions, not the C++ Standard Library header naming conventions. [note `` [*cannot synthesize or create a `typedef` if the underlying type is not provided by the compiler]. 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 `float128_t` and its corresponding least and fast types are not provided by `.] [warning If `` uses a compiler-specific non-standardized type ([*not] derived from `float, double,` or `long double`) for one or more of its floating-point `typedef`s, then there is no guarantee that specializations of `numeric_limits<>` will be available for these types. Typically, specializations of `numeric_limits<>` will only be available for these types if the compiler itself supports corresponding specializations for the underlying type(s), exceptions are GCC's `__float128` type and Intel's `_Quad` type which are explicitly supported via our own code.] [warning As an implementation artifact, certain C macro names from `` may possibly be visible to users of ``. Don't rely on using these macros; they are not part of any Boost-specified interface. Use `std::numeric_limits<>` for floating-point ranges, etc. instead.] [tip For best results, `` should be `#include`d before other headers that define generic code making use of standard library functions defined in . This is because `` may define overloads of standard library functions where a non-standard type (i.e. other than `float`, `double`, or `long double`) 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 implementation for more details. For this reason, making `#include ` the [*first include] is usually best. ] [endsect] [/section:rationale Rationale] [section:exact_typdefs Exact-Width Floating-Point `typedef`s] The `typedef float#_t`, with # replaced by the width, designates a floating-point type of exactly # bits. For example `float32_t` denotes a single-precision floating-point type with approximately 7 decimal digits of precision (equivalent to binary32 in __IEEE754). Floating-point types in C and C++ are specified to be allowed to have (optionally) implementation-specific widths and formats. However, if a platform supports underlying floating-point types (conformant with __IEEE754) with widths of 16, 32, 64, 80, 128 bits, or any combination thereof, then `` does provide the corresponding `typedef`s `float16_t, float32_t, float64_t, float80_t, float128_t,` their corresponding least and fast types, and the corresponding maximum-width type. [h4 How to tell which widths are supported] The definition (or not) of a [link math_toolkit.macros floating-point constant macro] is the way to test if a specific width is available on a platform. #if defined(BOOST_FLOAT16_C) // Can use boost::float16_t. #endif #if defined(BOOST_FLOAT32_C) // Can use boost::float32_t. #endif #if defined(BOOST_FLOAT64_C) // Can use boost::float64_t. #endif #if defined(BOOST_FLOAT80_C) // Can use boost::float80_t. #endif #if defined(BOOST_FLOAT128_C) // Can use boost::float128_t. #endif This can be used to write code which will compile and run (albeit differently) on several platforms. Without these tests, if a width, say `float128_t` is not supported, then compilation would fail. (It is of course, rare for `float64_t` or `float32_t` not to be supported). The number of bits in just the significand can be determined using: std::numeric_limits::digits and from this one can safely infer the total number of bits because the type must be IEEE754 format, so, for example, if `std::numeric_limits::digits == 113`, then `floatmax_t` must be` float128_t`. The [*total] number of bits using `floatmax_t` can be found thus: [floatmax_1] and the number of 'guaranteed' decimal digits using std::numeric_limits::digits10 and the maximum number of possibly significant decimal digits using std::numeric_limits::max_digits10 [tip `max_digits10` is not always supported, but can be calculated at compile-time using the Kahan formula.] [note One could test std::is_same::value == true but this would fail to compile on a platform where `boost::float128_t` is not defined. So use the MACROs BOOST_FLOATnnn_C. ] [endsect] [/section:exact_typdefs Exact-Width Floating-Point `typedef`s] [section:minimum_typdefs Minimum-width floating-point `typedef`s] The `typedef float_least#_t`, with # replaced by the width, designates a floating-point type with a [*width of at least # bits], such that no floating-point type with lesser size has at least the specified width. Thus, `float_least32_t` denotes the smallest floating-point type with a width of at least 32 bits. Minimum-width floating-point types are provided for all existing exact-width floating-point types on a given platform. For example, if a platform supports `float32_t` and `float64_t`, then `float_least32_t` and `float_least64_t` will also be supported, etc. [endsect] [/section:minimum_typdefs Minimum-width floating-point `typedef`s] [section:fastest_typdefs Fastest floating-point `typedef`s] The `typedef float_fast#_t`, with # replaced by the width, designates the [*fastest] floating-point type with a [*width of at least # bits]. There is no absolute guarantee that these types are the fastest for all purposes. In any case, however, they satisfy the precision and width requirements. Fastest minimum-width floating-point types are provided for all existing exact-width floating-point types on a given platform. For example, if a platform supports `float32_t` and `float64_t`, then `float_fast32_t` and `float_fast64_t` will also be supported, etc. [endsect] [/section:fastest_typdefs Fastest floating-point `typedef`s] [section:greatest_typdefs Greatest-width floating-point typedef] The `typedef floatmax_t` designates a floating-point type capable of representing any value of any floating-point type in a given platform most precisely. The greatest-width `typedef` is provided for all platforms, but, of course, the size may vary. To provide floating-point [*constants] most precisely for a `floatmax_t` type, use the macro BOOST_FLOATMAX_C. For example, replace a constant `123.4567890123456789012345678901234567890` with BOOST_FLOATMAX_C(123.4567890123456789012345678901234567890) If, for example, `floatmax_t` is `float64_t` then the result will be equivalent to a `long double` suffixed with L, but if `floatmax_t` is `float128_t` then the result will be equivalent to a `quad type` suffixed with Q (assuming, of course, that `float128` is supported). If we display with `max_digits10`, the maximum possibly significant decimal digits: [floatmax_widths_1] then on a 128-bit platform (GCC 4.8.1. with quadmath): [floatmax_widths_2] [endsect] [/section:greatest_typdefs Greatest-width floating-point typedef] [section:macros Floating-Point Constant Macros] All macros of the type `BOOST_FLOAT16_C, BOOST_FLOAT32_C, BOOST_FLOAT64_C, BOOST_FLOAT80_C, BOOST_FLOAT128_C, ` and `BOOST_FLOATMAX_C` are always defined after inclusion of ``. [cstdfloat_constant_2] [tip Boost.Math provides many constants 'built-in', so always use Boost.Math constants if available, for example:] [cstdfloat_constant_1] from [@../../example/cstdfloat_example.cpp cstdfloat_example.cpp]. [endsect] [/section:macros Floating-Point Constant Macros] [section:examples Examples] [h3:je_lambda Jahnke-Emden-Lambda function] The following code uses `` in combination with `` to compute a simplified version of the [@http://mathworld.wolfram.com/LambdaFunction.html Jahnke-Emden-Lambda function]. Here, we specify a floating-point type with [*exactly 64 bits] (i.e., `float64_t`). If we were to use, for instance, built-in `double`, then there would be no guarantee that the code would behave identically on all platforms. With `float64_t` from ``, however, it is very likely to be identical. Using `float64_t`, we know that this code is as portable as possible and uses a floating-point type with approximately 15 decimal digits of precision, regardless of the compiler or version or operating system. [cstdfloat_example_1] [cstdfloat_example_2] [cstdfloat_example_3] For details, see [@../../example/cstdfloat_example.cpp cstdfloat_example.cpp] - a extensive example program. [h3:normal_table Normal distribution table] This example shows printing tables of a normal distribution's PDF and CDF, using `boost::math` implmentation of normal. A function templated on floating-point type prints a table for a range of z values. The example shows use of the specified-width typedefs to either use a specific width, or to use the maximum available on the platform, perhaps a high as 128-bit. The number of digits displayed is controlled by the precision of the type, so there are no spurious insignificant decimal digits: float_32_t 0 0.39894228 float_128_t 0 0.398942280401432702863218082711682655 Some sample output for two different platforms is appended to the code at [@../../example/normal_tables.cpp normal_tables.cpp]. [normal_table_1] [endsect] [/section:examples examples] [section:float128 Implementation of Float128 type] Since few compilers implement a true 128-bit floating-point, and language features like the suffix Q, and C++ Standard library functions are as-yet missing or incomplete in C++11, this Boost.Math implementation wraps `__float128` provided by the GCC compiler or the `_Quad` type provided by the Intel compiler. This is provided to in order to demonstrate, and users to evaluate, the feasibility and benefits of higher-precision floating-point, especially to allow use of the full Boost.Math library of functions and distributions at high precision. (It is also possible to use Boost.Math with Boost.Multiprecision decimal and binary, but since these are entirely software solutions, allowing much higher precision or arbitrary precision, they are likely to be slower). We also provide (we believe full) support for `, `, I/O stream operations in ``, and ``. As a prototype for a future C++ standard, we place all these in `namespace std`. This contravenes the existing C++ standard of course, so selecting any compiler that promises to check conformance will fail. [tip For GCC, compile with `-std=gnu++11` or `-std=gnu++03` and do not use `-std=stdc++11`or any 'strict' options as these turn off full support for `__float128`. These requirements also apply to the Intel compiler on Linux, for Intel on Windows you need to compile with `-Qoption,cpp,--extended_float_type -DBOOST_MATH_USE_FLOAT128` in order to activate 128-bit floating point support.] The `__float128` type is provided by the [@http://gcc.gnu.org/onlinedocs/libquadmath/ libquadmath library] on GCC or by Intel's FORTRAN library with Intel C++. A typical invocation of the compiler is g++ -O3 -std=gnu++11 test.cpp -I/c/modular-boost -lquadmath -o test.exe [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.] g++ -O3 -std=gnu++11 test.cpp -I/c/modular-boost/libs/math/include -I/c/modular-boost -lquadmath -o test.exe [note So far, the only missing detail that we have noted is in trying to use ``, for example for `std::cout << typeid<__float_128>.name();`. Link fails: undefined reference to `typeinfo for __float128`. See [@http://gcc.gnu.org/bugzilla/show_bug.cgi?id=43622 GCC Bug 43622 - no C++ typeinfo for __float128].] [section Overloading template functions with float128_t] An artifact of providing C++ standard library support for quadmath may mandate the inclusion of `` [*before] the inclusion of other headers. Consider a function that calls `fabs(x)` and has previously injected `std::fabs()` into local scope via a `using` directive: template bool unsigned_compare(T a, T b) { using std::fabs; return fabs(a) == fabs(b); } In this function, the correct overload of `fabs` may be found via [@http://en.wikipedia.org/wiki/Argument-dependent_name_lookup argument-dependent-lookup (ADL)] or by calling one of the `std::fabs` overloads. There is a key difference between them however: an overload in the same namespace as T and found via ADL need ['[*not be defined at the time the function is declared]]. However, all the types declared in `` are fundamental types, so for these types we are relying on finding an overload declared in namespace `std`. In that case however, ['[*all such overloads must be declared prior to the definition of function `unsigned_compare` otherwise they are not considered]]. In the event that `` has been included [*after] the definition of the above function, the correct overload of `fabs`, while present, is simply not considered as part of the overload set. So the compiler tries to downcast the `float128_t` argument first to `long double`, then to `double`, then to `float`; the compilation fails because the result is ambiguous. However the compiler error message will appear cruelly inscrutable, at an apparently irelevant line number and making no mention of `float128`: the word ['ambiguous] is the clue to what is wrong. Provided you `#include ` [*before] the inclusion of the any header containing generic floating point code (such as other Boost.Math headers, then the compiler will know about and use the `std::fabs(std::float128_t)` that we provide in `#include `. [endsect] [section:exp_function Exponential function] There is a bug whe using any quadmath `expq` function on GCC: [@http://gcc.gnu.org/bugzilla/show_bug.cgi?id=60349 GCC bug #60349] [@http://sourceforge.net/p/mingw-w64/bugs/368/ mingw-64 bug #368] To work round this defect, an alternative implementation of 128-bit exp is temporarily provided by `boost/cstdfloat.hpp`. [endsect] [/section:exp_function exp function] [section:typeinfo `typeinfo`] It is not yet possible to use `typeinfo` for float_128 on GCC: see [@http://gcc.gnu.org/bugzilla/show_bug.cgi?id=43622 GCC 43622] so this fails to link `undefined reference to typeinfo for __float128` std::cout << typeid(boost::float128_t).name() << std::endl; This prevent using the existing tests for Boost.Math distributions, (unless a few lines are commented out) and if a MACRO BOOST_MATH_INSTRUMENT controlling them is defined then some diagnostic displays in Boost.Math will not work. However this is only used for display purposes and can be commented out until this is fixed. [endsect] [/section:typeinfo `typeinfo`] [endsect] [/section:float128 Float128 type] [/ cstdfloat.qbk Copyright 2014 Christopher Kormanyos, John Maddock and Paul A. Bristow. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt). ]