math/doc/cstdfloat/cstdfloat.qbk

[/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]]

[section:overview Overview]

The header `<boost/cstdfloat.hpp>` 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 `<cstdint>`.
All `typedef`s are in `namespace boost`.

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 `typedef`s are based on __N3626
proposed for a new C++14 standard header `<cstdfloat>` and
__N1703 proposed for a new C language standard header `<stdfloat.h>`.

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.

The following code uses `<boost/cstdfloat.hpp>` in combination with
`<boost/math/special_functions.hpp>` to compute a simplified
version of the 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
`<boost/cstdfloat.hpp>`, 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.

  #include <cmath>
  #include <boost/cstdfloat.hpp>
  #include <boost/math/special_functions.hpp>

  boost::float64_t jahnke_emden_lambda(boost::float64_t v, boost::float64_t x)
  {
    const boost::float64_t gamma_v_plus_one = boost::math::tgamma(v + 1);
    const boost::float64_t x_half_pow_v     = std::pow(x /2, v);

    return gamma_v_plus_one * boost::math::cyl_bessel_j(x, v) / x_half_pow_v;
  }

See `cstdfloat_test.cpp` for a more detailed test program.

[endsect] [/section:overview Overview]

[section:rationale 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 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 implementation `<boost/cstdfloat.hpp>`
supports an 80-bit floating-point `typedef` if this can be detected
and if the underlying type conforms 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 `<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++ Standard Library that may contain these `typedef`s.
Should some future 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.
Specializations of `numeric_limits<>` will only be available for these
types if the compiler itself supports corresponding specializations
for the underlying type(s).]

[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.]

[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, 128 bits, or any combination thereof,
then `<boost/cstdfloat.hpp>` 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.

The absence of `float128_t` is indicated by the macro `BOOST_NO_FLOAT128_T`.

[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.

The greatest-width typedef is provided for all platforms.

[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, BOOST_FLOATMAX_C`
are always defined after inclusion of
`<boost/cstdfloat.hpp>`.

These allow floating-point [*constants of at least the specified width] to be declared.

For example:

  #include <boost/cstdfloat.hpp>

  // Declare Pythagoras' constant with approximately 7 decimal digits of precision.
  static const boost::float32_t pi = BOOST_FLOAT32_C(3.1415926536);

  // Declare the Euler-gamma constant with approximately 34 decimal digits of precision.
  static const boost::float128_t euler = BOOST_FLOAT128_C(0.57721566490153286060651209008240243104216);

[endsect] [/section:macros Floating-Point Constant Macros]

[/ 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).
]