From 9c4ddc9c12c4a9c6bb79af87ded704a996d2d203 Mon Sep 17 00:00:00 2001 From: Sandor Szuecs Date: Sun, 22 May 2011 20:32:41 +0200 Subject: [PATCH] enhanced mathn docs --- lib/mathn.rb | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 files changed, 77 insertions(+), 4 deletions(-) diff --git a/lib/mathn.rb b/lib/mathn.rb index 61de1ff..fb9fe79 100644 --- a/lib/mathn.rb +++ b/lib/mathn.rb @@ -1,7 +1,22 @@ ## # = 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 # @@ -13,7 +28,7 @@ # # 3 / 2 # -# will return (3/2) instead of the usual 1. +# will return +Rational+ (3/2) instead of the usual +Fixnum+ 1. # # == Copyright # @@ -35,8 +50,21 @@ unless defined?(Math.exp!) Math = CMath end +## +# 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! @@ -53,8 +81,15 @@ class Fixnum end +# 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! @@ -71,11 +106,26 @@ class Bignum end +## +# Rational changes that simplfies the usage of Rational opaerations. +# +# normal behaviour: +# +# Rational.new!(1,3) ** 2 #=> Rational(1, 9) +# (1 / 3) ** 2 #=> 0 +# +# mathn behaviour: +# +# (1 / 3) ** 2 #=> 1/9 +# class Rational remove_method :** ## # exponentiate by +other+ + # + # (1/3) ** 2 #=> 1/9 + # def ** (other) if other.kind_of?(Rational) other2 = other @@ -138,11 +188,30 @@ class Rational end end +## +# Changes of the ruby Math module. +# +# 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 +# +# using mathn library 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+ + # Compute 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 +237,9 @@ module Math 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,6 +291,8 @@ module Math module_function :rsqrt end +## +# Float is changed to know Complex numbers. class Float alias power! ** -- 1.7.5.2