Version 1.0.2 -- improved Ft implementation and testing

* Improved the implementation and testing of float equality (Ft).
  There is a backwards-incompatible change in that Ft no longer
  accepts an epsilon argument. If Ft doesn't work for you with
  the built-in value (1e-13) then it's probably a bug in this
  library. Theoretically, this should be version 2.0.0, but that
  seems silly and I don't think anyone will be affected. Sorry
  if you are.

Author: gsinclair

Announcements.txt

@@ -1,3 +1,38 @@
+2012-01-27 ruby-talk
+
+Whitestone 1.0.1, a unit testing library, was released on 2012-01-02.  This
+update, 1.0.2, improves the implementation of float-equality testing,
+especially regarding numbers near zero. As it stands, floats are considered
+equal if their 14th significant figure is off by one. There is no provision
+for specifying a tolerance: it is supposed to just work, and if it doesn't
+then it's a bug.
+
+Key features of Whitestone include terse testing code, colorful and
+helpful output, custom assertions, a powerful and intuitive test
+runner, simple debugger integration. The homepage explains and
+demonstrates it well.
+
+Here are the assertion methods:
+  T  -- assert true
+  F  -- assert false
+  N  -- assert object is nil
+  Eq -- assert two objects are equal
+  Mt -- assert string matches regular expression
+  Id -- assert two objects are identical (same object)
+  E  -- assert error is raised
+  Ko -- assert an object is kind_of a class/module
+  Ft -- assert two floats are essentially equal
+  C  -- assert object is thrown
+
+Homepage: http://gsinclair.github.com/whitestone.html
+Code: http://github.com/gsinclair/whitestone
+Licence: MIT
+
+Regards,
+Gavin
+
+-------------------------------------------------------------------------------
+
 2012-01-02 ruby-talk
 
 Hi all,

History.txt

@@ -1,3 +1,15 @@
+=== 1.0.2 / 2012-01-27
+
+* Improved the implementation and testing of float equality (Ft).
+  There is a backwards-incompatible change in that Ft no longer
+  accepts an epsilon argument. If Ft doesn't work for you with
+  the built-in value (1e-13) then it's probably a bug in this
+  library. Theoretically, this should be version 2.0.0, but that
+  seems silly and I don't think anyone will be affected. Sorry
+  if you are.
+
+* Correct Ruby dependency set in the gemspec (>= 1.8.7).
+
 === 1.0.1 / 2012-01-02
 
 * Correction in README.txt

doc/whitestone.markdown

@@ -797,6 +797,9 @@ They are hardcoded and it would be a major effort to customise them!
 * July 2010: originally developed under the name 'attest' but not released
 * 2 JAN 2012: version 1.0.0
 * 2 JAN 2012: version 1.0.1 with corrected README.txt
+* 27 JAN 2012: version 1.0.2 with improved implementation and testing of float
+  equality (Ft). Note slight backwards incompatibility: Ft no longer accepts
+  'epsilon' argument.
 
 ### Future plans
 

lib/whitestone/assertion_classes.rb

@@ -263,33 +263,60 @@ def message
     end  # class Assertion::KindOf
 
     class FloatEqual < Base
-      EPSILON = 0.000001
+      # Experiments have shown this value to be a reliable threshold for
+      # ratio-based comparison, but that may be machine-dependant and may be
+      # overturned by more experiments. With this epsilon, floats appear to be
+      # considered equal if their first 13 significant figures are the same.
+      #
+      # Example: 1.1 - 1.0 gives 0.10000000000000009, which differs from 0.1 in
+      # the 17th digit. Therefore, I could, and perhaps should, be more
+      # aggressive and set an even smaller ratio like 1e-16. But I assume that
+      # complicated calculations involving floats would compound representation
+      # errors, so at the moment I choose to be conservative.
+      #
+      # It is by design that the programmer cannot specify a value for epsilon.
+      # This should "just work", and if someone finds a case where this epsilon
+      # is not sufficient for normal use, it is probably a bug in this library
+      # that needs to be addressed. If someone wants to experiment with
+      # different epsilon values, then they can do, for example
+      #   WhiteStone::Assertion::FloatEqual.const_set :EPSILON, 1e-16
+      EPSILON = 1e-13
       def initialize(mode, *args, &block)
         super
         no_block_allowed
         type_check(args, Numeric)
-        @actual, @expected, @epsilon = two_or_three_arguments(args).map { |x| x.to_f }
-        @epsilon ||= EPSILON
+        @actual, @expected = two_arguments(args).map { |x| x.to_f }
+        @epsilon = EPSILON
       end
       def run
