libs/math/doc/fp_utilities/float_next.qbk

   1 [section:next_float Floating-Point Representation Distance (ULP),
   2    and Finding Adjacent Floating-Point Values]
   3
   4 [@http://en.wikipedia.org/wiki/Unit_in_the_last_place Unit of Least Precision or Unit in the Last Place]
   5 is the gap between two different, but as close as possible, floating-point numbers.
   6
   7 Most decimal values, for example 0.1, cannot be exactly represented as floating-point values,
   8 but will be stored as the
   9 [@http://en.wikipedia.org/wiki/Floating_point#Representable_numbers.2C_conversion_and_rounding
  10 closest representable floating-point].
  11
  12 Functions are provided for finding adjacent greater and lesser floating-point values,
  13 and estimating the number of gaps between any two floating-point values.
  14
  15 The floating-point type FPT must have has a fixed number of bits in the representation.
  16 The number of bits may set at runtime, but must be the same for all numbers.
  17 For example, __NTL_quad_float type (fixed 128-bit representation)
  18 or __NTL_RR type (arbitrary but fixed decimal digits, default 150)
  19 but *not* a type that extends the representation to provide an exact representation
  20 for any number, for example [@http://keithbriggs.info/xrc.html XRC eXact Real in C].
  21
  22 [section:nextafter Finding the Next Representable Value in a Specific Direction (nextafter)]
  23
  24 [h4 Synopsis]
  25
  26 ``
  27 #include <boost/math/special_functions/next.hpp>
  28 ``
  29
  30   namespace boost{ namespace math{
  31
  32   template <class FPT>
  33   FPT nextafter(FPT val, FPT direction);
  34
  35   }} // namespaces
  36
  37 [h4 Description - nextafter]
  38
  39 This is an implementation of the `nextafter` function included in the C99 standard.
  40 (It is also effectively an implementation of the C99 'nexttoward' legacy function
  41 which differs only having a long double direction,
  42 and can generally serve in its place if required).
  43
  44 [note The C99 functions must use suffixes f and l to distinguish float and long double versions.
  45 C++ uses the template mechanism instead.]
  46
  47 Returns the next representable value after /x/ in the direction of /y/.  If
  48 `x == y` then returns /x/.  If /x/ is non-finite then returns the result of
  49 a __domain_error.  If there is no such value in the direction of /y/ then
  50 returns an __overflow_error.
  51
  52 [warning The template parameter FTP must be a floating-point type.
  53 An integer type, for example, will produce an unhelpful error message.]
  54
  55 [tip Nearly always, you just want the next or prior representable value,
  56 so instead use `float_next` or `float_prior` below.]
  57
  58 [h4 Examples - nextafter]
  59
  60 The two representations using a 32-bit float either side of unity are:
  61 ``
  62 The nearest (exact) representation of 1.F is      1.00000000
  63 nextafter(1.F, 999) is                            1.00000012
  64 nextafter(1/f, -999) is                           0.99999994
  65
  66 The nearest (not exact) representation of 0.1F is 0.100000001
  67 nextafter(0.1F, 10) is                            0.100000009
  68 nextafter(0.1F, 10) is                            0.099999994
  69 ``
  70
  71 [endsect]
  72
  73 [section:float_next Finding the Next Greater Representable Value (float_next)]
  74
  75 [h4 Synopsis]
  76
  77 ``
  78 #include <boost/math/special_functions/next.hpp>
  79 ``
  80
  81    namespace boost{ namespace math{
  82
  83    template <class FPT>
  84    FPT float_next(FPT val);
  85
  86    }} // namespaces
  87
  88 [h4 Description - float_next]
  89
  90 Returns the next representable value which is greater than /x/.
  91 If /x/ is non-finite then returns the result of
  92 a __domain_error.  If there is no such value greater than /x/ then
  93 returns an __overflow_error.
  94
  95 Has the same effect as
  96
  97   nextafter(val, (std::numeric_limits<FPT>::max)());
  98
  99 [endsect] [/section:float_next Finding the Next Greater Representable Value (float_prior)]
 100
 101 [section:float_prior Finding the Next Smaller Representable Value (float_prior)]
 102
 103 [h4 Synopsis]
 104
 105 ``
 106 #include <boost/math/special_functions/next.hpp>
 107 ``
 108
 109    namespace boost{ namespace math{
 110
 111    template <class FPT>
 112    FPT float_prior(FPT val);
 113
 114    }} // namespaces
 115
 116
 117 [h4 Description - float_prior]
 118
 119 Returns the next representable value which is less than /x/.
 120 If /x/ is non-finite then returns the result of
 121 a __domain_error.  If there is no such value less than /x/ then
 122 returns an __overflow_error.
 123
 124 Has the same effect as
 125
 126   nextafter(val, -(std::numeric_limits<FPT>::max)());  // Note most negative value -max.
 127
 128 [endsect] [/section:float_prior Finding the Next Smaller Representable Value (float_prior)]
 129
 130 [section:float_distance Calculating the Representation Distance
 131    Between Two Floating Point Values (ULP) float_distance]
 132
 133 Function float_distance finds the number of gaps/bits/ULP between any two floating-point values.
 134 If the significands of floating-point numbers are viewed as integers,
 135 then their difference is the number of ULP/gaps/bits different.
 136
 137 [h4 Synopsis]
 138
 139 ``
 140 #include <boost/math/special_functions/next.hpp>
 141 ``
 142
 143    namespace boost{ namespace math{
 144
 145    template <class FPT>
 146    FPT float_distance(FPT a, FPT b);
 147
 148    }} // namespaces
 149
 150 [h4 Description - float_distance]
 151
 152 Returns the distance between /a/ and /b/: the result is always
 153 a signed integer value (stored in floating-point type FPT)
 154 representing the number of distinct representations between /a/ and /b/.
 155
 156 Note that
 157
 158 * `float_distance(a, a)` always returns 0.
 159 * `float_distance(float_next(a), a)` always returns -1.
 160 * `float_distance(float_prior(a), a)` always returns 1.
 161
 162 The function `float_distance` is equivalent to calculating the number
 163 of ULP (Units in the Last Place) between /a/ and /b/ except that it
 164 returns a signed value indicating whether `a > b` or not.
 165
 166 If the distance is too great then it may not be able
 167 to be represented as an exact integer by type FPT,
 168 but in practice this is unlikely to be a issue.
 169
 170 [endsect] [/section:float_distance Calculating the Representation Distance
 171    Between Two Floating Point Values (ULP) float_distance]
 172
 173 [section:float_advance Advancing a Floating Point Value by a Specific
 174 Representation Distance (ULP) float_advance]
 175
 176 Function float_advance advances a floating point number by a specified number
 177 of ULP.
 178
 179 [h4 Synopsis]
 180
 181 ``
 182 #include <boost/math/special_functions/next.hpp>
 183 ``
 184
 185    namespace boost{ namespace math{
 186
 187    template <class FPT>
 188    FPT float_advance(FPT val, int distance);
 189
 190    }} // namespaces
 191
 192 [h4 Description - float_advance]
 193
 194 Returns a floating point number /r/ such that `float_distance(val, r) == distance`.
 195
 196 [endsect] [/section:float_advance]
 197
 198 [endsect] [/ section:next_float Floating-Point Representation Distance (ULP),
 199    and Finding Adjacent Floating-Point Values]
 200
 201 [/
 202   Copyright 2008 John Maddock and Paul A. Bristow.
 203   Distributed under the Boost Software License, Version 1.0.
 204   (See accompanying file LICENSE_1_0.txt or copy at
 205   http://www.boost.org/LICENSE_1_0.txt).
 206 ]
 207