numerals 0.0.0 → 0.1.0

data/lib/numerals/rounding.rb

@@ -1,229 +1,388 @@
-# Rounding of Numerals
-class Rounding
-
-  # Rounding is defined by the rounding mode and the precision,
-  # and is used to stablish the desired accuracy of a Numeral result.
-  #
-  # The rounding mode may be any of the valid Flt rounding modes
-  # (:half_even, :half_down, :half_up, :floor, :ceiling, :down, :up or :up05)
-  # or :exact for no rounding at all (to represent the situation where
-  # we want to get an exact numeral result.
-  #
-  # The precision may be defined either as a relative :precision value
-  # (number of significant digits of the result numeral) or as an :absolute
-  # :places that indicate the number of digits to the right of the fractional
-  # point. Negative values of :places will round to digits in integral positions.
-  #
-  # The base of the numerals to be rounded must also be defined (10 by default)
-  #
-  def initialize(*args)
-    if Hash === args.last
-      options = args.pop.dup
-    else
-      options = {}
-    end
-    args.each do |arg|
-      if Symbol === arg
-        options[:mode] = arg
-      elsif Integer === arg
-        options[:precision] = arg
-      else
-        raise "Invalid Rounding definition"
+module Numerals
+
+  # Rounding of Numerals
+  class Rounding < FormattingAspect
+
+    # Rounding defines a rounding mode and a precision,
+    # and is used to establish the desired accuracy of a Numeral result.
+    #
+    # Rounding also defines the base of the numerals to be rounded,
+    # which is 10 by default.
+    #
+    # The rounding mode is the rule used to limit
+    # the precision of a numeral; the rounding modes available are those
+    # of Flt::Num, namely:
+    #
+    # * :half_even
+    # * :half_up
+    # * :half_down
+    # * :ceiling
+    # * :floor
+    # * :up
+    # * :down
+    # * :up05
+    #
+    # Regarding the rounding precision there are two types of Roundings:
+    #
+    # * Fixed (limited) precision: the precision of the rounded result is either
+    #   defined as relative (number of significant digits defined by the
+    #   precision property) or absolute (number of fractional places
+    #   --decimals for base 10-- defined by the places property)
+    # * Free (unlimited) precision, which preserves the value of
+    #   the input numeral. As much precision as needed is used to keep
+    #   unambiguously the original value. When applied to exact input,
+    #   this kind of rounding doesn't perform any rounding.
+    #   For approximate input there are two variants:
+    #   - Preserving the original value precision, which produces and
+    #     approximate output. (All original digits are preserved;
+    #     full precision mode). This is the default free precision mode,
+    #     established by using the :free symbol for the precision
+    #     (or its synonym :preserve).
+    #   - Simplifiying or reducing the result to produce an exact output
+    #     without unneeded digits to restore the original value within its
+    #     original precision (e.g. traling zeros are not keep).
+    #     This case can be defined with the :short symbol for the precision
+    #     (or its synonum :simplify).
+    #
+    def initialize(*args)
+      DEFAULTS.each do |param, value|
+        instance_variable_set "@#{param}", value
       end
+      set! *args
     end
-    assign! options
-  end
 
-  attr_reader :mode, :base
+    DEFAULTS = {
+      mode: :half_even,
+      precision: :short,
+      places: nil,
+      base: 10
+    }
 
-  include ModalSupport::BracketConstructor
-  include ModalSupport::StateEquivalent
+    attr_reader :mode, :base
 
-  def [](options={})
-    assign! options
-  end
+    include ModalSupport::StateEquivalent
 
-  def assign!(options)
-    @mode      = options[:mode]      || @mode
-    @precision = options[:precision] || @precision
-    @places    = options[:places]    || @places
-    @base      = options[:base]      || @base
+    set do |*args|
+      options = extract_options(*args)
+      options.each do |option, value|
+        send :"#{option}=", value
+      end
+    end
 
-    if (@precision == 0 || @precision.nil?) && @places.nil?
-      @precision = 0
-      @mode = :exact
-    else
-      @mode ||= :half_even
+    def base=(v)
+      @base = v
     end
-    if @mode == :exact
-      @precision = 0
-      @places    = nil
+
+    def mode=(mode)
+      @mode = mode
     end
-    @base ||= 10
-    self
-  end
 
-  def parameters
-    if exact?
-      { mode: :exact }
-    elsif relative?
-      { mode: @mode, precision: @precision }
-    elsif absolute?
-      { mode: @mode, places: @places }
+    def precision=(v)
+      @precision = v
+      @precision = :simplify if v == 0
+      @places = nil if @precision
     end
-  end
 
