long-decimal 1.00.01 → 1.00.02

data/test/testlongdeclib.rb

@@ -4,8 +4,8 @@
 #
 # (C) Karl Brodowsky (IT Sky Consulting GmbH) 2006-2009
 #
-# CVS-ID:    $Header: /var/cvs/long-decimal/long-decimal/test/testlongdeclib.rb,v 1.41 2011/01/16 21:12:42 bk1 Exp $
-# CVS-Label: $Name: RELEASE_1_00_00 $
+# CVS-ID:    $Header: /var/cvs/long-decimal/long-decimal/test/testlongdeclib.rb,v 1.42 2011/02/03 00:22:39 bk1 Exp $
+# CVS-Label: $Name:  $
 # Author:    $Author: bk1 $ (Karl Brodowsky)
 #
 
@@ -21,13 +21,12 @@ class Integer
   end
 end
 
-
 #
 # test class for LongDecimal and LongDecimalQuot
 #
 module TestLongDecHelper
 
-  @RCS_ID='-$Id: testlongdeclib.rb,v 1.41 2011/01/16 21:12:42 bk1 Exp $-'
+  @RCS_ID='-$Id: testlongdeclib.rb,v 1.42 2011/02/03 00:22:39 bk1 Exp $-'
 
   def assert_equal_float(lhs, rhs, delta=0, msg="")
     if ((lhs - rhs).abs >= delta)
@@ -37,11 +36,13 @@ module TestLongDecHelper
   end
 
   def assert_equal_rbo(lhs, rhs, msg="", lhsname="lhs", rhsname="rhs", delta=0)
-    msg2 = "#{lhsname}=#{lhs} #{rhsname}=#{rhs} " + msg
+    msg2 = "#{lhsname}=#{lhs} (#{lhs.class}) #{rhsname}=#{rhs} (#{rhs.class}) " + msg
     if (lhs.kind_of? Rational) && (rhs.kind_of? BigDecimal) || (lhs.kind_of? BigDecimal) && (rhs.kind_of? Rational)
       assert_equal(lhs.to_ld, rhs.to_ld, msg2)
     elsif (delta > 0 && ((lhs.kind_of? Float) || (rhs.kind_of? Float)))
       assert_equal_float(lhs, rhs, delta, msg2 + " d=#{delta}")
+    elsif ((lhs.kind_of? Rational) && (rhs.kind_of? Rational))
+      assert_equal(lhs.numerator*rhs.denominator, lhs.denominator*rhs.numerator, msg)
     else
       assert_equal(lhs, rhs, msg2)
     end
@@ -499,6 +500,11 @@ module TestLongDecHelper
     y = y.to_ld
     # calculate z = x**y
     z = LongMath.power(x, y, prec)
+    prec_dp = 2*prec+1
+    z_dp = LongMath.power(x, y, prec_dp)
+    msg = "x=#{x}\ny=#{y}\nz=#{z}\nz_dp=#{z_dp}\nprec=#{prec}"
+    puts msg
+    assert((z - z_dp).abs <= 2*z.unit, msg)
 
     corr2 = (x - 1).abs*1000000000 # 10**9
     if (z.abs < LongMath::MAX_FLOATABLE && corr2 > 1)
@@ -509,23 +515,23 @@ module TestLongDecHelper
       zf = z.to_f
       qf = 1e9
       delta = [ z.unit.to_f, zf.abs / qf ].max
-      # puts "delta=#{delta} z=#{z} zu=#{z.unit} zuf=#{z.unit.to_f} zf=#{zf} |zf/qf|=#{zf.abs/qf}"
       if (yf.abs > 1)
         l = Math.log(yf.abs)
         if (l > 1)
           delta *= l
         end
-        # puts "delta=#{delta} l=#{l}"
       end
       corr = corr2 * 0.5
       if corr > 1
         corr_f = [ corr.to_f, 5.0 ].min
         delta *= corr_f
       end
-      # puts "delta=#{delta} corr_f=#{corr_f} corr=#{corr}"
 
       diff  = (zf - wf).abs
