[前][次][番号順一覧][スレッド一覧]

ruby-changes:19662

From: drbrain <ko1@a...>
Date: Mon, 23 May 2011 09:08:37 +0900 (JST)
Subject: [ruby-changes:19662] drbrain:r31707 (trunk): * lib/mathn.rb: Improve documentation. Patch by Sandor Szucs.

drbrain	2011-05-23 09:08:30 +0900 (Mon, 23 May 2011)

  New Revision: 31707

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=31707

  Log:
    * lib/mathn.rb:  Improve documentation.  Patch by Sandor Szucs.
      [Ruby 1.9 - Bug #4767]

  Modified files:
    trunk/ChangeLog
    trunk/lib/mathn.rb

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 31706)
+++ ChangeLog	(revision 31707)
@@ -1,3 +1,8 @@
+Mon May 23 09:08:07 2011  Eric Hodel  <drbrain@s...>
+
+	* lib/mathn.rb:  Improve documentation.  Patch by Sandor Szucs.
+	  [Ruby 1.9 - Bug #4767]
+
 Mon May 23 08:45:55 2011  Eric Hodel  <drbrain@s...>
 
 	* lib/ostruct.rb:  Improve documentation.  Patch by Franklin Webber.
Index: lib/mathn.rb
===================================================================
--- lib/mathn.rb	(revision 31706)
+++ lib/mathn.rb	(revision 31707)
@@ -1,8 +1,23 @@
 ##
 # = mathn
 #
-# mathn is a library for changing the way Ruby does math.
+# mathn is a library for changing the way Ruby does math. If you need
+# more precise rounding with multiple division or exponentiation
+# operations, then mathn is the right tool. It makes sense to use this
+# library if you can use it's late rounding. Mathn does not convert
+# Fixnums into Floats as long as you do not convert it yourself.
+# Instead of using Float as intermediate value it use Rational as
+# value representation.
 #
+# Example Fixnum with intermediate Float:
+#
+#   20 / 9 * 3 * 14 / 7 * 3 / 2  # => 18
+#
+# Example: using mathn Fixnum/Rational:
+#
+#   require 'mathn'
+#   20 / 9 * 3 * 14 / 7 * 3 / 2  # => 20
+#
 # == Usage
 #
 # To start using this library, simply:
@@ -13,13 +28,13 @@
 #
 #   3 / 2
 #
-# will return (3/2) instead of the usual 1.
+# will return +Rational+ (3/2) instead of the usual +Fixnum+ 1.
 #
 # == Copyright
 #
 # Author: Keiju ISHITSUKA(SHL Japan Inc.)
 #
-# --
+#--
 # $Release Version: 0.5 $
 # $Revision: 1.1.1.1.4.1 $
 
@@ -35,14 +50,29 @@
   Math = CMath
 end
 
+##
+# When mathn is required Fixnum's division and exponentiation are enhanced to
+# return more precise values in mathematical formulas.
+#
+#   2/3*3  # => 0
+#   require 'mathn'
+#   2/3*3  # => 2
+
 class Fixnum
   remove_method :/
+
+  ##
+  # +/+ defines the Rational division for Fixnum.
+  #
+  #   1/3  # => (1/3)
+
   alias / quo
 
   alias power! ** unless method_defined? :power!
 
   ##
-  # exponentiate by +other+
+  # Exponentiate by +other+
+
   def ** (other)
     if self < 0 && other.round != other
       Complex(self, 0.0) ** other
@@ -53,14 +83,25 @@
 
 end
 
+##
+# When mathn is required Bignum's division and exponentiation are enhanced to
+# return more precise values in mathematical formulas.
+
 class Bignum
   remove_method :/
+
+  ##
+  # +/+ defines the Rational division for Bignum.
+  #
+  #   (2**72) / ((2**70) * 3)  # => 4/3
+
   alias / quo
 
   alias power! ** unless method_defined? :power!
 
   ##
-  # exponentiate by +other+
+  # Exponentiate by +other+
+
   def ** (other)
     if self < 0 && other.round != other
       Complex(self, 0.0) ** other
@@ -71,11 +112,27 @@
 
 end
 
+##
+# When mathn is required Rational changes to simplfy the usage of Rational
+# operations.
+#
+# Normal behaviour:
+#
+#   Rational.new!(1,3) ** 2 # => Rational(1, 9)
+#   (1 / 3) ** 2            # => 0
+#
+# require 'mathn' behaviour:
+#
+#   (1 / 3) ** 2            # => 1/9
+
 class Rational
   remove_method :**
 
   ##
-  # exponentiate by +other+
+  # Exponentiate by +other+
+  #
+  #   (1/3) ** 2 # => 1/9
+
   def ** (other)
     if other.kind_of?(Rational)
       other2 = other
@@ -138,11 +195,32 @@
   end
 end
 
+##
+# When mathn is requried the Math module changes as follows:
+#
+# Standard Math module behaviour:
+#   Math.sqrt(4/9)     # => 0.0
+#   Math.sqrt(4.0/9.0) # => 0.666666666666667
+#   Math.sqrt(- 4/9)   # => Errno::EDOM: Numerical argument out of domain - sqrt
+#
+# After require 'mathn' this is changed to:
+#
+#   require 'mathn'
+#   Math.sqrt(4/9)      # => 2/3
+#   Math.sqrt(4.0/9.0)  # => 0.666666666666667
+#   Math.sqrt(- 4/9)    # => Complex(0, 2/3)
+
 module Math
   remove_method(:sqrt)
 
   ##
-  # compute the square root of +a+
+  # Computes the square root of +a+.  It makes use of Complex and
+  # Rational to have no rounding errors if possible.
+  #
+  #   Math.sqrt(4/9)      # => 2/3
+  #   Math.sqrt(- 4/9)    # => Complex(0, 2/3)
+  #   Math.sqrt(4.0/9.0)  # => 0.666666666666667
+
   def sqrt(a)
     if a.kind_of?(Complex)
       abs = sqrt(a.real*a.real + a.imag*a.imag)
@@ -168,7 +246,11 @@
     end
   end
 
-  def rsqrt(a) # :nodoc:
+  ##
+  # Compute square root of a non negative number. This method is
+  # internally used by +Math.sqrt+.
+
+  def rsqrt(a)
     if a.kind_of?(Float)
       sqrt!(a)
     elsif a.kind_of?(Rational)
@@ -220,11 +302,15 @@
   module_function :rsqrt
 end
 
+##
+# When mathn is required Float is changed to handle Complex numbers.
+
 class Float
   alias power! **
 
   ##
-  # exponentiate by +other+
+  # Exponentiate by +other+
+
   def ** (other)
     if self < 0 && other.round != other
       Complex(self, 0.0) ** other

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]