-  def to_s
-    if exact?
-      "Rounding[:exact]"
-    elsif relative?
-      "Rounding[#{@mode.inspect}, precision: #{@precision}]"
-    elsif absolute?
-      "Rounding[#{@mode.inspect}, places: #{@places}]"
+    def places=(v)
+      @places = v
+      @precision = nil if @places
     end
-  end
 
-  def inspect
-    to_s
-  end
+    def parameters
+      if @precision
+        { mode: @mode, precision: @precision, base: @base }
+      else
+        { mode: @mode, places: @places, base: @base }
+      end
+    end
 
-  def exact?
-    @mode == :exact
-  end
+    def to_s
+      params = parameters
+      DEFAULTS.each do |param, default|
+        params.delete param if params[param] == default
+      end
+      "Rounding[#{params.inspect.unwrap('{}')}]"
+    end
 
-  def absolute?
-    !exact? && !@precision
-  end
+    def inspect
+      to_s
+    end
 
-  def relative?
-    !exact? && !absolute?
-  end
+    # Returns true if the Rounding is of free (unlimited) precision,
+    # which can be either :free (preserving) or :short (simplifying)
+    # regarding approximate input.
+    def free? # unlimited? exact? all? nonrounding? free?
+      [:free, :short].include?(@precision)
+    end
 
-  # Number of significant digits for a given numerical/numeral value
-  def precision(value)
-    if relative? || exact?
-      @precision
-    else
-      @places + num_integral_digits(value)
+    # Returns true if the Rounding is of fixed (limited) precision.
+    def fixed? # limited? approximate? rounding? fixed?
+      !free?
     end
-  end
 
-  # Number of fractional placesfor a given numerical/numeral value
-  def places(value)
-    if absolute? || exact?
-      @places
-    else
-      @precision - num_integral_digits(value)
+    # Returns true if the Rounding is of fixed precision defined
+    # as a number of fractional places, i.e. independently of the
+    # number to be rounded's magnitude.
+    def absolute?
+      @precision.nil? # fixed? && @precision # !@places.nil?
     end
-  end
 
-  # Round a numeral. If the numeral has been truncated
-  # the :round_up option must be used to pass the information
-  # about the discarded digits:
-  # * nil if all discarded digits where 0 (the truncated value is exact)
-  # * :lo if there where non-zero discarded digits, but the first discarded digit
-  #   is below half the base.
-  # * :tie if the first discarded was half the base and there where no more nonzero digits,
-  #   i.e. the original value was a 'tie', exactly halfway between the truncated value
-  #   and the next value with the same number of digits.
-  # * :hi if the original value was above the tie value.
-  def round(numeral, options={})
-    round_up = options[:round_up]
-    numeral, round_up = truncate(numeral, round_up)
-    adjust(numeral, round_up)
-  end
+    # Returns true if the Rounding is of fixed precision defined
+    # as a number of significant digits (precision attribute),
+    # i.e. in relation to the number to be rounded's magnitude.
+    def relative?
+      fixed? && !absolute?
+    end
 
-  private
+    # Returns true if the Rounding is of free precision and
+    # the behaviour for approximate numbers is producing a
+    # simplified (short) result with only the needed digits
+    # to restore the original value within its precision.
+    def simplifying?
+      @precision == :short
+    end
 
-  def check_base(numeral)
-    if numeral.base != @base
-      raise "Invalid Numeral (base #{numeral.base}) for a base #{@base} Rounding"
+    def short?
+      simplifying?
+    end
+
+    # Returns true if the Rounding is of free precision and
+    # the behaviour for approximate numbers is to keep its
+    # original precision (so it may include trailing zeros)
+    # and the result of rounding will be an approximate numeral.
+    def preserving?
+      @precision == :free
+    end
+
+    def full?
+      preserving?
     end
-  end
 
-  # Truncate a numeral and return also a round_up value with information about
-  # the digits beyond the truncation point that can be used to round the truncated
-  # numeral. If the numeral has already been truncated, the round_up result of
-  # that truncation should be passed as the second argument.
-  def truncate(numeral, round_up=nil)
-    check_base numeral
-    if exact?
-      round_up = nil
-    else
-      n = precision(numeral)
-      unless n==numeral.digits.size && numeral.approximate?
-        if n < numeral.digits.size - 1
-          rest_digits = numeral.digits[n+1..-1]
+    # Number of significant digits for a given numerical/numeral value.
+    # If no value is passed, the :precision property is returned.
+    def precision(value = nil, options = {})
+      if value.nil?
+        @precision
+      elsif free?
+        if is_exact?(value, options)
+          0
         else
-          rest_digits = []
+          num_digits(value, options)
         end
