ruby-decimal 0.2.0 → 0.2.1

data/History.txt

@@ -1,9 +1,24 @@
 == 0.1.0 2009-06-19
 
-* Initial release 0.1.0
+* Initial release
 
 == 0.2.0 2009-06-21
 
-* Release 0.2.0
-  New functions implemented: exp(), ln(), log10(), power().
+* New functions implemented:
+  exp(), ln(), log10(), power().
+
+
+
+* Bug fixes:
+  - Decimal#inspect was always producing debug information; now it uses $DEBUG
+  - Raising some exceptions caused error, because too many parameters were being
+    passed to the exception's base class initializer.
+
+* New functionality:
+  - ulp (unit in the last place)
+  - normalize (in the classic sense, not in the original GDA sense)
+  - maximum_finite, minimum_normal, minimum_nonzero value decimal constructors
+  - epsilon, strict_epsilon, half_epsilon
+  - setting context exponent limits with elimit
+  - require decimal/shortcut to use D for Decimal
 

data/Manifest.txt

@@ -7,6 +7,7 @@ lib/decimal.rb
 lib/decimal/version.rb
 lib/decimal/decimal.rb
 lib/decimal/support.rb
+lib/decimal/shortcut.rb
 setup.rb
 test/all_tests.rb
 test/helper.rb
@@ -21,4 +22,7 @@ test/test_round.rb
 test/test_exact.rb
 test/test_to_int.rb
 test/test_to_rf.rb
+test/test_epsilon.rb
+test/test_ulp.rb
+test/test_odd_even.rb
 

data/README.txt

@@ -20,10 +20,10 @@ and the revised IEEE 754 standard (IEEE 754-2008).
 
 = Examples of use
 
-To install the library use gem from the command line: (you may not need sudo)
+To install the library use gem from the command line: (you may not need +sudo+)
   sudo gem install ruby-decimal
 
-Then require the library in your code:
+Then require the library in your code (if it fails you may need to <tt>require 'rubygems'</tt> first)
   require 'decimal'
 
 Now we can use the Decimal class simply like this:
@@ -79,8 +79,8 @@ And individual parameters can be assigned like this:
   puts Decimal.context.precision                     -> 9
   puts Decimal.context.rounding                      -> half_even
   Decimal.context(:rounding=>:down) do |context|
-    puts context.precision
-    puts context.rounding
+    puts context.precision                           -> 9
+    puts context.rounding                            -> down
   end
 
 Contexts created with the Decimal::Context() constructor
@@ -173,10 +173,48 @@ an interface compatible with the Ruby interface of Float:
   puts Decimal('101.5').truncate                     -> 101
 
 ==Special values
-TODO
+
+In addition to finite numbers, a Decimal object can represent some special values:
+* Infinity (+Infinity, -Infinity). The method Decimal#infinite? returns true for these to values.
+  Decimal.infinity Decimal.infinity(-1) can be used to get these values.
+* NaN (not a number) represents indefined results. The method Decimal#nan? returns true for it and
+  Decimal.nan can be used to obtain it. There is a variant, sNaN (signaling NaN) that casues
+  an invalid operation condition if used; it can be detected with Decimal.snan?.
+  A NaN can also include diagnostic information in its sign and coefficient.
+
+Any of the special values can be detected with Decimal#special?
+Finite numbers can be clasified with
+these methods:
+* Decimal#zero? detects a zero value (note that there are two zero values: +0 and -0)
+* Decimal#normal? detects normal values: those whose adjusted exponents are not less than the the emin.
+* Decimal#subnormal? detects subnormal values: those whose adjusted exponents are less than the the emin.
 
 ==Exceptions
-TODO
+
+Exceptional conditions that may arise during operations have corresponding classes that represent them:
+* Decimal::InvalidOperation
+* Decimal::DivisionByZero
+* Decimal::DivisionImpossible
+* Decimal::DivisionUndefined
+* Decimal::Inexact
+* Decimal::Overflow
+* Decimal::Underflow
+* Decimal::Clamped
+* Decimal::InvalidContext
+* Decimal::Rounded
+* Decimal::Subnormal
+* Decimal::ConversionSyntax
+
+For each condition, a flag and a trap (boolean values) exist in the context.
+When a condition occurs, the corresponding flag in the context takes the value true (and remains
+set until cleared) and a exception is raised if the corresponding trap has the value true.
+
+  Decimal.context.traps[Decimal::DivisionByZero] = false
+  Decimal.context.flags[Decimal::DivisionByZero] = false
+  puts Decimal(1)/Decimal(0)                                -> Infinity
+  puts Decimal.context.flags[Decimal::DivisionByZero]       -> true
+  Decimal.context.traps[Decimal::DivisionByZero] = true
+  puts Decimal(1)/Decimal(0)                                -> Exception : Decimal::DivisionByZero
 
 ==Numerical conversion
 
@@ -206,6 +244,7 @@ Or with a generic method:
 Conversion is also possible to Float:
   puts Decimal('1.1').to_f                           -> 1.1
   puts Decimal('1.1').convert_to(Float)              -> 1.1
+  puts Float(Decimal('1.1'))                         -> 1.1
 
 And with GDAS style operations:
 
@@ -252,6 +291,46 @@ Note that the conversion we've defined depends on the context precision:
 
   Decimal.local_context(:precision=>12) { puts Decimal(0.1) } -> 0.100000000000
 