-      assert_equal_float(zf, wf, delta, "z=#{z}=#{zf} and wf=#{wf.to_s} should be almost equal x=#{x}=#{xf} y=#{y}=#{yf} delta=#{delta} l=#{l} diff=#{diff} prec=#{prec} corr=#{corr}=#{corr.to_f} corr2=#{corr2}=#{corr2.to_f} corr_f=#{corr_f}")
+      msg = "z=#{z}=#{zf} and wf=#{wf.to_s} should be almost equal\nx=#{x}=#{xf}\ny=#{y}=#{yf}\ndelta=#{delta}\nl=#{l}\ndiff=#{diff}\nprec=#{prec}\ncorr=#{corr}=#{corr.to_f}\ncorr2=#{corr2}=#{corr2.to_f}\ncorr_f=#{corr_f}"
+      puts msg
+      assert_equal_float(zf, wf, delta, msg)
+      puts "OK"
     end
 
     # check by taking log(z) = y * log(x)
@@ -549,9 +555,14 @@ module TestLongDecHelper
       if (y.abs > 1) then
         l10y = (Math.log(y.abs.to_f) / Math.log(10)).ceil
       end
+      lprec_dp = 2*lprec+1
       u = LongMath.log(z, lprec)
+      u_dp = LongMath.log(z_dp, lprec_dp)
       v = LongMath.log(x, lprec+l10y)
+      v_dp = LongMath.log(x, lprec_dp + l10y)
       yv = (y*v).round_to_scale(lprec, LongDecimal::ROUND_HALF_DOWN)
+      yv_dp = (y * v_dp).round_to_scale(lprec_dp, LongDecimal::ROUND_HALF_DOWN)
+      assert((u_dp - yv_dp).abs <= unit, "u=log(z,#{lprec})=#{u_dp}=#{u} and yv=y*v=y*log(x,#{lprec+l10y})=#{yv_dp}=#{yv} should be almost equal (unit=#{unit} x=#{x.to_s} y=#{y.to_s} z=#{z_dp}=#{z.to_s} u=#{u_dp}=#{u.to_s} v=#{v_dp}=#{v.to_s} lprec=#{lprec} prec=#{prec} lprec_dp=#{lprec_dp} prec_dp=#{prec_dp})")
       assert((u - yv).abs <= unit, "u=log(z,#{lprec})=#{u} and yv=y*v=y*log(x,#{lprec+l10y})=#{yv} should be almost equal (unit=#{unit} x=#{x.to_s} y=#{y.to_s} z=#{z.to_s} u=#{u.to_s} v=#{v.to_s} lprec=#{lprec} prec=#{prec})")
     end
 
@@ -812,7 +823,6 @@ module TestLongDecHelper
   def check_cbrtb_with_remainder(x, s)
     y, r = LongMath.cbrtb_with_remainder(x)
     z0 = y.cube
-    # puts "x=#{x} y=#{y} z0=#{z0} r=#{r}"
     z1 = z0 + r
     z2 = (y+1).cube
     assert(0 <= y, "cbrt _with_remainder must be >= 0" + s)

data/test/testrandlib.rb

@@ -4,20 +4,21 @@
 #
 # (C) Karl Brodowsky (IT Sky Consulting GmbH) 2006-2009
 #
-# CVS-ID:    $Header: /var/cvs/long-decimal/long-decimal/test/testrandlib.rb,v 1.9 2009/04/15 19:29:38 bk1 Exp $
-# CVS-Label: $Name: RELEASE_1_00_00 $
+# CVS-ID:    $Header: /var/cvs/long-decimal/long-decimal/test/testrandlib.rb,v 1.10 2011/02/03 00:22:39 bk1 Exp $
+# CVS-Label: $Name:  $
 # Author:    $Author: bk1 $ (Karl Brodowsky)
 #
 
-#require "rubygems"
-require "crypt/ISAAC"
+require "rubygems"
+# require "crypt/ISAAC"
+require "crypt-isaac"
 
 #
 # test class for LongDecimal and LongDecimalQuot
 #
 module TestRandomHelper
 
-  @RCS_ID='-$Id: testrandlib.rb,v 1.9 2009/04/15 19:29:38 bk1 Exp $-'
+  @RCS_ID='-$Id: testrandlib.rb,v 1.10 2011/02/03 00:22:39 bk1 Exp $-'
 
   @@r1 = Crypt::ISAAC.new
   @@r2 = Crypt::ISAAC.new

data/test/testrandom.rb

@@ -4,17 +4,24 @@
 #
 # (C) Karl Brodowsky (IT Sky Consulting GmbH) 2006-2009
 #