-        if numeral.repeating? && numeral.repeat < numeral.digits.size && n >= numeral.repeat
-          rest_digits += numeral.digits[numeral.repeat..-1]
+      else # fixed?
+        if absolute?
+          @places + num_integral_digits(value)
+        else # relative?
+          @precision
         end
-        digits = numeral.digits[0, n]
-        if digits.size < n
-          digits += (digits.size...n).map{|i| numeral.digit_value_at(i)}
+      end
+    end
+
+    # Number of fractional places for a given numerical/numeral value
+    # If no value is passed, the :places property is returned.
+    def places(value = nil, options = {})
+      if value.nil?
+        @places
+      elsif is_exact?(value, options)
+        @places || 0
+      elsif free?
+        num_digits(value, options) - num_integral_digits(value)
+      else # fixed?
+        if absolute?
+          @places
+        else # relative?
+          @precision - num_integral_digits(value)
         end
-        if numeral.base % 2 == 0
-          tie_digit = numeral.base / 2
-          max_lo = tie_digit - 1
-        else
-          max_lo = numeral.base / 2
+      end
+    end
+
+    # Round a numeral. If the numeral has been truncated
+    # the :round_up option must be used to pass the information
+    # about the discarded digits:
+    # * nil if all discarded digits where 0 (the truncated value is exact)
+    # * :lo if there where non-zero discarded digits, but the first discarded digit
+    #   is below half the base.
+    # * :tie if the first discarded was half the base and there where no more nonzero digits,
+    #   i.e. the original value was a 'tie', exactly halfway between the truncated value
+    #   and the next value with the same number of digits.
+    # * :hi if the original value was above the tie value.
+    def round(numeral, options={})
+      round_up = options[:round_up]
+      numeral, round_up = truncate(numeral, round_up)
+      if numeral.exact?
+        numeral
+      else
+        adjust(numeral, round_up)
+      end
+    end
+
+    # Note: since Rounding has no mutable attributes, default dup is OK
+    # otherwise we'd need to redefine it:
+    # def dup
+    #   Rounding[parameters]
+    # end
+
+    private
+
+    def check_base(numeral)
+      if numeral.base != @base
+        raise "Invalid Numeral (base #{numeral.base}) for a base #{@base} Rounding"
+      end
+    end
+
+    # Truncate a numeral and return also a round_up value with information about
+    # the digits beyond the truncation point that can be used to round the truncated
+    # numeral. If the numeral has already been truncated, the round_up result of
+    # that prior truncation should be passed as the second argument.
+
+
+    def truncate(numeral, round_up=nil)
+      check_base numeral
+      unless simplifying? # TODO: could simplify this just skiping on free?
+        n = precision(numeral)
+        if n == 0
+          return numeral if numeral.repeating? # or rails inexact...
+          n = numeral.digits.size
         end
-        next_digit = numeral.digit_value_at(n)
-        if next_digit == 0
-          unless round_up.nil? && rest_digits.all?{|d| d == 0}
-            round_up = :lo
+        unless n >= numeral.digits.size && numeral.approximate?
+          if n < numeral.digits.size - 1
+            rest_digits = numeral.digits[n+1..-1]
+          else
+            rest_digits = []
           end
-        elsif next_digit <= max_lo # next_digit < tie_digit
-          round_up = :lo
-        elsif next_digit == tie_digit
-          if round_up || rest_digits.any?{|d| d != 0}
-            round_up = :hi
+          if numeral.repeating? && numeral.repeat < numeral.digits.size && n >= numeral.repeat
+            rest_digits += numeral.digits[numeral.repeat..-1]
+          end
+          digits = numeral.digits[0, n]
+          if digits.size < n
+            digits += (digits.size...n).map{|i| numeral.digit_value_at(i)}
+          end
+          if numeral.base % 2 == 0
+            tie_digit = numeral.base / 2
+            max_lo = tie_digit - 1
           else
-            round_up = :tie
+            max_lo = numeral.base / 2
+          end
+          next_digit = numeral.digit_value_at(n)
+          if next_digit == 0
+            unless round_up.nil? && rest_digits.all?{|d| d == 0}
+              round_up = :lo
+            end
+          elsif next_digit <= max_lo # next_digit < tie_digit
+            round_up = :lo
+          elsif next_digit == tie_digit
+            if round_up || rest_digits.any?{|d| d != 0}
+              round_up = :hi
+            else
+              round_up = :tie
+            end
+          else # next_digit > tie_digit
+            round_up = :hi
           end
-        else # next_digit > tie_digit
-          round_up = :hi
+          numeral = Numeral[
+                      digits, point: numeral.point, sign: numeral.sign,
+                      base: numeral.base,
+                      normalize: :approximate
+                    ]
         end