+  Decimal.local_context(:exact=>true) { puts Decimal(0.1) }   -> 0.1000000000000000055511151231257827021181583404541015625
+
+== Abbreviation
+
+The use of Decimal can be made less verbose by requiring:
+
+  require 'decimal/shortcut'
+
+This file defines +D+ as a synonym for +Decimal+:
+
+  D.context.precision = 3
+  puts +D('1.234')                                   -> 1.23
+
+== Error analysis
+
+The Decimal#ulp() method returns the value of a "unit in the last place" for a given number
+
+  D.context.precision = 4
+  puts D('1.5').ulp                                  -> 0.001
+  puts D('1.5E10').ulp                               -> 1E+7
+
+Whe can compute the error in ulps of an approximation +aprx+ to correclty rounded value +exct+ with:
+
+  def ulps(exct, aprx)
+    (aprx-exct).abs/exct.ulp
+  end
+
+  puts ulps(Decimal('0.5000'), Decimal('0.5003'))    -> 3
+  puts ulps(Decimal('0.5000'), Decimal('0.4997'))    -> 3
+
+  puts ulps(Decimal('0.1000'), Decimal('0.1003'))    -> 3E+1
+  puts ulps(Decimal('0.1000'), Decimal('0.0997'))    -> 3E+1
+
+  puts ulps(Decimal(1), Decimal(10).next_minus)      -> 8.999E+4
+  puts ulps(Decimal(1), Decimal(10).next_plus)       -> 9.01E+4
+
+Note that in the definition of ulps we use exct.ulp. If we had use aprx.ulp Decimal(10).next_plus
+would seem to be a better approximation to Decimal(1) than Decimal(10).next_minus. (Admittedly,
+such bad approximations should not be common.)
+
 == More Information
 
 Consult the documentation for the classes Decimal and Decimal::Context.
@@ -265,25 +344,33 @@ EXPAND-
 Decimal solves some of the difficulties of using BigDecimal.
 
 One of the major problems with BigDecimal is that it's not easy to control the number of
-significant digits: while addition, subtraction and multiplication are exact (unless a limit is used),
-divisions will need to be passed precision explicitly or they will loose an indeterminate number of digits.
-With Decimal, Context objects are used to specify the exact number of digits to be used for all operations:
+significant digits of the results. While addition, subtraction and multiplication are exact (unless a limit is used),
+divisions will need to be passed precision explicitly or else an indeterminate number of significant digits will be lost.
+Part of the problem is that numbers don't keep track of its precision (0.1000 is not distinguishable from 0.1.)
+
+With Decimal, Context objects are used to specify the exact number of digits to be used for all operations making
+the code cleaner and the results more easily predictable.
+
   Decimal.context.precision = 10
   puts Decimal(1)/Decimal(3)
 Contexts are thread-safe and can be used for individual operations:
-  puts Decimal(1).divide(Decimal(e), Decimal::Context.new(:precision=>4))
+  puts Decimal(1).divide(Decimal(e), Decimal::Context(:precision=>4))
+Which can be abbreviated:
+puts Decimal(1).divide(Decimal(e), :precision=>4)
 Or use locally in a block without affecting other code:
