[Boost-commit] svn:boost r54997 - sandbox/SOC/2007/visualization/boost/svg_plot/detail

Subject: [Boost-commit] svn:boost r54997 - sandbox/SOC/2007/visualization/boost/svg_plot/detail
From: pbristow_at_[hidden]
Date: 2009-07-17 10:04:52

Author: pbristow
Date: 2009-07-17 10:04:52 EDT (Fri, 17 Jul 2009)
New Revision: 54997
URL: http://svn.boost.org/trac/boost/changeset/54997

Log:
Floating-point comparison routines added to svg_plot/detail/FP_compare.hpp
Text files modified: 
   sandbox/SOC/2007/visualization/boost/svg_plot/detail/FP_compare.hpp |   208 ++++++++++++++++----------------------- 
   1 files changed, 87 insertions(+), 121 deletions(-)

Modified: sandbox/SOC/2007/visualization/boost/svg_plot/detail/FP_compare.hpp
==============================================================================
--- sandbox/SOC/2007/visualization/boost/svg_plot/detail/FP_compare.hpp	(original)
+++ sandbox/SOC/2007/visualization/boost/svg_plot/detail/FP_compare.hpp	2009-07-17 10:04:52 EDT (Fri, 17 Jul 2009)
@@ -1,46 +1,33 @@
-/*! \file FP_compare.hpp
-    \brief Two types of floating-point comparison "Very close" and "Close enough" to a chosen tolerance.
-    \details
-      Derived from Boost.Test Copyright Gennadiy Rozental 2001-2007.
-      See http://www.boost.org/libs/test for the Boost.Test library home page.
-      Deliberately removed any treatment of percent to avoid further potential confusion!
-    \date Mar 2009
-    \author Paul A. Bristow
-*/
-
-//  Copyright Paul A. Bristow 2008, 2009
+//  Copyright Paul A. Bristow 2008
+//  derived from Copyright Gennadiy Rozental 2001-2007.
 
 //  Distributed under the Boost Software License, Version 1.0.
-//  (See accompanying file LICENSE_1_0.txt or copy at
+//  (See accompanying file LICENSE_1_0.txt or copy at 
 //  http://www.boost.org/LICENSE_1_0.txt)
 
-#ifndef BOOST_FLOATING_POINT_COMPARISON_HPP
-#define BOOST_FLOATING_POINT_COMPARISON_HPP
+//  See http://www.boost.org/libs/test for the library home page.
+//  Deliberately removed any treatment of percent!
 
-#include <boost/limits.hpp>  // using std::numeric_limits
-#include <boost/math/tools/precision.hpp> // using max_value, min_value & epsilon for floating_point type.
+#ifndef BOOST_TEST_FLOATING_POINT_COMPARISON_HPP
+#define BOOST_TEST_FLOATING_POINT_COMPARISON_HPP
 
-//namespace boost
-//{
-//  namespace math
-//  {
+#include <boost/limits.hpp>  // for std::numeric_limits
+#include <boost/math/tools/precision.hpp> // for max_value, min_value & epsilon for floating_point type;
 
 // Check two floating-point values are close within a chosen tolerance.
-template<typename FPT> class close_to; // Default = double.
+template<typename FPT> class close_to;
 
 // Check floating-point value is smaller than a chosen small value.
-template<typename FPT> class smallest; // Default = double.
+template<typename FPT> class smallest;
 
 enum floating_point_comparison_type
