boost/libs/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]]

[import ../../example/cstdfloat_example.cpp]
[import ../../example/normal_tables.cpp]

[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>` and `stdint.h`.

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

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 `<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 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
[@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/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 implementation for more details.

For this reason, making `#include <boost/cstdfloat.hpp>` 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 `<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.

[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<boost::floatmax_t>::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<boost::floatmax_t>::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<boost::floatmax_t>::digits10

and the maximum number of  possibly significant decimal digits using

    std::numeric_limits<boost::floatmax_t>::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<boost::floatmax_t, boost::float128_t>::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 `<boost/cstdfloat.hpp>`.

[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 `<boost/cstdfloat.hpp>` in combination with
`<boost/math/special_functions.hpp>` 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
`<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,
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 `<limits>, <cmath>`, I/O stream operations in `<iostream>`, and `<complex>`.

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 `<typeinfo>`, 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 `<boost/cstdfloat.hpp>`
[*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 <class T>
   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 `<boost/cstdfloat.hpp>` 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 `<boost/cstdfloat.hpp>` 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 <boost/cstdfloat.hpp>` [*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 <boost/cstdfloat.hpp>`.


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