| Home | Libraries | People | FAQ | More

## Rationale

The implementation of `<boost/cstdfloat.hpp>` is designed to utilize `<float.h>`, defined in the 1989 C standard. The preprocessor is used to query certain preprocessor definitions in `<float.h>` 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 requiring conformance with IEEE_floating_point (IEC599) based on `std::numeric_limits<>::is_iec559` is performed with `static_assert`.

In addition, this Boost implementation `<boost/cstdfloat.hpp>` 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 IEEE-754 precision extension (provided `std::numeric_limits<>::is_iec559 == true` for this type).

The header `<boost/cstdfloat.hpp>` 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 `<stdfloat.h>` and `<cstdfloat>`, then `<boost/cstdfloat.hpp>` will continue to function, but will become redundant and may be safely deprecated.

Because `<boost/cstdfloat.hpp>` is a Boost header, its name conforms to the boost header naming conventions, not the C++ Standard Library header naming conventions.

| Note
`<boost/cstdfloat.hpp>` 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 `<boost/cstdfloat.hpp`>.

| Warning
If `<boost/cstdfloat.hpp>` 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 `<float.h>` may possibly be visible to users of `<boost/cstdfloat.hpp>`. 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, `<boost/cstdfloat.hpp>` should be `#include`d before other headers that define generic code making use of standard library functions defined in <cmath>. This is because `<boost/cstdfloat.hpp>` 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 overloading template functions with float128_t and the implementation of `cstdfloat.hpp` for more details. For this reason, making `#include <boost/cstdfloat.hpp>` the first include is usually best.