-        numeral = Numeral[digits, point: numeral.point, sign: numeral.sign, normalize: :approximate]
       end
+      [numeral, round_up]
     end
-    [numeral, round_up]
-  end
 
-  # Adjust a truncated numeral using the round-up information
-  def adjust(numeral, round_up)
-    check_base numeral
-    point, digits = Flt::Support.adjust_digits(
-      numeral.point, numeral.digits.digits_array,
-      round_mode: @mode,
-      negative: numeral.sign == -1,
-      round_up: round_up,
-      base: numeral.base
-    )
-    Numeral[digits, point: point, base: numeral.base, sign: numeral.sign, normalize: :approximate]
-  end
+    # Adjust a truncated numeral using the round-up information
+    def adjust(numeral, round_up)
+      check_base numeral
+      point, digits = Flt::Support.adjust_digits(
+        numeral.point, numeral.digits.digits_array,
+        round_mode: @mode,
+        negative: numeral.sign == -1,
+        round_up: round_up,
+        base: numeral.base
+      )
+      if numeral.zero? && simplifying?
+        digits = []
+        point = 0
+      end
+      normalization = simplifying? ? :exact : :approximate
+      Numeral[digits, point: point, base: numeral.base, sign: numeral.sign, normalize: normalization]
+    end
 
-  ZERO_DIGITS = 0 # 1?
+    ZERO_DIGITS = 0 # 1?
 
-  # Number of digits in the integer part of the value (excluding leading zeros).
-  def num_integral_digits(value)
-    case value
-    when 0
-      ZERO_DIGITS
-    when Numeral
-      if value.zero?
+    # Number of digits in the integer part of the value (excluding leading zeros).
+    def num_integral_digits(value)
+      case value
+      when 0
         ZERO_DIGITS
+      when Numeral
+        if value.zero?
+          ZERO_DIGITS
+        else
+          if @base != value.base
+            value = value.to_base(@base)
+          end
+          value.normalized(remove_trailing_zeros: true).point
+        end
       else
-        if @base != value.base
-          value = value.to_base(@base)
+        Conversions.order_of_magnitude(value, base: @base)
+      end
+    end
+
+    def num_digits(value, options)
+      case value
+      when 0
+        ZERO_DIGITS
+      when Numeral
+        if value.zero?
+          ZERO_DIGITS
+        else
+          if @base != value.base
+            value = value.to_base(@base)
+          end
+          if value.repeating?
+            0
+          else
+            value.digits.size
+          end
         end
-        value.normalized(remove_trailing_zeros: true).point
+      else
+        Conversions.number_of_digits(value, options.merge(base: @base))
       end
-    else
-      Conversions.order_of_magnitude(value, base: @base)
     end
+
+    def is_exact?(value, options={})
+      case value
+      when Numeral
+        value.exact?
+      else
+        Conversions.exact?(value, options)
+      end
+    end
+
+    def extract_options(*args)
+      options = {}
+      args = args.first if args.size == 1 && args.first.kind_of?(Array)
+      args.each do |arg|
+        case arg
+        when Hash
+          options.merge! arg
+        when :short, :simplify
+          options.merge! precision: :short
+        when :free, :preserve
+          options.merge! precision: :free
+        when Symbol
+          options[:mode] = arg
+        when Integer
+          options[:precision] = arg
+        when Rounding
+          options.merge! arg.parameters
+        else
+          raise "Invalid Rounding definition"
+        end
+      end
+      options
+    end
+
   end
 
 end

data/lib/numerals/version.rb

@@ -1,3 +1,3 @@
 module Numerals
-  VERSION = "0.0.0"
+  VERSION = "0.1.0"
 end

data/lib/numerals.rb

@@ -2,11 +2,13 @@ require 'modalsupport'
 
 require "numerals/version"
 require 'numerals/numeral'
+require 'numerals/formatting_aspect'
 require 'numerals/rounding'
+require 'numerals/repeat_detector'
 require 'numerals/conversions/float'
 require 'numerals/conversions/integer'
 require 'numerals/conversions/rational'
 require 'numerals/conversions/bigdecimal'
 require 'numerals/conversions/flt'
-require 'numerals/formatting/digits_definition'
-require 'numerals/formatting/options'
+require 'numerals/format'
+# require 'numerals/formatting/options'

data/numerals.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency 'flt', "~> 1.3.4"
+  spec.add_dependency 'flt', "~> 1.4.6"
   spec.add_dependency 'modalsupport', "~> 0.9.2"
 
   spec.add_development_dependency "bundler", "~> 1.6"