-{ /*! \enum floating_point_comparison_type
-   \brief Two types of floating-point comparison "Very close" and "Close enough".
-   \details equations in Douglas E. Knuth, Seminumerical algorithms (3rd Ed) section 4.2.4, Vol II,
-    pp 213-225, Addison-Wesley, 1997, ISBN: 0201896842.\n
-    Strong requires closeness relative to \b both values being compared,
-    Weak only requires only closeness relative to \b either \b one value.
-  */
-  FPC_STRONG, //!< "Very close"   - Knuth equation 1 (the default).
-  FPC_WEAK    //!< "Close enough" - Knuth equation 2.
+{ // Two types of comparison.
+  FPC_STRONG, // "Very close"   - Knuth equation 1'  the default.
+  FPC_WEAK    // "Close enough" - equation 2'.
+  // equations in Dougles E. Knuth, Seminumerical algorithms (3rd Ed) section 4.2.4, Vol II,
+  // pp 213-225, Addison-Wesley, 1997, ISBN: 0201896842.
+  // Strong requires closeness relative to BOTH values begin compared,
+  // Weak only requires only closeness to EITHER ONE value. 
 };
 
 // GNU int gsl_fcmp (double x, double y, double epsilon) provides similar function.
@@ -55,28 +42,31 @@
 // www.boost.org/libs/test/doc/components/test_tools/floating_point_comparison.html
 // Comparison of Floating Point Numbers, Matthias Ruppwww.mrupp.info/Data/2007floatingcomp.pdf, July 2007.
 // The pitfalls of verifying floating-point computations, David Monniaux
-// CNRS Ecole normale superieure, 1 Feb 2008, http://arxiv.org/abs/cs/0701192v4
+// CNRS Ecole normale sup´erieure, 1 Feb 2008, http://arxiv.org/abs/cs/0701192v4
 // submitted to ACM TOPLAS.
 
-// \tparam FPT is Floating-Point Type: float, double, long double, or User-Defined like NTL quad_float or RR.
+// FPT is Floating-Point Type: float, double, long double, or User-Defined like NTL quad_float or RR.
 // from boost/math/tools/precision.hpp
-template <class FPT> FPT max_value(FPT); //!< maximum value for floating-point type T.
-template <class FPT> FPT min_value(FPT); //!< minimum value for floating-point type T.
-template <class FPT> FPT epsilon(FPT); //!< epsilon for type T (about 1e-16 for double)
+template <class T> T max_value(T);
+template <class T> T min_value(T);
+template <class T> T epsilon(T);
 
 template<typename FPT> FPT
-fpt_abs(FPT arg)
-{ //! abs function (just in case abs is not defined for a user-defined FPT).
+fpt_abs(FPT arg) 
+{ // abs function (just in case abs is not defined for FPT).
   return arg <static_cast<FPT>(0) ? -arg : arg;
 }
 
 template<typename FPT> FPT
 safe_fpt_division(FPT f1, FPT f2)
-{ //! Division safe from underflow and overflow. (Both f1 and f2 must be unsigned here).
+{ // Safe from under and overflow.
+  // Both f1 and f2 must be unsigned here.
+ 
   if( (f2 < static_cast<FPT>(1))  && (f1 > f2 * boost::math::tools::max_value<FPT>()) )
   { // Avoid overflow.
     return boost::math::tools::max_value<FPT>();
   }
+
   if( (f1 == static_cast<FPT>(0))
     || ((f2 > static_cast<FPT>(1)) && (f1 < f2 * boost::math::tools::min_value<FPT>()) )
     )
@@ -86,23 +76,17 @@
   return f1 / f2;
 } // safe_fpt_division(FPT f1, FPT f2)
 
-template<typename FPT = double> //! \tparam FPT floating-point type.
-class close_to
-{ /*!
-   \class close_to
-   \brief Test if two floating-point values are close within a chosen tolerance.
-   \details Close can be one of two types of floating-point comparison "Very close" and "Close enough".
-    equations in Dougles E. Knuth, Seminumerical algorithms (3rd Ed) section 4.2.4, Vol II,
-    pp 213-225, Addison-Wesley, 1997, ISBN: 0201896842.
-    Strong requires closeness relative to BOTH values begin compared,
-    Weak only requires only closeness to EITHER ONE value.
+// Check two floating-point values are close within a chosen tolerance.
 
-  */
+template<typename FPT = double>
+class close_to
+{
 public:
-  //! Constructor for close_to from tolerance and strength. (By design, percent is NOT implemented).
+
+  // One constructor for fraction tolerance only.
   template<typename FPT>
-  explicit close_to(FPT tolerance, //!< Fractional tolerance.
-    floating_point_comparison_type fpc_type = FPC_STRONG) //!< strong requires closeness relative to both values.
+  explicit close_to(FPT tolerance, 
+    floating_point_comparison_type fpc_type = FPC_STRONG) 
   :
     fraction_tolerance_(tolerance),
       strong_or_weak_(fpc_type)
@@ -112,91 +96,80 @@
     BOOST_ASSERT(tolerance >= static_cast<FPT>(0));
   }
 
+  //template<typename FPT>
   close_to()
   :
   fraction_tolerance_(2 * boost::math::tools::epsilon<FPT>()),
     strong_or_weak_(FPC_STRONG)
-  { /*! Default is two epsilon for the FPT.\n
-        Note that some user-defined floating-point types may not specialize std::numeric_limits<FPT>::epsilon()
-        so it is convenient to use boost::math::tools::epsilon<FPT>(); instead.
-     */
-
+  { // Default is two epsilon.
   }
 
   bool operator()(FPT left, FPT right) const
-  { //! \brief Test if two floating-point values are close within a chosen tolerance.
-    //! \details Tolerance can be interpreted as Knuth's  "Very close" (equation 1), the default, or "Close enough" (equation 2).
-
+  {
     FPT diff = fpt_abs(left - right);
     FPT d1   = safe_fpt_division(diff, fpt_abs(right));
     FPT d2   = safe_fpt_division(diff, fpt_abs(left));
 
-    return strong_or_weak_
+    return strong_or_weak_ 
       ? ((d1 <= fraction_tolerance_) && (d2 <= fraction_tolerance_)) // Strong.
       : ((d1 <= fraction_tolerance_) || (d2 <= fraction_tolerance_)); // Weak.
   }
 
   FPT size()
-  { //! \return the chosen tolerance, as a \b fraction (not a percentage).
+  { // Get function.
     return fraction_tolerance_;
   }
 
   floating_point_comparison_type strength()
-  { //! \return strength of comparison, Knuth's  "Very close" (equation 1), the default, or "Close enough" (equation 2).
+  { // Get function.
     return strong_or_weak_;
   }
 
 private:
-    FPT fraction_tolerance_; //!< tolerance as a fraction.
-    floating_point_comparison_type strong_or_weak_;  //!< Knuth's  "Very close" (equation 1), the default, or "Close enough" (equation 2).
+    FPT fraction_tolerance_;
+    floating_point_comparison_type strong_or_weak_;
 
 }; // class close_to
 
-template<typename FPT = double> //! \tparam FPT floating-point type.
-class smallest
-{ /*! \class smallest
-      \brief Check floating-point value is smaller than a chosen small value,
-         default is twice min_value() for the floating-point type FPT.
-      \details
-       It is somewhat common for beginners to add a comparison check to 0 before
-       computing a division, in order to avoid possible division-by-zero exceptions or
-       the generation of infinite results.\n
-       A first objection to this practise is that, anyway,
-       computing 1/x for x very close to zero will generate very large numbers
-       that will most probably result in overflows later.\n
-       Another objection, which few programmers know about and that we wish to draw attention
-       to, is that it may actually fail to work, depending on what the compiler
-       does, that is, the program may actually test that x == 0, then, further down,
-       find that x = 0 without any apparent change to x!\n
-       David Monniaux, http://arxiv.org/abs/cs/0701192v4.
-       \tparam FPT A floating-point type, float, double, long double or user-defined like NTL quad_float or RR.
-   */
+// Check floating-point value is smaller than a chosen small value.
 
+// David Monniaux, http://arxiv.org/abs/cs/0701192v4,
+// It is somewhat common for beginners to add a comparison check to 0 before
+// computing a division, in order to avoid possible division-by-zero exceptions or
+// the generation of infinite results. A first objection to this practise is that, anyway,
+// computing 1/x for x very close to zero will generate very large numbers
+// that will most probably result in overflows later.
+// Another objection, which few programmers know about and that we wish to draw attention
+// to, is that it may actually fail to work, depending on what the compiler
+// does — that is, the program may actually test that x 6= 0, then, further down,
+// find that x = 0 without any apparent change to x!
+
+template<typename FPT = double>
+class smallest
+{
 public:
   template<typename FPT>
-  explicit smallest(FPT s)
+  explicit smallest(FPT s) 
   :
   smallest_(s)
-  { /*! Constructor with user defined value of smallest, for example 10 * min_value<FPT>.
-        Note that some user-defined floating-point types may not specialize std::numeric_limits<FPT>::min_value()
-        so it is convenient to use boost::math::tools::min_value<FPT>(); instead.
-    */
+  { // Constructor.
   }
 
-  smallest()
+  smallest() 
   :
   smallest_(2 * boost::math::tools::min_value<FPT>())
-  { /*! Default Constructor with smallest_ =  2. * boost::math::tools::min_value<double>();\n
-       multiplier m = 2 (must be integer or static_cast<FPT>())
-       is chosen to allow for a few bits of computation error.\n
-       Pessimistic multiplier is the number of arithmetic operations,
-       assuming every operation causes a 1 least significant bit error,
-       but a more realistic average might be half this.
-     */
+  { // Default Constructor.
+    // smallest_ =  2. * boost::math::tools::min_value<double>();
+    // multiplier m = 2 (must be integer or static_cast<FPT>())
+    // is chosen to allow for a few bits of computation error.
+    // Pessimistic multiplier is the number of arithmetic operations,
+    // assuming every operation causes a 1 least significant bit error,
+    // but a more realistic average would be half this.
   }
 
+  template<typename FPT>
   bool operator()(FPT fp_value, FPT s)
-  { //! True if value is smaller than a smallest value s.
+  {
     if (fpt_abs(fp_value) == static_cast<FPT>(0))
     { // Test for zero first in case FPT is actually an integer type zero,
       // when the comparison < below would fail because
@@ -206,44 +179,37 @@
     return fpt_abs(fp_value) < fpt_abs(s);
   } // bool operator()
 
+  template<typename FPT>
   bool operator()(FPT fp_value)
-  { //! True if value is smaller than chosen smallest value.
+  {
+   
     if (fpt_abs(fp_value) == static_cast<FPT>(0))
     { // Test for zero first in case FPT is actually an integer type,
-      // when the comparison < below would fail because smallest could become zero.
+      // when the comparison < below would fail because
+      // smallest could become zero.
       return true;
     }
     return fpt_abs(fp_value) < fpt_abs(smallest_);
   } // bool operator()
 
   FPT size()
-  { //! \return chosen smallest value that will be counted as effectively zero.
+  { // Get function.
     return smallest_;
   }
 
 private:
-  FPT smallest_; //!< Chosen smallest value that will be counted as effectively zero.
+  // Smallest value that will be counted as effectively zero.
+  FPT smallest_;
+
 }; // class smallest
 
-// Define two convenience typedefs.
+// Since double and the default smallest value 2 * min_value = 4.45015e-308
+// is a very common requirement, provide an convenience alias for this:
+typedef smallest<double> tiny; // Allow tiny as a shorthand for 1e-308
 
-typedef smallest<double> tiny;
-/*!
-  \typedef tiny
-  \brief Allow tiny as a shorthand for twice the double min_value 4.45e-308.
-  \details Since double and the default smallest value 2 * std::numeric_limits<double>::min_value() = 2 * 2.22507e-308 + 4.45015e-308
-  is a very common requirement, provide an convenience alias for this.
-*/
-
-/*!
-  \typedef neareq
-  \brief Allow neareq as a shorthand for twice double epsilon = 4.44e-16
-  \details Since double and the default close_to value 2 * epsilon =  std::numeric_limits<double>::epsilon = 2 * 2.220446e-016 = 4.440892e-016
-  is a very common requirement, provide an convenience alias for this.
-*/
-typedef close_to<double> neareq;
 
- // namespace math
- // namespace boost
+// Since double and the default smallest value 2 * min_value = 4.45015e-308
+// is a very common requirement, provide an convenience alias for this:
+typedef close_to<double> neareq; // Allow tiny as a shorthand for epsilon
 
 #endif // BOOST_FLOATING_POINT_COMPARISON_HPP