libs/test/doc/test_output/logging_floating_point.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:log_floating_points Logging floating point type numbers]
   9
  10 It may appear that floating-point numbers are displayed by the __UTF__ with an excessive number of decimal digits.
  11 However the number of digits shown is chosen to avoid apparently nonsensical displays like `[1.00000 != 1.00000]`
  12 when comparing exactly unity against a value which is increased by just one least significant binary digit using
  13 the default precision for float of just 6 decimal digits, given by
  14  `std::numeric_limits<float>::digits10`. The function used for the number of decimal
  15 digits displayed is that proposed for a future C++ Standard,
  16 [@http://www2.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1822.pdf A Proposal to add a max
  17 significant decimal digits value], to be called `std::numeric_limits::max_digits10();`.
  18 For 32-bit floats, 9 decimal digits are needed to ensure a single bit change produces a different decimal digit
  19 string.
  20
  21 So a much more helpful display using 9 decimal digits is thus:
  22 `[1.00000000 != 1.00000012]` showing that the two values are in fact different.
  23
  24
  25 For __IEEE754__ 32-bit float values - 9 decimal digits are shown. For 64-bit __IEEE754__ double - 17 decimal digits. For
  26 __IEEE754__ extended long double using 80-bit - 21 decimal digits. For __IEEE754__ quadruple long double 128-bit, and SPARC
  27 extended long double 128-bit - 36 decimal digits. For floating-point types, a convenient formula to calculate
  28 `max_digits10` is: `2 + std::numeric_limits<FPT>::digits * 3010/10000`;
  29
  30 [note
  31      Note that a user defined floating point type UDFPT must define
  32      `std::numeric_limits<UDFPT>::is_specialized = true` and provide an appropriate value
  33      for `std::numeric_limits<UDFPT>::digits`, the number of bits used for the significand
  34      or mantissa. For example, for the SPARC extended long double 128, 113 bits are used for the significand (one of
  35      which is implicit).
  36 ]
  37 [endsect] [/section:log_floating_points]