-# CVS-ID:    $Header: /var/cvs/long-decimal/long-decimal/test/testrandom.rb,v 1.17 2009/05/09 15:37:00 bk1 Exp $
-# CVS-Label: $Name: RELEASE_1_00_00 $
+# CVS-ID:    $Header: /var/cvs/long-decimal/long-decimal/test/testrandom.rb,v 1.18 2011/02/03 00:22:39 bk1 Exp $
+# CVS-Label: $Name:  $
 # Author:    $Author: bk1 $ (Karl Brodowsky)
 #
 
-require "runit/testcase"
-require "runit/cui/testrunner"
-require "runit/testsuite"
+$test_type = nil
+if ((RUBY_VERSION.match /^1\./) || (RUBY_VERSION.match /^2\.0/)) then
+  require 'test/unit'
+  $test_type = :v20
+else
+  require 'minitest/autorun'
+  require 'test/unit/assertions'
+  include Test::Unit::Assertions
+  $test_type = :v21
+end
 
-#require "rubygems"
-require "crypt/ISAAC"
+require "rubygems"
+require "crypt-isaac"
 
 load "lib/long-decimal.rb"
 load "test/testlongdeclib.rb"
@@ -22,14 +29,23 @@ load "test/testrandlib.rb"
 
 LongMath.prec_overflow_handling = :warn_use_max
 
+if ($test_type == :v20)
+  class UnitTest < Test::Unit::TestCase
+  end
+else
+  class UnitTest < MiniTest::Test
+  end
+end
+
 #
 # test class for LongDecimal and LongDecimalQuot
 #
-class TestRandom_class < RUNIT::TestCase
+class TestRandom_class < UnitTest
   include TestLongDecHelper
   include TestRandomHelper
+  include LongDecimalRoundingMode
 
-  @RCS_ID='-$Id: testrandom.rb,v 1.17 2009/05/09 15:37:00 bk1 Exp $-'
+  @RCS_ID='-$Id: testrandom.rb,v 1.18 2011/02/03 00:22:39 bk1 Exp $-'
 
   # for how many seconds should this test run? change to different
   # value on demand
@@ -40,14 +56,14 @@ class TestRandom_class < RUNIT::TestCase
       @scnt += 1
       puts("\ncnt=#{cnt} scnt=#{@scnt} x=#{x} ep=#{eprec} lp=#{lprec} sp=#{sprec} pp=#{pprec}\n")
       if (x <= LongMath::MAX_EXP_ABLE) then
-	check_exp_floated(x, eprec)
+        check_exp_floated(x, eprec)
       end
       if (x > 0)
-	check_log_floated(x, lprec)
+        check_log_floated(x, lprec)
       end
       if (x > 0)
-	xr = x.round_to_scale(sc, LongMath::ROUND_HALF_UP)
-	check_sqrt_with_remainder(xr, sprec, "x=#{x} p=#{sprec}")
+        xr = x.round_to_scale(sc, LongMath::ROUND_HALF_UP)
+        check_sqrt_with_remainder(xr, sprec, "x=#{x} p=#{sprec}")
       end
     end
   end
@@ -71,6 +87,6 @@ class TestRandom_class < RUNIT::TestCase
 
 end
 
-RUNIT::CUI::TestRunner.run(TestRandom_class.suite)
+# RUNIT::CUI::TestRunner.run(TestRandom_class.suite)
 
 # end of file testrandom.rb

data/test/testrandpower.rb

@@ -5,14 +5,20 @@
 # (C) Karl Brodowsky (IT Sky Consulting GmbH) 2006-2009
 #
 # CVS-ID:    $Header: /var/cvs/long-decimal/long-decimal/test/testrandpower.rb,v 1.14 2009/05/09 15:37:00 bk1 Exp $
-# CVS-Label: $Name: RELEASE_1_00_00 $
+# CVS-Label: $Name:  $
 # Author:    $Author: bk1 $ (Karl Brodowsky)
 #
 
-require "runit/testcase"
-require "runit/cui/testrunner"
-require "runit/testsuite"
-require "crypt/ISAAC"
+$test_type = nil
+if ((RUBY_VERSION.match /^1\./) || (RUBY_VERSION.match /^2\.0/)) then
+  require 'test/unit'
+  $test_type = :v20
+else
+  require 'minitest/autorun'
+  require 'test/unit/assertions'
+  include Test::Unit::Assertions
+  $test_type = :v21
+end
 
 load "lib/long-decimal.rb"
 load "lib/long-decimal-extra.rb"