-  Decimal.local_context {
+  Decimal.context {
     Decimal.context.precision = 3
     puts Decimal(1)/Decimal(3)
   }
   puts Decimal.context.precision
+Which can also be abbreviated:
+  Decimal.context(:precision=>3) { puts Decimal(1)/Decimal(3) }
 
 This allows in general to write simpler code; e.g. this is an exponential function, adapted from the
 'recipes' in Python's Decimal:
-    def exp(x,c=nil)
+    def exp(x, c=nil)
       i, lasts, s, fact, num = 0, 0, 1, 1, 1
-      Decimal.local_context(c) do |context|
+      Decimal.context(c) do |context|
         context.precision += 2
         while s != lasts
           lasts = s
@@ -295,9 +382,11 @@ This allows in general to write simpler code; e.g. this is an exponential functi
       end
       return +s
     end
+
 The final unary + applied to the result forces it to be rounded to the current precision
 (because we have computed it with two extra digits)
-The result of this method does not have trailing insignificant digits, as is common with BigDecimal.
+The result of this method does not have trailing non-significant digits, as is common with BigDecimal
+(e.g. in the exp implementation available in the standard Ruby library, in bigdecimal/math)
 
 --
 EXPAND+
@@ -305,5 +394,7 @@ EXPAND+
 
 = Roadmap
 
-* Version 0.3.0: Implement the remaining of GDA functions
-* Complete documentation (README sections on special values & exceptions, etc. and method descriptions.)
+* Version 0.3.0: Implement the missing GDA functions:
+  rotate, shift, trim, and, or, xor, invert,
+  max, min, maxmag, minmag, comparetotal, comparetotmag
+

data/lib/decimal/decimal.rb

@@ -109,7 +109,7 @@ class Decimal
     end
     def initialize(context=nil, *args)
       @value = args.first if args.size>0
-      super
+      super context
     end
   end
 
@@ -123,7 +123,7 @@ class Decimal
     end
     def initialize(context=nil, sign=nil, *args)
       @sign = sign
-      super
+      super context
     end
   end
 
@@ -203,7 +203,7 @@ class Decimal
     end
     def initialize(context=nil, sign=nil, *args)
       @sign = sign
-      super
+      super context
     end
   end
 
@@ -295,11 +295,15 @@ class Decimal
     # * :rounding : one of :half_even, :half_down, :half_up, :floor,
     #   :ceiling, :down, :up, :up05
     # * :precision : number of digits (or 0 for exact precision)
-    # * :exact : true or false (precision is ignored when true)
+    # * :exact : if true precision is ignored and Inexact conditions are trapped,
+    #            if :quiet it set exact precision but no trapping;
     # * :traps : a Flags object with the exceptions to be trapped
     # * :flags : a Flags object with the raised flags
     # * :ignored_flags : a Flags object with the exceptions to be ignored
-    # * :emin, :emax : minimum and maximum exponents
+    # * :emin, :emax : minimum and maximum adjusted exponents
+    # * :elimit : the exponent limits can also be defined by a single value;
+    #   if positive it is taken as emax and emin=1-emax; otherwiae it is
+    #   taken as emin and emax=1-emin. Such limits comply with IEEE 754-2008
     # * :capitals : (true or false) to use capitals in text representations
     # * :clamp : (true or false) enables clamping
     #
@@ -310,6 +314,9 @@ class Decimal
         base = options.shift
         copy_from base
       else
+        @rounding = @emin = @emax = nil
+        @capitals = false
+        @clamp = false
         @ignored_flags = Decimal::Flags()
         @traps = Decimal::Flags()
         @flags = Decimal::Flags()
@@ -346,16 +353,25 @@ class Decimal
       @ignored_flags.clear(*flags)
     end
 
-    # 'tiny' exponet (emin - precision + 1)
+    # 'tiny' exponent (emin - precision + 1)
+    # is the minimum valid value for the (integral) exponent
     def etiny
       emin - precision + 1
     end
 
-    # maximum exponent (emax - precision + 1)
+    # top exponent (emax - precision + 1)
+    # is the maximum valid value for the (integral) exponent
     def etop
       emax - precision + 1
     end
 
+    # Set the exponent limits, according to IEEE 754-2008
+    # if e > 0 it is taken as emax and emin=1-emax
+    # if e < 0  it is taken as emin and emax=1-emin
+    def elimit=(e)
+      @emin, @emax = [elimit, 1-elimit].sort
+    end
+
     # synonym for precision()
     def digits
       self.precision
@@ -420,6 +436,9 @@ class Decimal
         @traps = Decimal::Flags(options[:traps]) unless options[:traps].nil?
         @flags = Decimal::Flags(options[:flags]) unless options[:flags].nil?
         @ignored_flags = Decimal::Flags(options[:ignored_flags]) unless options[:ignored_flags].nil?
+        if elimit=options[:elimit]
+          @emin, @emax = [elimit, 1-elimit].sort
+        end
         @emin = options[:emin] unless options[:emin].nil?
         @emax = options[:emax] unless options[:emax].nil?
         @capitals = options[:capitals ] unless options[:capitals ].nil?
@@ -526,6 +545,12 @@ class Decimal
       _convert(x).reduce(self)
     end
 
+    # normalizes so that the coefficient has precision digits
+    # (this is not the old GDA normalize function)
+    def normalize(x)
+      _convert(x).reduce(self)
+    end
+
     # Adjusted exponent of x returned as a Decimal value.
     def logb(x)
       _convert(x).logb(self)
@@ -562,14 +587,14 @@ class Decimal
     # normalized to precision digits. (minimum exponent)
     def normalized_integral_exponent(x)
       x = _convert(x)
-      x.integral_exponent - (precision - x.number_of_digits)
+      x.exponent - (precision - x.number_of_digits)
     end
 
     # Significand normalized to precision digits
     # x == normalized_integral_significand(x) * radix**(normalized_integral_exponent)
     def normalized_integral_significand(x)
       x = _convert(x)
-      x.integral_significand*(Decimal.int_radix_power(precision - x.number_of_digits))
+      x.coefficient*(Decimal.int_radix_power(precision - x.number_of_digits))
     end
 
     # Returns both the (signed) normalized integral significand and the corresponding exponent
@@ -726,13 +751,87 @@ class Decimal
       _convert(x).next_toward(y, self)
     end
 
+    # ulp (unit in the last place) according to the definition proposed by J.M. Muller in
+    # "On the definition of ulp(x)" INRIA No. 5504
+    def ulp(x=nil)
+      x ||= 1
+      _convert(x).ulp(self)
+    end
+
+    # Some singular Decimal values that depend on the context
+
+    # Maximum finite number
+    def maximum_finite(sign=+1)
+      return exception(InvalidOperation, "Exact context maximum finite value") if exact?
+      # equals +Decimal(+1, 1, emax)
+      # equals Decimal.infinity.next_minus(self)
+      Decimal(sign, Decimal.int_radix_power(precision)-1, etop)
+    end
+
+    # Minimum positive normal number
+    def minimum_normal(sign=+1)
+      return exception(InvalidOperation, "Exact context maximum normal value") if exact?
+      Decimal(sign, 1, emin)
+    end
+
+    # Maximum subnormal number
+    def maximum_subnormal(sign=+1)
+      return exception(InvalidOperation, "Exact context maximum subnormal value") if exact?
+      # equals mininum_normal.next_minus(self)
+      Decimal(sign, Decimal.int_radix_power(precision-1)-1, etiny)
+    end
+
+    # Minimum nonzero positive number (minimum positive subnormal)
+    def minimum_nonzero(sign=+1)
+      return exception(InvalidOperation, "Exact context minimum nonzero value") if exact?
+      Decimal(sign, 1, etiny)
+    end
+
+    # This is the difference between 1 and the smallest Decimal
+    # value greater than 1: (Decimal(1).next_plus - Decimal(1))
+    def epsilon(sign=+1)
+      return exception(InvalidOperation, "Exact context epsilon") if exact?
+      Decimal(sign, 1, 1-precision)
+    end
+
+    # The strict epsilon is the smallest value that produces something different from 1
+    # wehen added to 1. It may be smaller than the general epsilon, because
+    # of the particular rounding rules used.
+    def strict_epsilon(sign=+1)
+      return exception(InvalidOperation, "Exact context strict epsilon") if exact?
+      coeff = 1
+      exp   = 1-precision
+      # assume radix is even (Decimal.radix%2 == 0)
+      case rounding
+      when :down, :floor
+        exp = 1-precision
+        coeff = 1
+      when :half_even, :half_down #, :up #  :up #     :down,    :half_down, :up05, :floor
+        exp = 1-2*precision
+        coeff = 1 + Decimal.int_radix_power(precision)/2
+      when :half_up
+        exp = 1-2*precision
+        coeff = Decimal.int_radix_power(precision)/2
+      when :up, :ceiling, :up05
+        return minimum_nonzero(sign)
+      end
+      return Decimal(sign, coeff, exp)
+    end
+
+    # This is the maximum relative error corresponding to 1/2 ulp:
+    #  (radix/2)*radix**(-precision) == epsilon/2
+    # This is called "machine epsilon" in Goldberg's "What Every Computer Scientist..."
+    def half_epsilon(sign=+1)
+      Decimal(sign, Decimal.radix/2, -precision)
+    end
+
     def to_s
       inspect
     end
 
     def inspect
       "<#{self.class}:\n" +
-      instance_variables.map { |v| "  #{v}: #{eval(v)}"}.join("\n") +
+      instance_variables.map { |v| "  #{v}: #{eval(v).inspect}"}.join("\n") +
       ">\n"
     end
 
@@ -809,10 +908,16 @@ class Decimal
     end
 
     def update_precision
+      if @emax && !@emin
+        @emin = 1 - @emax
+      elsif @emin && !@emax
+        @emax = 1 - @emin
+      end
       if @exact || @precision==0
+        quiet = (@exact == :quiet)
         @exact = true
         @precision = 0
-        @traps << Inexact
+        @traps << Inexact unless quiet
         @ignored_flags[Inexact] = false
       else
         @traps[Inexact] = false
@@ -1003,6 +1108,16 @@ class Decimal
   # * Given a precision p = 8, the normalized integral representation is 12040000 with exponent -9
   # * The normalized fractional representation is 0.1204 with exponent -1
   #
+  # ==Exponent limits
+  #
+  # The (integral) exponent e must be within this limits: etiny <= e <= etop
+  # The adjusted exponent a must: emin <= a <= emax
+  # emin, emax are the limite of the exponent shown in scientific notation and are use to defined
+  # the exponent limits in the contexts.
+  # etiny = emin-precision+1 and etop=emax-precision+1 are the limits of the internal exponent.
+  # Note that for significands with less than precision digits we can use exponents greater than etop
+  # without causing overflow: +Decimal(+1,1,emax) == Decimal(+1,K,etop) where K=10**(precision-1)
+  #
   # =Interoperatibility with other numeric types
   #
   # For some numeric types implicit conversion to Decimal is defined through these methods:
@@ -1044,14 +1159,26 @@ class Decimal
       arg.delete :exponent
       context ||= arg
     end
+    args = args.first if args.size==1 && args.first.is_a?(Array)
 
     context = Decimal.define_context(context)
 
     case args.size
     when 3
+      # internal representation
       @sign, @coeff, @exp = args
       # TO DO: validate
 
+    when 2
+      # signed integer and scale
+      @coeff, @exp = args
+      if @coeff < 0
+        @sign = -1
+        @coeff = -@coeff
+      else
+        @sign = +1
+      end
+
     when 1
       arg = args.first
       case arg
@@ -1108,19 +1235,17 @@ class Decimal
             @exp = :inf
           end
         end
-      when Array
-        @sign, @coeff, @exp = arg
       else
         raise TypeError, "invalid argument #{arg.inspect}"
       end
     else
-      raise ArgumentError, "wrong number of arguments (#{args.size} for 1 or 3)"
+      raise ArgumentError, "wrong number of arguments (#{args.size} for 1, 2 or 3)"
     end
   end
 
   # Returns the internal representation of the number, composed of:
   # * a sign which is +1 for plus and -1 for minus
-  # * a coefficient (significand) which is an integer
+  # * a coefficient (significand) which is a nonnegative integer
   # * an exponent (an integer) or :inf, :nan or :snan for special values
   # The value of non-special numbers is sign*coefficient*10^exponent
   def split
@@ -1289,7 +1414,7 @@ class Decimal
       return Decimal(other) if other.infinite?
     end
 
-    exp = [self.integral_exponent, other.integral_exponent].min
+    exp = [self.exponent, other.exponent].min
     negativezero = (context.rounding == ROUND_FLOOR && self.sign != other.sign)
 
     if self.zero? && other.zero?
@@ -1300,12 +1425,12 @@ class Decimal
     end
 
     if self.zero?
-      exp = [exp, other.integral_exponent - context.precision - 1].max unless context.exact?
+      exp = [exp, other.exponent - context.precision - 1].max unless context.exact?
       return other._rescale(exp, context.rounding)._fix(context)
     end
 
     if other.zero?
-      exp = [exp, self.integral_exponent - context.precision - 1].max unless context.exact?
+      exp = [exp, self.exponent - context.precision - 1].max unless context.exact?
       return self._rescale(exp, context.rounding)._fix(context)
     end
 
@@ -1313,8 +1438,8 @@ class Decimal
 
     result_sign = result_coeff = result_exp = nil
     if op1.sign != op2.sign
-      return ans = Decimal.new([negativezero ? -1 : +1, 0, exp])._fix(context) if op1.integral_significand == op2.integral_significand
-      op1,op2 = op2,op1 if op1.integral_significand < op2.integral_significand
+      return ans = Decimal.new([negativezero ? -1 : +1, 0, exp])._fix(context) if op1.coefficient == op2.coefficient
+      op1,op2 = op2,op1 if op1.coefficient < op2.coefficient
       result_sign = op1.sign
       op1,op2 = op1.copy_negate, op2.copy_negate if result_sign < 0
     elsif op1.sign < 0
@@ -1325,12 +1450,12 @@ class Decimal
     end
 
     if op2.sign == +1
-      result_coeff = op1.integral_significand + op2.integral_significand
+      result_coeff = op1.coefficient + op2.coefficient
     else
-      result_coeff = op1.integral_significand - op2.integral_significand
+      result_coeff = op1.coefficient - op2.coefficient
     end
 
-    result_exp = op1.integral_exponent
+    result_exp = op1.exponent
 
     return Decimal([result_sign, result_coeff, result_exp])._fix(context)
 
@@ -1369,13 +1494,13 @@ class Decimal
       end
     end
 
-    resultexp = self.integral_exponent + other.integral_exponent
+    resultexp = self.exponent + other.exponent
 
     return Decimal([resultsign, 0, resultexp])._fix(context) if self.zero? || other.zero?
-    #return Decimal([resultsign, other.integral_significand, resultexp])._fix(context) if self.integral_significand==1
-    #return Decimal([resultsign, self.integral_significand, resultexp])._fix(context) if other.integral_significand==1
+    #return Decimal([resultsign, other.coefficient, resultexp])._fix(context) if self.coefficient==1
+    #return Decimal([resultsign, self.coefficient, resultexp])._fix(context) if other.coefficient==1
 
-    return Decimal([resultsign, other.integral_significand*self.integral_significand, resultexp])._fix(context)
+    return Decimal([resultsign, other.coefficient*self.coefficient, resultexp])._fix(context)
 
   end
 
@@ -1403,22 +1528,22 @@ class Decimal
     end
 
     if self.zero?
-      exp = self.integral_exponent - other.integral_exponent
+      exp = self.exponent - other.exponent
       coeff = 0
     else
       prec = context.exact? ? self.number_of_digits + 4*other.number_of_digits : context.precision # this assumes radix==10
       shift = other.number_of_digits - self.number_of_digits + prec + 1
-      exp = self.integral_exponent - other.integral_exponent - shift
+      exp = self.exponent - other.exponent - shift
       if shift >= 0
-        coeff, remainder = (self.integral_significand*Decimal.int_radix_power(shift)).divmod(other.integral_significand)
+        coeff, remainder = (self.coefficient*Decimal.int_radix_power(shift)).divmod(other.coefficient)
       else
-        coeff, remainder = self.integral_significand.divmod(other.integral_significand*Decimal.int_radix_power(-shift))
+        coeff, remainder = self.coefficient.divmod(other.coefficient*Decimal.int_radix_power(-shift))
       end
       if remainder != 0
         return context.exception(Inexact) if context.exact?
         coeff += 1 if (coeff%(Decimal.radix/2)) == 0
       else
-        ideal_exp = self.integral_exponent - other.integral_exponent
+        ideal_exp = self.exponent - other.exponent
         while (exp < ideal_exp) && ((coeff % Decimal.radix)==0)
           coeff /= Decimal.radix
           exp += 1
@@ -1794,7 +1919,7 @@ class Decimal
       return Decimal.new(self)._fix(context)
     end
 
-    ideal_exp = [self.integral_exponent, other.integral_exponent].min
+    ideal_exp = [self.exponent, other.exponent].min
     if self.zero?
       return Decimal([self.sign, 0, ideal_exp])._fix(context)
     end
@@ -1806,9 +1931,9 @@ class Decimal
       return self._rescale(ideal_exp, context.rounding)._fix(context)
     end
 
-      self_coeff = self.integral_significand
-      other_coeff = other.integral_significand
-      de = self.integral_exponent - other.integral_exponent
+      self_coeff = self.coefficient
+      other_coeff = other.coefficient
+      de = self.exponent - other.exponent
       if de >= 0
         self_coeff = Decimal.int_mult_radix_power(self_coeff, de)
       else
@@ -1848,15 +1973,30 @@ class Decimal
 
     exp_max = context.clamp? ? context.etop : context.emax
     end_d = nd = dup.number_of_digits
-    exp = dup.integral_exponent
-    coeff = dup.integral_significand
+    exp = dup.exponent
+    coeff = dup.coefficient
     dgs = dup.digits
     while (dgs[end_d-1]==0) && (exp < exp_max)
       exp += 1
       end_d -= 1
     end
     return Decimal.new([dup.sign, coeff/Decimal.int_radix_power(nd-end_d), exp])
+  end
 
+  # normalizes so that the coefficient has precision digits
+  # (this is not the old GDA normalize function)
+  def normalize(context=nil)
+    context = Decimal.define_context(context)
+    return Decimal(self) if self.special? || self.zero?
+    return context.exception(InvalidOperation, "Normalize in exact context") if context.exact?
+    return context.exception(Subnormal, "Cannot normalize subnormal") if self.subnormal?
+    min_normal_coeff = Decimal.int_radix_power(context.precision-1)
+    sign, coeff, exp = self._fix(context).split
+    while coeff < min_normal_coeff
+      coeff *= Decimal.radix
+      exp -= 1
+    end
+    Decimal(sign, coeff, exp)
   end
 
   # Returns the exponent of the magnitude of the most significant digit.
@@ -1881,7 +2021,7 @@ class Decimal
     other = _convert(other)
     ans = _check_nans(context, other)
     return ans if ans
-    return context.exception(InvalidOperation) if other.infinite? || other.integral_exponent != 0
+    return context.exception(InvalidOperation) if other.infinite? || other.exponent != 0
     unless context.exact?
       liminf = -2 * (context.emax + context.precision)
       limsup =  2 * (context.emax + context.precision)
@@ -1996,10 +2136,50 @@ class Decimal
     end
   end
 
+  # ulp (unit in the last place) according to the definition proposed by J.M. Muller in
+  # "On the definition of ulp(x)" INRIA No. 5504
+  def ulp(context = nil)
+    context = Decimal.define_context(context)
+
+    return context.exception(InvalidOperation, "ulp in exact context") if context.exact?
+
+    if self.nan?
+      return Decimal(self)
+    elsif self.infinite?
+      # The ulp here is context.maximum_finite - context.maximum_finite.next_minus
+      return Decimal(+1, 1, context.etop)
+    elsif self.zero? || self.adjusted_exponent <= context.emin
+      # This is the ulp value for self.abs <= context.minimum_normal*Decimal.context
+      # Here we use it for self.abs < context.minimum_normal*Decimal.context;
+      #  because of the simple exponent check; the remaining cases are handled below.
+      return context.minimum_nonzero
+    else
+      # The next can compute the ulp value for the values that
+      #   self.abs > context.minimum_normal && self.abs <= context.maximum_finite
+      # The cases self.abs < context.minimum_normal*Decimal.context have been handled above.
+
+      # assert self.normal? && self.abs>context.minimum_nonzero
+      norm = self.normalize
+      exp = norm.integral_exponent
+      sig = norm.integral_significand
+
+      # Powers of the radix, r**n, are between areas with different ulp values: r**(n-p-1) and r**(n-p)
+      # (p is context.precision).
+      # This method and the ulp definitions by Muller, Kahan and Harrison assign the smaller ulp value
+      # to r**n; the definition by Goldberg assigns it to the larger ulp.
+      # The next line selects the smaller ulp for powers of the radix:
+      exp -= 1 if sig == Decimal.int_radix_power(context.precision-1)
+
+      return Decimal(+1, 1, exp)
+    end
+  end
+
   def inspect
-    #"Decimal('#{self}')"
-    #debug:
-    "Decimal('#{self}') [coeff:#{@coeff.inspect} exp:#{@exp.inspect} s:#{@sign.inspect}]"
+    if $DEBUG
+      "Decimal('#{self}') [coeff:#{@coeff.inspect} exp:#{@exp.inspect} s:#{@sign.inspect}]"
+    else
+      "Decimal('#{self}')"
+    end
   end
 
   # Internal comparison operator: returns -1 if the first number is less than the second,
@@ -2033,8 +2213,8 @@ class Decimal
           self_adjusted = self.adjusted_exponent
           other_adjusted = other.adjusted_exponent
           if self_adjusted == other_adjusted
-            self_padded,other_padded = self.integral_significand,other.integral_significand
-            d = self.integral_exponent - other.integral_exponent
+            self_padded,other_padded = self.coefficient,other.coefficient
+            d = self.exponent - other.exponent
             if d>0
               self_padded *= Decimal.int_radix_power(d)
             else
@@ -2115,12 +2295,12 @@ class Decimal
     @coeff.to_s.size
   end
 
-  # Significand as an integer, unsigned
+  # Significand as an integer, unsigned. Synonym of coefficient
   def integral_significand
     @coeff
   end
 
-  # Exponent of the significand as an integer
+  # Exponent of the significand as an integer. Synonym of exponent
   def integral_exponent
     # fractional_exponent - number_of_digits
     @exp
@@ -2131,7 +2311,17 @@ class Decimal
     @sign
   end
 
-  # Return the value of the number as an integer and a scale.
+  # Significand as an integer, unsigned
+  def coefficient
+    @coeff
+  end
+
+  # Exponent of the significand as an integer.
+  def exponent
+    @exp
+  end
+
+  # Return the value of the number as an signed integer and a scale.
   def to_int_scale
     if special?
       nil
@@ -2252,7 +2442,7 @@ class Decimal
         return context.exception(InvalidOperation, 'quantize with one INF')
       end
     end
-    exp = exp.integral_exponent
+    exp = exp.exponent
     _watched_rescale(exp, context, watch_exp)
   end
 
@@ -2267,7 +2457,7 @@ class Decimal
     if self.special? || other.special?
       return (self.nan? && other.nan?) || (self.infinite? && other.infinite?)
     end
-    return self.integral_exponent == other.integral_exponent
+    return self.exponent == other.exponent
   end
 
   # Rounds to a nearby integer. May raise Inexact or Rounded.
@@ -2392,7 +2582,7 @@ class Decimal
         product = Decimal.infinity(self.sign*other.sign)
       end
     else
-      product = Decimal.new([self.sign*other.sign,self.integral_significand*other.integral_significand, self.integral_exponent+other.integral_exponent])
+      product = Decimal.new([self.sign*other.sign,self.coefficient*other.coefficient, self.exponent+other.exponent])
     end
     return product.add(third, context)
   end
@@ -2486,7 +2676,7 @@ class Decimal
           multiplier = other.to_i
         end
 
-        exp = _self.integral_exponent * multiplier
+        exp = _self.exponent * multiplier
         if exp < 1-context.precision
           exp = 1-context.precision
           context.exception Rounded
@@ -2551,7 +2741,7 @@ class Decimal
       end
       ans = _self._power_exact(other, test_precision)
       if !ans.nil? && (result_sign == -1)
-        ans = Decimal(-1, ans.integral_significand, ans.integral_exponent)
+        ans = Decimal(-1, ans.coefficient, ans.exponent)
       end
     end
 
@@ -2562,10 +2752,10 @@ class Decimal
       return context.exception(Inexact, "Inexact power") if context.exact?
 
       p = context.precision
-      xc = _self.integral_significand
-      xe = _self.integral_exponent
-      yc = other.integral_significand
-      ye = other.integral_exponent
+      xc = _self.coefficient
+      xe = _self.exponent
+      yc = other.coefficient
+      ye = other.exponent
       yc = -yc if other.sign == -1
 
       # compute correctly rounded result:  start with precision +3,
@@ -2591,7 +2781,7 @@ class Decimal
       # pad with zeros up to length context.precision+1 if necessary
       if ans.number_of_digits <= context.precision
         expdiff = context.precision+1 - ans.number_of_digits
-        ans = Decimal(ans.sign, Decimal.int_mult_radix_power(ans.integral_significand, expdiff), ans.integral_exponent-expdiff)
+        ans = Decimal(ans.sign, Decimal.int_mult_radix_power(ans.coefficient, expdiff), ans.exponent-expdiff)
       end
       context.exception Underflow if ans.adjusted_exponent < context.emin
     end
@@ -2621,13 +2811,13 @@ class Decimal
     # log10(10**n) = n
     if digits.first == 1 && digits[1..-1].all?{|d| d==0}
       # answer may need rounding
-      ans = Decimal(self.integral_exponent + digits.size - 1)
+      ans = Decimal(self.exponent + digits.size - 1)
       return ans if context.exact?
     else
       # result is irrational, so necessarily inexact
       return context.exception(Inexact, "Inexact power") if context.exact?
-      c = self.integral_significand
-      e = self.integral_exponent
+      c = self.coefficient
+      e = self.exponent
       p = context.precision
 
       # correctly rounded result: repeatedly increase precision
@@ -2694,8 +2884,8 @@ class Decimal
       ans = Decimal(+1, Decimal.int_radix_power(p+1)-1, -p-1)
     else
       # general case
-      c = self.integral_significand
-      e = self.integral_exponent
+      c = self.coefficient
+      e = self.exponent
       c = -c if self.sign == -1
 
       # compute correctly rounded result: increase precision by
@@ -2744,8 +2934,8 @@ class Decimal
     # result is irrational, so necessarily inexact
     return context.exception(Inexact, 'Inexact exp') if context.exact?
 
-    c = self.integral_significand
-    e = self.integral_exponent
+    c = self.coefficient
+    e = self.exponent
     p = context.precision
 
     # correctly rounded result: repeatedly increase precision by 3
@@ -2798,9 +2988,9 @@ class Decimal
 
     return Decimal.new(self) if special?
     return Decimal.new([sign, 0, exp]) if zero?
-    return Decimal.new([sign, @coeff*Decimal.int_radix_power(self.integral_exponent - exp), exp]) if self.integral_exponent > exp
-    #nd = number_of_digits + self.integral_exponent - exp
-    nd = exp - self.integral_exponent
+    return Decimal.new([sign, @coeff*Decimal.int_radix_power(self.exponent - exp), exp]) if self.exponent > exp
+    #nd = number_of_digits + self.exponent - exp
+    nd = exp - self.exponent
     if number_of_digits < nd
       slf = Decimal.new([sign, 1, exp-1])
       nd = number_of_digits
@@ -2817,7 +3007,7 @@ class Decimal
   def _watched_rescale(exp, context, watch_exp)
     if !watch_exp
       ans = _rescale(exp, context.rounding)
-      context.exception(Rounded) if ans.integral_exponent > self.integral_exponent
+      context.exception(Rounded) if ans.exponent > self.exponent
       context.exception(Inexact) if ans != self
       return ans
     end
@@ -2835,7 +3025,7 @@ class Decimal
     ans = _rescale(exp, context.rounding)
     return context.exception(InvalidOperation,"exponent of rescale result too large for current context") if ans.adjusted_exponent > context.emax
     return context.exception(InvalidOperation,"rescale result has too many digits for current context") if (ans.number_of_digits > context.precision) && !context.exact?
-    if ans.integral_exponent > self.integral_exponent
+    if ans.exponent > self.exponent
       context.exception(Rounded)
       context.exception(Inexact) if ans!=self
     end
@@ -2941,7 +3131,7 @@ class Decimal
         d = Decimal.new(self)
       end
       changed = d._round(context.rounding, dg)
-      coeff = Decimal.int_div_radix_power(d.integral_significand, dg)
+      coeff = Decimal.int_div_radix_power(d.coefficient, dg)
       coeff += 1 if changed==1
       ans = Decimal.new([sign, coeff, exp_min])
       if changed!=0
@@ -2952,8 +3142,8 @@ class Decimal
             context.exception Clamped
           end
         elsif ans.number_of_digits == context.precision+1
-          if ans.integral_exponent< etop
-            ans = Decimal.new([ans.sign, Decimal.int_div_radix_power(ans.integral_significand,1), ans.integral_exponent+1])
+          if ans.exponent< etop
+            ans = Decimal.new([ans.sign, Decimal.int_div_radix_power(ans.coefficient,1), ans.exponent+1])
           else
             ans = context.exception(Overflow, 'above Emax', d.sign)
           end
@@ -2994,9 +3184,9 @@ class Decimal
     context = Decimal.define_context(context)
     sign = self.sign * other.sign
     if other.infinite?
-      ideal_exp = self.integral_exponent
+      ideal_exp = self.exponent
     else
-      ideal_exp = [self.integral_exponent, other.integral_exponent].min
+      ideal_exp = [self.exponent, other.exponent].min
     end
 
     expdiff = self.adjusted_exponent - other.adjusted_exponent
@@ -3004,9 +3194,9 @@ class Decimal
       return [Decimal.new([sign, 0, 0]), _rescale(ideal_exp, context.rounding)]
     end
     if (expdiff <= context.precision) || context.exact?
-      self_coeff = self.integral_significand
-      other_coeff = other.integral_significand
-      de = self.integral_exponent - other.integral_exponent
+      self_coeff = self.coefficient
+      other_coeff = other.coefficient
+      de = self.exponent - other.exponent
       if de >= 0
         self_coeff = Decimal.int_mult_radix_power(self_coeff, de)
       else
@@ -3027,9 +3217,9 @@ class Decimal
     context = Decimal.define_context(context)
     sign = self.sign * other.sign
     if other.infinite?
-      ideal_exp = self.integral_exponent
+      ideal_exp = self.exponent
     else
-      ideal_exp = [self.integral_exponent, other.integral_exponent].min
+      ideal_exp = [self.exponent, other.exponent].min
     end
 
     expdiff = self.adjusted_exponent - other.adjusted_exponent
@@ -3037,9 +3227,9 @@ class Decimal
       return [Decimal.new([sign, 0, 0]), _rescale(ideal_exp, context.rounding)]
     end
     if (expdiff <= context.precision) || context.exact?
-      self_coeff = self.integral_significand*self.sign
-      other_coeff = other.integral_significand*other.sign
-      de = self.integral_exponent - other.integral_exponent
+      self_coeff = self.coefficient*self.sign
+      other_coeff = other.coefficient*other.sign
+      de = self.exponent - other.exponent
       if de >= 0
         self_coeff = Decimal.int_mult_radix_power(self_coeff, de)
       else
@@ -3108,12 +3298,12 @@ class Decimal
     sign = other.even? ? +1 : -1
     modulo = modulo.to_i.abs
 
-    base = (self.integral_significand % modulo * (Decimal.int_radix_power(self.integral_exponent) % modulo)) % modulo
+    base = (self.coefficient % modulo * (Decimal.int_radix_power(self.exponent) % modulo)) % modulo
 
-    other.integral_exponent.times do
+    other.exponent.times do
       base = (base**Decimal.radix) % modulo
     end
-    base = (base**other.integral_significand) % modulo
+    base = (base**other.coefficient) % modulo
 
     Decimal(sign, base, 0)
   end
@@ -3127,8 +3317,8 @@ class Decimal
   # Assumes that elimination of special cases has already been
   # performed: self and other must both be nonspecial; self must
   # be positive and not numerically equal to 1; other must be
-  # nonzero.  For efficiency, other.integral_exponent should not be too large,
-  # so that 10**other.integral.exponent.abs is a feasible calculation.
+  # nonzero.  For efficiency, other.exponent should not be too large,
+  # so that 10**other.exponent.abs is a feasible calculation.
   def _power_exact(other, p)
 
     # In the comments below, we write x for the value of self and
@@ -3176,15 +3366,15 @@ class Decimal
     # Similarly, len(str(abs(yc)*xc_bits)) <= -ye implies |y|
     # < 1/nbits(xc).
 
-    xc = self.integral_significand
-    xe = self.integral_exponent
+    xc = self.coefficient
+    xe = self.exponent
     while (xc % Decimal.radix) == 0
       xc /= Decimal.radix
       xe += 1
     end
 
-    yc = other.integral_significand
-    ye = other.integral_exponent
+    yc = other.coefficient
+    ye = other.exponent
     while (yc % Decimal.radix) == 0
       yc /= Decimal.radix
       ye += 1
@@ -3202,7 +3392,7 @@ class Decimal
       exponent = -exponent if other.sign == -1
       # if other is a nonnegative integer, use ideal exponent
       if other.integral? and (other.sign == +1)
-        ideal_exponent = self.integral_exponent*other.to_i
+        ideal_exponent = self.exponent*other.to_i
         zeros = [exponent-ideal_exponent, p-1].min
       else
         zeros = 0
@@ -3320,7 +3510,7 @@ class Decimal
     # exponent, if necessary
     str_xc = xc.to_s
     if other.integral? && other.sign == +1
-      ideal_exponent = self.integral_exponent*other.to_i
+      ideal_exponent = self.exponent*other.to_i
       zeros = [xe-ideal_exponent, p-str_xc.length].min
     else
       zeros = 0
@@ -3448,12 +3638,12 @@ class Decimal
     # 1-1/x <= log(x) <= x-1. If x > 1 we have |log10(x)| >
     # (1-1/x)/2.31 > 0.  If x < 1 then |log10(x)| > (1-x)/2.31 > 0
 
-    adj = self.integral_exponent + number_of_digits - 1
+    adj = self.exponent + number_of_digits - 1
     return adj.to_s.length - 1 if adj >= 1 # self >= 10
     return (-1-adj).to_s.length-1 if adj <= -2 # self < 0.1
 
-    c = self.integral_significand
-    e = self.integral_exponent
+    c = self.coefficient
+    e = self.exponent
     if adj == 0
       # 1 < self < 10
       num = (c - Decimal.int_radix_power(-e)).to_s
@@ -3470,7 +3660,7 @@ class Decimal
   # that self is finite and positive and that self != 1.
   def _ln_exp_bound
     # for 0.1 <= x <= 10 we use the inequalities 1-1/x <= ln(x) <= x-1
-    adj = self.integral_exponent + number_of_digits - 1
+    adj = self.exponent + number_of_digits - 1
     if adj >= 1
       # argument >= 10; we use 23/10 = 2.3 as a lower bound for ln(10)
       return (adj*23/10).to_s.length - 1
@@ -3479,8 +3669,8 @@ class Decimal
       # argument <= 0.1
       return ((-1-adj)*23/10).to_s.length - 1
     end
-    c = self.integral_significand
-    e = self.integral_exponent
+    c = self.coefficient
+    e = self.exponent
     if adj == 0
       # 1 < self < 10
       num = (c-(10**-e)).to_s
@@ -3519,7 +3709,7 @@ class Decimal
 
     # Normalizes op1, op2 to have the same exp and length of coefficient. Used for addition.
     def _normalize(op1, op2, prec=0)
-      if op1.integral_exponent < op2.integral_exponent
+      if op1.exponent < op2.exponent
         swap = true
         tmp,other = op2,op1
       else
@@ -3528,13 +3718,13 @@ class Decimal
       end
       tmp_len = tmp.number_of_digits
       other_len = other.number_of_digits
-      exp = tmp.integral_exponent + [-1, tmp_len - prec - 2].min
-      if (other_len+other.integral_exponent-1 < exp) && prec>0
+      exp = tmp.exponent + [-1, tmp_len - prec - 2].min
+      if (other_len+other.exponent-1 < exp) && prec>0
         other = Decimal.new([other.sign, 1, exp])
       end
       tmp = Decimal.new(tmp.sign,
-                        Decimal.int_mult_radix_power(tmp.integral_significand, tmp.integral_exponent-other.integral_exponent),
-                        other.integral_exponent)
+                        Decimal.int_mult_radix_power(tmp.coefficient, tmp.exponent-other.exponent),
+                        other.exponent)
       return swap ? [other, tmp] : [tmp, other]
     end