Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

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 typedefs 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 typedefs. 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] 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] 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 typedefs, 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] 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] Tip

For best results, <boost/cstdfloat.hpp> should be #included 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.


PrevUpHomeNext