-        if @actual.zero? or @expected.zero?
-          # There's no scale, so we can only go on difference.
-          (@actual - @expected) < @epsilon
+        if @actual.zero? and @expected.zero?
+          true
+        elsif @actual.zero? or @expected.zero?
+          # Precisely one of our values is zero. Ratios don't work in this case,
+          # so we work around by adding 0.01 to both to get them away from zero.
+          # We check first to be sure that this would actually work.
+          if (@actual - @expected).abs < 0.00001
+            floats_essentially_equal?(@actual + 0.01, @expected + 0.01)
+          else
+            # They differ by more than 0.00001 so they're clearly not equal enough.
+            false
+          end
         else
-          # We go by ratio. The ratio of two equal numbers is one, so the ratio
-          # of two practically-equal floats will be very nearly one.
-          @ratio = (@actual/@expected - 1).abs
-          @ratio < @epsilon
+          floats_essentially_equal?(@actual, @expected)
         end
       end
+      def floats_essentially_equal?(a, b)
+        @ratio = (a/b - 1).abs
+        @ratio < EPSILON
+      end
       def message
         String.new.tap { |str|
           case @mode
           when :assert
             str << Col["Float equality test failed"].yb
             str << "\n" << Col["  Should be: #{@expected.inspect}"].gb
             str << "\n" << Col["        Was: #{@actual.inspect}"].rb
-            str << "\n" <<     "    Epsilon: #{@epsilon}"
+            str << "\n" <<     "    Epsilon: #{EPSILON}"
             if @ratio
               str << "\n" <<   "      Ratio: #{@ratio}"
             end
@@ -298,7 +325,7 @@ def message
             str << Col[line].yb
             str << "\n" << Col["    Value 1: ", @actual.inspect  ].fmt(:yb, :rb)
             str << "\n" << Col["    Value 2: ", @expected.inspect].fmt(:yb, :rb)
-            str << "\n" <<     "    Epsilon: #{@epsilon}"
+            str << "\n" <<     "    Epsilon: #{EPSILON}"
             if @ratio
               str << "\n" <<   "      Ratio: #{@ratio}"
             end

lib/whitestone/version.rb

@@ -1,3 +1,3 @@
 module Whitestone
-  VERSION = "1.0.2.pre"
+  VERSION = "1.0.2"
 end

test/whitestone_test.rb

@@ -122,28 +122,41 @@
   end
 
   D 'Ft' do
-    Ft  Math::PI, 3.141592    # default tolerance 0.00001
-    Ft! Math::PI, 3.14
-    Ft  Math::PI, 3.14, 0.1   # tolerance for this line is 0.1
-    Ft  Math::PI, 3.14, 0.01
-    Ft  Math::PI, 3.14, 0.001
-    Ft! Math::PI, 3.14, 0.0001
+    D 'basic' do
+      Ft 45.44332211, 45.443322110000000000001
+      Ft! 109.123456, 109.123457   # These are too close to be considered
+                                   # essentially equal.
+    end
     D 'test values of massively differing magnitude' do
       a = 0.000000000837
       b = 0.0000000004315    # a and b are _not_ "essentially" equal
-      c = 100.000000000837
-      d = 100.0000000004315  # c and d _are_ "essentially" equal
       Ft! a, b
       Ft! b, a
+      c = 100.000000000000837
+      d = 100.0000000000004315  # c and d _are_ "essentially" equal
       Ft  c, d
       Ft  d, c
     end
+    D "anomolies like (1.1 - 1.0) does not equal 0.1" do
+      Ft 1.1 - 1.0, 0.1
+      Ft 1.1 - 1.0 - 0.1, 0.0
+      Ft 0.1 + 0.1, 0.2
+      Ft 0.2 + 0.1, 0.3  # This doesn't work when using ==
+      Ft 0.3 + 0.1, 0.4
+      Ft 0.4 + 0.1, 0.5
+      Ft 0.5 + 0.1, 0.6
+      Ft 0.6 + 0.1, 0.7
+      Ft 0.7 + 0.1, 0.8  # Nor does this one
+      Ft 0.8 + 0.1, 0.9
+      Ft 0.9 + 0.1, 1.0
+    end
     D 'integer values' do
       Ft 4,   4
       Ft 4.0, 4
       Ft 4,   4.0
       Ft -13, -13
       Ft -13.0, -13
+      Ft! 4, 5
     end
     D 'zero' do
       Ft 0,   0
@@ -154,26 +167,84 @@
       Ft -1.1102230246251565e-16, 0.0
     end
     D 'numbers near zero' do
-      Ft  0, 0.00000000000124, 0.0000000001
-      Ft  0, 0.00000000000124, 0.00000000001
-      Ft  0, 0.00000000000124, 0.000000000001
-      Ft  0, 0.00000000000124, 0.0000000000001
-      # The next test fails but I don't know what we really should expect.
-      # Ft! 0, 0.00000000000124, 1e-25
+      Ft! 0, 0.001
+      Ft! 0, 0.0001
+      Ft! 0, 0.00001
+      Ft! 0, 0.000001
+      Ft! 0, 0.0000001
+      Ft! 0, 0.00000001
+      Ft! 0, 0.000000001
+      Ft! 0, 0.0000000001
+      Ft! 0, 0.00000000001
+      Ft! 0, 0.000000000001
+      Ft! 0, 0.0000000000001
+      Ft! 0, 0.00000000000001
+      Ft  0, 0.000000000000001      # This is the first float that is
+      Ft  0, 0.0000000000000001     # essentially equal to zero.
+      Ft  0, 0.00000000000000001
+      Ft  0, 0.000000000000000001
     end
     D '(near) equal and negative' do
-      a = -2.0000051298352
-      b = -2.0000051298336
-      Ft a, b, 0.000000001
-      Ft b, a, 0.000000001
-    end
-    D 'tiny numbers' do
-      Ft  1.234567e-50, 1.234568e-50
-      Ft! 1.234567e-50, 1.234567e-51
-    end
-    D 'huge numbers' do
-      Ft  1.234567e50, 1.234568e50
-      Ft! 1.234567e50, 1.234567e51
+      a = -2.000000000051298352
+      b = -2.000000000051298336
+      Ft a, b
+      Ft b, a
+    end
+    D "13th digit differs: not equal enough" do
+      Ft! 1.234567890123e50,  1.23456789122e50
+      Ft! 1.234567890123e40,  1.23456789122e40
+      Ft! 1.234567890123e30,  1.23456789122e30
+      Ft! 1.234567890123e20,  1.23456789122e20
+      Ft! 1.234567890123e10,  1.23456789122e10
+      Ft! 1.234567890123e0,   1.23456789122e0
+      Ft! 1.234567890123e-10, 1.23456789122e-10
+      Ft! 1.234567890123e-20, 1.23456789122e-20
+      Ft! 1.234567890123e-30, 1.23456789122e-30
+      Ft! 1.234567890123e-40, 1.23456789122e-40
+    end
+    D "14th digit differs: equal enough" do
+      Ft 1.2345678901234e90,  1.2345678901233e90
+      Ft 1.2345678901234e90,  1.2345678901234e90
+      Ft 1.2345678901234e90,  1.2345678901235e90
+      Ft 1.2345678901234e50,  1.2345678901233e50
+      Ft 1.2345678901234e50,  1.2345678901234e50
+      Ft 1.2345678901234e50,  1.2345678901235e50
+      Ft 1.2345678901234e10,  1.2345678901233e10
+      Ft 1.2345678901234e10,  1.2345678901234e10
+      Ft 1.2345678901234e10,  1.2345678901235e10
+      Ft 1.2345678901234e0,   1.2345678901233e0
+      Ft 1.2345678901234e0,   1.2345678901234e0
+      Ft 1.2345678901234e0,   1.2345678901235e0
+      Ft 1.2345678901234e-10, 1.2345678901233e-10
+      Ft 1.2345678901234e-10, 1.2345678901234e-10
+      Ft 1.2345678901234e-10, 1.2345678901235e-10
+      Ft 1.2345678901234e-50, 1.2345678901233e-50
+      Ft 1.2345678901234e-50, 1.2345678901234e-50
+      Ft 1.2345678901234e-50, 1.2345678901235e-50
+      Ft 1.2345678901234e-90, 1.2345678901233e-90
+      Ft 1.2345678901234e-90, 1.2345678901234e-90
+      Ft 1.2345678901234e-90, 1.2345678901235e-90
+      D "but it can only be off by 1" do
+        Ft! 1.2345678901234e90, 1.2345678901231e90
+        Ft! 1.2345678901234e90, 1.2345678901232e90
+        Ft! 1.2345678901234e90, 1.2345678901236e90
+        Ft! 1.2345678901234e90, 1.2345678901237e90
+        Ft! 1.2345678901234e10, 1.2345678901231e10
+        Ft! 1.2345678901234e10, 1.2345678901232e10
+        Ft! 1.2345678901234e10, 1.2345678901236e10
+        Ft! 1.2345678901234e10, 1.2345678901237e10
+        Ft! 1.2345678901234e-10, 1.2345678901231e-10
+        Ft! 1.2345678901234e-10, 1.2345678901232e-10
+        Ft! 1.2345678901234e-10, 1.2345678901236e-10
+        Ft! 1.2345678901234e-10, 1.2345678901237e-10
+        Ft! 1.2345678901234e-90, 1.2345678901231e-90
+        Ft! 1.2345678901234e-90, 1.2345678901232e-90
+        Ft! 1.2345678901234e-90, 1.2345678901236e-90
+        Ft! 1.2345678901234e-90, 1.2345678901237e-90
+      end
+    end
+    D "Ft does not allow epsilon argument" do
+      E(AssertionSpecificationError) { Ft? 3.14159265, 3.1415, 0.01 }
     end
   end