@@ -22,12 +28,21 @@ load "test/testrandlib.rb"
 
 LongMath.prec_overflow_handling = :warn_use_max
 
+if ($test_type == :v20)
+  class UnitTest < Test::Unit::TestCase
+  end
+else
+  class UnitTest < MiniTest::Test
+  end
+end
+
 #
 # test class for LongDecimal and LongDecimalQuot
 #
-class TestRandomPower_class < RUNIT::TestCase
+class TestRandomPower_class < UnitTest
   include TestLongDecHelper
   include TestRandomHelper
+  include LongDecimalRoundingMode
 
   @RCS_ID='-$Id: testrandpower.rb,v 1.14 2009/05/09 15:37:00 bk1 Exp $-'
 
@@ -72,6 +87,6 @@ class TestRandomPower_class < RUNIT::TestCase
 
 end
 
-RUNIT::CUI::TestRunner.run(TestRandomPower_class.suite)
+# RUNIT::CUI::TestRunner.run(TestRandomPower_class.suite)
 
 # end of file testrandpower.rb

data/tex/long-decimal.tex

@@ -0,0 +1,420 @@
+% LaTeX
+% $Header: /var/cvs/long-decimal/long-decimal/tex/long-decimal.tex,v 1.3 2011/02/09 22:51:52 bk1 Exp $
+% $Name:  $
+%
+\documentclass[10pt,a4paper]{article}
+\usepackage{isodate}
+\usepackage[T1]{fontenc}
+\usepackage[latin1]{inputenc}
+\usepackage{graphics}
+\usepackage{amsmath,amssymb}
+\usepackage[a4paper,margin=3cm,footskip=.5cm]{geometry}
+
+\title{The Ruby library {\slshape long-decimal}}
+\author{Karl Brodowsky\\
+IT Sky Consulting GmbH\\
+Switzerland}
+
+\date{2011-02-06}
+
+%\makeatletter
+%\makeatother
+
+\setlength{\topmargin}{0mm}
+%\setlength{\leftmargin}{10mm}
+\setlength{\oddsidemargin}{-11mm}
+\setlength{\evensidemargin}{-11mm}
+\setlength{\parindent}{0mm}
+
+%\newfont{\ocrb}{ocrb10}
+
+\def\ld{\mathrm l}
+\def\ldq{\mathrm q}
+
+\begin{document}
+\sffamily
+\maketitle
+
+\begin{abstract}
+
+The goal of the Ruby-library {\slshape long-decimal}\/ is to provide a new
+numerical type {\slshape LongDecimal\/}\/ and arithmetic operations to deal
+with this type.
+
+\end{abstract}
+
+\section{Introduction}
+
+Ruby supports non-integral numbers with the built-in types {\slshape
+  Float\/} and {\slshape Rational\/} and {\slshape BigDecimal\/}.
+While these are very useful for many purposes, the development of
+finance application requires the availability of a type like
+{\slshape LongDecimal\/}, that allows explicit control of the rounding and uses a
+decimal representation for the fractional part.  An instance of
+{\slshape LongDecimal\/} can be represented as a pair of integral
+numbers $(n, d)$, where the value of the number is $\frac{n}{10^d}$.
+The ring-operations $+$, $-$ and $*$ can be trivially defined in a way
+that does not loose any information (and thus does not require any
+rounding).
+
+Division requires some additional thought, because the exact quotient
+of two {\slshape LongDecimal\/}s can very well be expressed as
+Rational, but not always as {\slshape LongDecimal\/}.  A supplementary
+numeric type {\slshape LongDecimalQuot\/} has been introduced to
+support storing pairs $(r, d)$, where $r$ is a rational number and $d$
+is an estimation about the significant digits after the decimal point.
+The represented value is the rational number $r$.
+
+Calculation of roots and trancendental functions require additional
+information as input parameters to control the number of digits after
+the decimal point and the rounding rules for achieving the result.
+
+In the remainder of this document we will write $\ld(n, d)$ for the
+{\slshape LongDecimal\/}-number represented by the pair $(n, d)$ in
+the manner described above and $\ldq(r, d)$ for the {\slshape
+  LongDecimalQuot\/}-number represented by the pair $(r, n)$.  It
+needs to be observed that the part $d$ in both cases carries
+information about the precision of the number in terms of significant
+digits after the decimal point.
+
+\pagebreak
+
+\section{Ring Operations}
+
+The ring operations $+$, $-$ and $*$ and obvious derived operations
+like negation are defined like this:
+
+$$\bigwedge_{e,d \in \mathbb{N}_0} \bigwedge_{m, n \in \mathbb{Z}}
+\ld(m,d) + \ld(n,e) = \ld(m \cdot 10^{\max(d, e)-d} + n \cdot 10^{\max(d, e)-e}, \max(d, e))$$
+$$\bigwedge_{e,d \in \mathbb{N}_0} \bigwedge_{m, n \in \mathbb{Z}}
+\ld(m,d) - \ld(n,e) = \ld(m \cdot 10^{\max(d, e)-d} - n \cdot 10^{\max(d, e)-e}, \max(d, e))$$
+$$\bigwedge_{e,d \in \mathbb{N}_0} \bigwedge_{m, n \in \mathbb{Z}}
+\ld(m,d) \cdot \ld(n,e) = \ld(m n, d+e)$$
+
+\pagebreak
+
+\section{Rounding Operations}
+
+The library supports two rounding operations that can be applied both
+to {\slshape LongDecimal\/} and {\slshape LongDecimalQuot\/}.  In the
+latter case it implies a conversion to {\slshape LongDecimal\/}.  The
+normal rounding function {\slshape round\_to\_scale\/} changes the
+precision to the given value, while keeping the value expressed by the
+number approximately the same.
+
+The optional second parameter describes how rounding will be done, if the
+process looses information.  It defaults to {\slshape
+ROUND\_UNNECESSARY\/}, in which case an exception is raised whenever
+a value changing rounding process would be required.
+
+The other rounding operations can be grouped into two groups:
+ROUND\_UP, ROUND\_DOWN, ROUND\_CEILING and ROUND\_FLOOR already answer
+the question of how to round completely because they use the values
+that result from rounding as boundaries and obviously round these to
+themselves.
+
+The other rounding operations put a boundary somewhere in the middle
+between allowed rounded values, but they leave the question of how to
+round the boundary itself to be answered as well.  This is expressed
+by having a major rounding mode that defines where the boundaries lie
+and a minor rounding mode that is applicable for values that lie
+exactly on the boundary. In some cases this cannot happen, because
+boundaries are irrational and {\slshape LongDecimal\/} (and {\slshape LongDecimalQuot\/}) can
+only express (some) rational numbers, but for the sake of completeness
+and applicability to other representations, that might allow some
+irrational values, this is done in a uniform way.  Since rounding
+operations can also apply to internal intermediate results, it is a
+good idea not to constrain their definition to rational numbers.
+
+Major rounding modes are 
+
+\begin{tabular}{|l|p{100mm}|}
+\hline
+  MAJOR\_UP           & always round in such a way that the absolute value does not decrease.No minor rounding mode needed.\\
+\hline
+  MAJOR\_DOWN         & always round in such a way that the absolute value does not increase. No minor rounding mode needed.\\
+\hline
+  MAJOR\_CEILING      & always round in such a way that the rational value does not decrease. No minor rounding mode needed.\\
+\hline
+  MAJOR\_FLOOR        & always round in such a way that the rational value does not increase. No minor rounding mode needed.\\
+\hline
+  MAJOR\_HALF         & round to the nearest available value.  The boundary is the arithmetic mean of the two adjacent available values.\\
+\hline
+  MAJOR\_GEOMETRIC    & round to one of the two adjacent available values $x,y$ and use their geometric mean $\sqrt{xy}$ as boundary.  For negative $x,y$ use the negated square root instead.\\
+\hline
+  MAJOR\_HARMONIC     & round to one of the two adjacent available values $x,y$ and use their harmonic mean $\frac{2xy}{x+y}$ as boundary.\\
+\hline
+  MAJOR\_QUADRATIC    & round to one of the two adjacent available values $x,y$ and use their quadratic mean $\sqrt{\frac{x^2+y^2}{2}}$ as boundary.  If $x,y\le 0$ use the negated square root instead.\\
+\hline
+  MAJOR\_CUBIC        & round to one of the two adjacent available values $x,y$ and use their cubic mean $\sqrt[3]{\frac{x^3+y^3}{2}}$ as boundary.\\
+\hline
+  MAJOR\_UNNECESSARY  & raise an exception if value changing rounding would be needed\\
+\hline
+\end{tabular}
+
+\pagebreak
+
+Minor rounding modes are
+
+
+\begin{tabular}{|l|p{100mm}|}
+\hline
+{\bfseries rounding mode}&{\bfseries description}\\
+\hline
+  MINOR\_UNUSED  & no minor rounding mode applies, can only be combined with ROUND\_UP, ROUND\_DOWN, ROUND\_CEILING and ROUND\_FLOOR.\\
+\hline
+  MINOR\_UP      & round values exactly on the boundary by increasing the absolute value (away from zero).\\
+\hline
+  MINOR\_DOWN    & round values exactly on the boundary by decreasing the absolute value (towards zero).\\
+\hline
+  MINOR\_CEILING & round values exactly on the boundary by increasing the rational value (towards $\infty$).\\
+\hline
+  MINOR\_FLOOR   & round values exactly on the boundary by decreasing the rational value (towards $-\infty$).\\
+\hline
+  MINOR\_EVEN    & round values exactly on the boundary by using the choice resulting in the rounded last digit to be even.\\
+\hline
+  MINOR\_ODD     & round values exactly on the boundary by using the choice resulting in the rounded last digit to be odd.\\
+\hline
+\end{tabular}
+
+\pagebreak
+
+These combine to rounding modes:
+
+\begin{tabular}{|l|p{100mm}|}
+\hline
+{\bfseries rounding mode}&{\bfseries description}\\
+\hline
+  ROUND\_UP           & always round in such a way that the absolute value does not decrease.\\
+\hline
+  ROUND\_DOWN         & always round in such a way that the absolute value does not increase.\\
+\hline
+  ROUND\_CEILING      & always round in such a way that the rational value does not decrease.\\
+\hline
+  ROUND\_FLOOR        & always round in such a way that the rational value does not increase.\\
+\hline
+  ROUND\_HALF\_UP      & round to the nearest available value, prefer increasing the absolute value if the last digit is 5\\
+\hline
+  ROUND\_HALF\_DOWN    & round to the nearest available value, prefer decreasing the absolute value if the last digit is 5\\
+\hline
+  ROUND\_HALF\_CEILING & round to the nearest available value, prefer increasing the rational value if the last digit is 5\\
+\hline
+  ROUND\_HALF\_FLOOR   & round to the nearest available value, prefer decreasing the rational value if the last digit is 5\\
+\hline
+  ROUND\_HALF\_EVEN    & round to the nearest available value, prefer the resulting last digit to be even if the last digit prior to rounding is 5\\
+\hline
+  ROUND\_HALF\_ODD    & round to the nearest available value, prefer the resulting last digit to be odd if the last digit prior to rounding is 5\\
+\hline
+  ROUND\_GEOMETRIC\_UP      & round to the available value using the geometric mean as boundary, prefer increasing the absolute value if the unrounded value is exactly on the boundary\\
+\hline
+  ROUND\_GEOMETRIC\_DOWN    & round to the available value, using the geometric mean as boundary, prefer decreasing the absolute value if the unrounded value is exactly on the boundary\\
+\hline
+  \dots & \ldots\\
+\hline
+  ROUND\_HARMONIC\_UP      & round to the available value using the harmonic mean as boundary, prefer increasing the absolute value if the unrounded value is exactly on the boundary\\
+\hline
+  ROUND\_HARMONIC\_DOWN    & round to the available value, using the harmonic mean as boundary, prefer decreasing the absolute value if the unrounded value is exactly on the boundary\\
+\hline
+  \dots & \ldots\\
+\hline
+  ROUND\_QUADRATIC\_UP      & round to the available value using the quadratic mean as boundary, prefer increasing the absolute value if the unrounded value is exactly on the boundary\\
+\hline
+  ROUND\_QUADRATIC\_DOWN    & round to the available value, using the quadratic mean as boundary, prefer decreasing the absolute value if the unrounded value is exactly on the boundary\\
+\hline
+  \dots & \ldots\\
+\hline
+  ROUND\_CUBIC\_UP      & round to the available value using the cubic mean as boundary, prefer increasing the absolute value if the unrounded value is exactly on the boundary\\
+\hline
+  ROUND\_CUBIC\_DOWN    & round to the available value, using the cubic mean as boundary, prefer decreasing the absolute value if the unrounded value is exactly on the boundary\\
+\hline
+  \dots & \ldots\\
+\hline
+  ROUND\_CUBIC\_ODD    & round to the available value using the cubic mean as boundary, prefer the resulting last digit to be odd if the unrounded value is exactly on the boundary\\
+\hline
+  ROUND\_UNNECESSARY  & raise an exception if value changing rounding would be needed\\
+\hline
+\end{tabular}
+
+
+In addition to these commonly available rounding operations {\slshape long-decimal\/} provides rounding to remainder sets.  This is motivated by the practice in some
+currencies to prefer using certain multiples of the smallest unit.  For example in CHF you commonly use two digits after the decimal point, but the last digit is
+required to be 0 or 5.  This is achieved as a special case of a more general concept {\slshape round\_to\_allowed\_remainders\/}.  A modulus $M \ge 2$ and a set
+$R\subset\mathbb{N}_0$ are given and a number $x$ is rounded to $\ld(n, d)$ such that
+
+$$\bigvee_{r\in R} n \equiv r \mod M$$
+
+Typically $M$ is ten or a power of ten, but this is not required.  Neither is it required that zero is a member of $R$.  In that case an additional parameter is needed
+in order to define to which direction a potential last digit of zero would be rounded.  In the CHF case we would have $M=10$ and $R=\{0, 5\}$.
+
+This kind of rounding can be applied to integers as well as to
+{\slshape LongDecimal\/} and {\slshape LongDecimalQuot\/}, in which case the integral numerator
+$n$ of $\ld(n, d)=\frac{n}{10^d}$ must fullfill the additional
+constraint.  In order to avoid complications, this is not supported in
+conjunction with minor rounding modes MINOR\_EVEN and MINOR\_ODD,
+because all matching rounded values might be even or odd and we cannot
+rely on the alternation of even and odd values.
+It is possible to exclude $0$ from the set $R$. In this case a
+ZERO-rounding-mode needs to be provided that tells in which way a
+zero, should it occur, shoud be rounded.
+
+\pagebreak
+
+\section{Division}
+
+Regular division using $/$ yields an instance of {\slshape LongDecimalQuot\/}.  The approximate number of significant digits is estimated by using the partial derivatives of $f(x, y) = \frac{x}{y}$.
+Assume $x=\ld(m, s)$ and $y=\ld(n, t)$.  So we get for $\ld(m, s) / \ld(n, t)$ an result 
+
+$$\frac{x}{y} = \ldq(10^{t-s}\frac{m}{n}, r)$$
+
+with 
+
+$$r \approx -\log_{10}\left(10^{-s} \frac{1}{|y|} + 10^{-t} \frac{|x|}{y^2}\right) 
+    =  2 \log_{10}(y) + s + t -\log_{10}\left(|m| + |n|) \right)$$
+
+In order to avoid expensive logarithmic operation for such basic operations as division this is approximated by
+
+$$r = \max( 0, 2 v + s + t - \max( u + s, v + t) - 3)$$
+with $u = \lfloor\log |m| \rfloor - s + 1$ and $v = \lfloor\log |n| \rfloor - t + 1$ for $m$ and $n$ not zero 
+and $u=-s$ for $m = 0$ and $v=-t$ for $n=0$.  Using $\max(a, b)$ instead of $log_{10}(10^a + 10^b)$ is a good approximation, when a and b are far apart.
+
+It is recommended to use explicit rounding after having performed
+division rather than to rely on this somewhat arbitrary estimation on
+the number of significant digits.  It is possible to retain
+intermediate results with {\slshape LongDecimalQuot\/}, because the
+full arithmetic is available for this type as well, but using rational
+numbers internally it will blow up numerator and denominator to an
+extent that diminishes performance by quite a margin in longer
+calculations.
+
+\pagebreak
+
+\section{Roots}
+
+Square root and cube root of {\slshape LongDecimal\/} can be calculated quite
+efficiently using an algorithm that is somewhat similar to the
+algorithm for long integer division.  This has been preferred over the
+more commonly known Newton algorithm.  Since square and cube roots are
+usually irrational, it is mandatory to provide rounding information
+concerning the number of desired digits and the rounding mode.
+
+Square roots and cube roots can also calculated of integers, in which
+case a variant is available that also calculates a remainder $r$ in
+addition to the approximated square root $s$, such
+that
+$a = s^2+r$.
+
+\section{$\pi$}
+
+The number $\pi$ can be calculated to a given number of digits, which
+works sufficiently fast for a few thousend digits.
+
+Please use dedicated programs if you seriously want to calculate $\pi$
+to millions of digits, Ruby is not fast enough for this kind of number
+crunching to compete with the best C-programs.
+
+\pagebreak
+
+\section{Transcendental Functions}
+
+It is the goal of this library to support the most common
+transcendental functions in the long run.  Currently $\exp$ and $\log$
+are supported.  These are calculated using the Taylor series, but the
+calculation has been improved.  Most important it is to improve the
+convergence, which is the case with a series of the form
+
+$$\sum_{n=0}^\infty \frac{x^n}{n!}$$
+
+for $x< 0.5$.
+
+For the exponential function this can always be achieved by using the following transformations: $x = 2^n x_0$ with $x_0 < 0.5$ implies
+
+$$\exp(x) = \exp(x_0)^{2^n}$$
+
+which can be easily calculated using successive squaring operations.
+
+For the logarithm we first use $x = e^n x_0$ with $n \in \mathbb{N}_0$ and $x_0 < e$ with
+
+$$\log(x) = n + \log(x_0).$$
+
+From here we make use of the efficient square root calculation facility and use 
+
+$$\bigwedge_{m=0}^\infty x_{m+1} = \sqrt{x_m}$$
+
+and
+
+$$\log(x) = n + 2^m \log x_m$$
+
+Using this $x_m$ can be brought sufficiently close to $1$ to make the Taylor series of $\log$ converge sufficiently fast to be useful for the calculation:
+
+$$\log(x_m) = \sum_{k=1}^\infty \frac{(x_m-1)^k(-1)^{k+1}}{k}$$
+
+Another minor optimization uses some integer $j$ and adds
+
+$$ \bigwedge_{l=0}^{j-1} s_k = \sum_{l=0}^n \frac{x^{lj}}{(lj+k)!}$$
+
+from which we finally multiply the partial sums with appropriate low powers of $x$.  This saves on the number of multiplications.
+Similar patterns will be applied to the calculation of other transcendental functions.
+
+\pagebreak
+
+\section{Powers}
+
+Calculation of powers with any positive {\slshape LongDecimal\/} as base and any {\slshape LongDecimal\/} as exponent is quite challenging to do.
+
+It is quite trivial that $x^y = \exp(y \log x)$, but the challenges
+are to achieve the result in acceptable time and with the required
+precision.  The builtin class {\slshape BigDecimal} does not meet
+these goals, because it becomes incredibly slow for certain
+combinations of $x$ and $y$.  The power function of {\slshape LongDecimal\/} has
+been optimized to handle a broad range of cases with different
+approaches to provide precision and speed. This should work fine for
+reasonable practical use, but it will still be possible to construct
+corner cases with bases very close to 1 and large exponents which fail
+in an attempt to do an accurate calculation in their last digits.
+
+\section{Means}
+
+In the class {\slshape LongMath} there are methods for calculating the
+following means: arithmetic\_mean, geometric\_mean, harmonic\_mean,
+quadratic\_mean, cubic\_mean, arithmetic\_geometric\_mean,
+harmonic\_geometric\_mean.  See Wikipedia for their definitions.
+
+\section{Rounding with sum constraint}
+
+Experimental support for rounding of several number simultanously in
+such a way that their rounded sum is the sum of the rounded numbers is
+included with the methods {\slshape LongMath.round\_sum\_hm} which uses
+the Haare-Niemeyer-approach and {\slshape LongMath.round\_sum\_divisor}
+which uses one of several divisor based approaches, like D'Hondt. The
+approach is chosen by the rounding mode. These are not yet implemented
+efficiently nor are they tested well, so use at your own risk (like
+the whole library).
+
+\section{Limitations}
+
+Rounding with sum constraint is not yet production stable.
+
+Powers with bases that are off 1 by $10^{-20}$ or less and exponents
+in the order of magnitude of $10^20$ or more are not always calculated
+precisely.
+
+Some interesting transcendental functions are missing.
+
+Many operations (like power, exp, log and other transcendental functions) fail to work with numbers whose magnitude cannot be
+expressed as double.
+
+Using transcendental functions that have a rounding mode and precision
+as part of their parameter set has not been tested with the newer
+rounding modes, \dots\_ODD, ROUND\_GEOMETRIC\_\dots,
+ROUND\_HARMONIC\_\dots, ROUND\_QUADRATIC\_\dots and
+ROUND\_CUBIC\_\dots.
+These combinations will be tested and improved in future versions.
+
+\section{Tests}
+
+Unit tests have been added to test much of the implemented
+functionality.
+
+More unit tests are desirable.
+
+\end{document}