[Boost-commit] svn:boost r45253 - sandbox/math_toolkit/libs/math/doc/sf_and_dist

From: pbristow_at_[hidden]
Date: 2008-05-09 14:49:14

Author: pbristow
Date: 2008-05-09 14:49:14 EDT (Fri, 09 May 2008)
New Revision: 45253
URL: http://svn.boost.org/trac/boost/changeset/45253

Log:
Enhanced and title changed.
Text files modified: 
   sandbox/math_toolkit/libs/math/doc/sf_and_dist/float_next.qbk |   118 +++++++++++++++++++++++++++++---------- 
   1 files changed, 87 insertions(+), 31 deletions(-)

Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/float_next.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/float_next.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/float_next.qbk	2008-05-09 14:49:14 EDT (Fri, 09 May 2008)
@@ -1,34 +1,68 @@
-[section:next_float Floating Point Representation Distance (ULP), 
-   and Moving Between Adjacent Floating Point Values]
+[section:next_float Floating-Point Representation Distance (ULP), 
+   and Finding Adjacent Floating-Point Values]
    
-[section:nextafter Moving to the Next Representable Value in 
-   a Specific Direction (nextafter)]
+[@http://en.wikipedia.org/wiki/Unit_in_the_last_place Unit of Least Precision or Unit in the Last Place]
+is the gap between two different, but as close as possible, floating-point numbers.
+
+Most decimal values, for example 0.1, cannot be exactly represented as floating-point values,
+but will be stored as the closest representable floating-point.
+
+Functions are provided for finding adjacent greater and lesser floating-point values,
+and estimating the number of gaps between any two floating-point values.
+
+The floating-point type FPT must have has a fixed number of bits in the representation.
+The number of bits may set at runtime, but must be the same for all numbers.
+For example, __NTL_quad_float type (fixed 128-bit representation)
+or __NTL_RR type (arbitrary but fixed decimal digits, default 150)
+but *not* a type that extends the representation to provide an exact representation
+for any number, for example [@http://keithbriggs.info/xrc.html XRC eXact Real in C].
+
+[section:nextafter Finding the Next Representable Value in a Specific Direction (nextafter)]
    
 [h4 Synopsis]
 
 ``
 #include <boost/math/special_functions/next.hpp>
 ``
-
-   namespace boost{ namespace math{
+ 
+  namespace boost{ namespace math{
    
-   template <class T>
-   T nextafter(T val, T direction);
+  template <class FPT>
+  FPT nextafter(FPT val, FPT direction);
    
-   }} // namespaces
+  }} // namespaces
 
-[h4 Description]
+[h4 Description - nextafter]
 
 This is an implementation of the `nextafter` function included in the C99 standard.
+(It is also effectively an implementation of the C99 'nexttoward' legacy function
+which differs only having a long double direction,
+and can generally serve in its place if required). 
+
+[note The C99 functions must use suffixes f and l to distinguish float and long double versions.
+C++ uses the template mechanism instead.]
 
 Returns the next representable value after /x/ in the direction of /y/.  If
 `x == y` then returns /x/.  If /x/ is non-finite then returns the result of
 a __domain_error.  If there is no such value in the direction of /y/ then
 returns an __overflow_error.
 
+[h4 Examples - nextafter]
+
+The two representations using a 32-bit float either side of unity are given by
+``
+The nearest & exact representation of 1.F is 1.10000000
+nextafter(1.F, 999) is                       1.00000012
+nextafter(1/f, -999) is                      0.99999994
+
+The nearest (not exact) representation of 0.1F is 0.100000001
+nextafter(0.1F, 10) is                            0.100000009
+nextafter(0.1F, 10) is                            0.099999994
+``
+
 [endsect]
 
-[section:float_next Moving to the Next Greater Representable Value]
+[section:float_next Finding the Next Greater Representable Value (float_next)]
    
 [h4 Synopsis]
 
@@ -38,21 +72,25 @@
 
    namespace boost{ namespace math{
    
-   template <class T>
-   T float_next(T val);
+   template <class FPT>
+   FPT float_next(FPT val);
    
    }} // namespaces
 
-[h4 Description]
+[h4 Description - float_next]
 
 Returns the next representable value which is greater than /x/.  
 If /x/ is non-finite then returns the result of
 a __domain_error.  If there is no such value greater than /x/ then
 returns an __overflow_error.
 
-[endsect]
+Has the same effect as
 
-[section:float_prior Moving to the Next Smaller Representable Value]
+  nextafter(val, std::numeric_limits<FPT>::max());
+
+[endsect] [/section:float_next Finding the Next Greater Representable Value (float_prior)]
+
+[section:float_prior Finding the Next Smaller Representable Value (float_prior)]
    
 [h4 Synopsis]
 
@@ -62,22 +100,31 @@
 
    namespace boost{ namespace math{
    
-   template <class T>
-   T float_prior(T val);
+   template <class FPT>
+   FPT float_prior(FPT val);
    
    }} // namespaces
-
-[h4 Description]
+   
+  
+[h4 Description - float_prior]
 
 Returns the next representable value which is less than /x/.  
 If /x/ is non-finite then returns the result of
 a __domain_error.  If there is no such value less than /x/ then
 returns an __overflow_error.
 
-[endsect]
+Has the same effect as
+
+  nextafter(val, -std::numeric_limits<FPT>::max());  // Note most negative value -max.
+
+[endsect] [/section:float_prior Finding the Next Smaller Representable Value (float_prior)]
 
 [section:float_distance Calculating the Representation Distance
-   Between Two Floating Point Values (ULP)]
+   Between Two Floating Point Values (ULP) float_distance]
+   
+Function float_distance finds the number of gaps/bits/ULP between any two floating-point values.
+If the significands of floating-point numbers are viewed as integers,
+then their difference is the number of ULP/gaps/bits different.
    
 [h4 Synopsis]
 
@@ -87,27 +134,36 @@
 
    namespace boost{ namespace math{
    
-   template <class T>
-   T float_distance(T a, T b);
+   template <class FPT>
+   FPT float_distance(FPT a, FPT b);
    
    }} // namespaces
 
-[h4 Description]
+[h4 Description - float_distance]
 
-Returns the distance between /a/ and /b/: the result is always an integer
+Returns the distance between /a/ and /b/: the result is always
+a signed integer value (stored in floating-point type FPT)
 representing the number of distinct representations between /a/ and /b/.
 
-Note that `float_distance(a, a)` always returns 0,
-`float_distance(float_next(a), a)` always returns 1, and.
-`float_distance(float_prior(a), a)` always returns -1.
+Note that
+
+* `float_distance(a, a)` always returns 0.
+* `float_distance(float_next(a), a)` always returns 1.
+* `float_distance(float_prior(a), a)` always returns -1.
 
 The function `float_distance` is equivalent to calculating the number
 of ULP (Units in the Last Place) between /a/ and /b/ except that it 
 returns a signed value indicating whether `a > b` or not.
 
-[endsect]
+If the distance is too great then it may not be able
+to be represented as an exact integer by type FPT,
+but in practice this is unlikely to be a issue.
 
-[endsect]
+[endsect] [/section:float_distance Calculating the Representation Distance
+   Between Two Floating Point Values (ULP) float_distance]
+
+[endsect] [/ section:next_float Floating-Point Representation Distance (ULP), 
+   and Finding Adjacent Floating-Point Values]
 
 [/ 
   Copyright 2008 John Maddock and Paul A. Bristow.