numerals 0.0.0 → 0.1.0

data/lib/numerals/conversions.rb

@@ -1,48 +1,89 @@
 module Numerals::Conversions
 
   class <<self
-    def [](type)
+    def [](type, options = nil)
       if type.respond_to?(:numerals_conversion)
-        type.numerals_conversion
+        type.numerals_conversion(options || {})
       end
     end
 
     def order_of_magnitude(number, options={})
-      self[number.class].order_of_magnitude(number, options)
+      self[number.class, options[:type_options]].order_of_magnitude(number, options)
     end
 
-    # explicit: number_to_numeral x, mode, rounding
-    # but for :free mode rounding is ignored except for the base
-    # so if no rounding/rounding options are passed except for the base, the default mode should be :free
-    # otherwise, the default mode should be :fixed...
-
-    # number_to_numeral(x, precision: 3) = number_to_numeral(x, :fixed, Rounding[precision: 3])
-    # number_to_numeral(x, precision: 3, base: 2) = number_to_numeral(x, :fixed, Rounding[precision: 3, base: 2])
-    # number_to_numeral(x, :exact, base: 2) = number_to_numeral(x, :free, Rounding[:exact, base: 2])
-
-    # Two ways of defining the conversion mode:
-    # 1. fixed or free:
-    # * :fixed means: adjust the number precision to the output rounding
-    # * :free means: forget about the rounding, preserve the input number precision
-    # But :free cheats: if rounding is not exact it really honors it by
-    # converting the number to an exact numeral an then rounding it.
-    # 2. exact or approximate
-    # * :exact means: consider the number an exact quantity
-    # * :approximate means: consider the number approximate; show only non-spurious digits.
-    def number_to_numeral(number, *args)
-      mode = extract_mode_from_args!(args)
-      rounding = Rounding[*args]
-      # mode ||= rounding.exact? ? :free : :fixed
-      mode ||= :approximate
-      if [:fixed, :free].include?(mode)
-        mode = (mode == :fixed) == (rounding.exact?) ? :exact : :approximate
-      end
-      self[number.class].number_to_numeral(number, mode, rounding)
+    def number_of_digits(number, options={})
+      self[number.class, options[:type_options]].number_of_digits(number, options)
+    end
+
+    # Convert Numeral to Number
+    #
+    #   read numeral, options={}
+    #
+    # If the input numeral is approximate and the destination type
+    # allows for arbitrary precision, then the destination context
+    # precision will be ignored and the precision of the input will be
+    # preserved. The :simplify option affects this case by generating
+    # only the mininimun number of digits needed.
+    #
+    # The :exact option will prevent this behaviour and always treat
+    # input as exact.
+    #
+    # Valid output options:
+    #
+    # * :type class of the output number
+    # * :context context (in the case of Flt::Num, Float) for the output
+    # * :simplify (for approximate input numeral/arbitrary precision type only)
+    # * :exact treat input numeral as if exact
+    #
+    def read(numeral, options={})
+      selector = options[:context] || options[:type]
+      exact_input = options[:exact]
+      approximate_simplified = options[:simplify]
+      conversions = self[selector, options[:type_options]]
+      conversions.read(numeral, exact_input, approximate_simplified)
+    end
+
+    # Convert Number to Numeral
+    #
+    #   write number, options={}
+    #
+    # Valid options:
+    #
+    # * :rounding (a Rounding) (which defines output base as well)
+    # * :exact (exact input indicator)
+    #
+    # Approximate mode:
+    #
+    # If the input is treated as an approximation
+    # (which is the case for types such as Flt::Num, Float,...
+    # unless the :exact option is true) then no 'spurious' digits
+    # will be shown (digits that can take any value and the numeral
+    # still would convert to the original number if rounded to the same precision)
+    #
+    # In approximate mode, if rounding is simplifying? (:short), the shortest representation
+    # which rounds back to the origina number with the same precision is used.
+    # If rounding is :free and the output base is the same as the number
+    # internal radix, the exact precision (trailing zeros) of the number
+    # is represented.
+    #
+    # Exact mode:
+    #
+    # Is used for 'exact' types (such as Integer, Rational) or when the :exact
+    # option is defined to be true.
+    #
+    # The number is treated as an exact value, and converted according to
+    # Rounding. (in this case the :free and :short precision roundings are
+    # equivalent)
+    #
+    def write(number, options = {})
+      output_rounding = Rounding[options[:rounding] || Rounding[]]
+      conversion = self[number.class, options[:type_options]]
+      exact_input = conversion.exact?(number, options)
+      conversion.write(number, exact_input, output_rounding)
     end
 
-    def numeral_to_number(numeral, type, *args)
-      mode = extract_mode_from_args!(args) || :fixed
-      self[type].numeral_to_number(numeral, mode, *args)
+    def exact?(number, options = {})
+      self[number.class, options[:type_options]].exact?(number, options)
     end
 
     private

data/lib/numerals/digits.rb

@@ -2,8 +2,8 @@ require 'forwardable'
 
 module Numerals
 
-  # Sequence of digit values type, with an Array-compatible interface
-  # Having this encapsulated here allow to change the implementation
+  # Sequence of digit values, with an Array-compatible interface.
+  # Having this encapsulated here allows changing the implementation
   # e.g. to an Integer or packed in a String, ...
   class Digits
     def initialize(*args)
@@ -32,7 +32,7 @@ module Numerals
                    :size, :map, :pop, :push, :shift, :unshift,
                    :empty?, :first, :last, :any?, :all?, :[]=
 
-    # The [] with a Range argument or two arguments (index, length)
+    # The [] operator with a Range argument or two arguments (index, length)
     # returns a Regular Array.
     def_delegators :@digits_array, :[], :replace
     include ModalSupport::StateEquivalent # maybe == with Arrays too?
@@ -68,7 +68,7 @@ module Numerals
 
     def zero?
       # value == 0
-      @digits && @digits.all?{|d| d==0 }
+      !@digits_array || @digits_array.empty? || @digits_array.all?{|d| d==0 }
     end
 
     # Deep copy
@@ -93,7 +93,10 @@ module Numerals
     def truncate!(n)
       @digits_array.slice! n..-1
     end
+
+    def valid?
+      @digits_array.none? { |x| !x.kind_of?(Integer) || x < 0 || x >= @radix }
+    end
   end
 
 end
-

data/lib/numerals/format/base_scaler.rb

@@ -0,0 +1,160 @@
+require 'forwardable'
+
+module Numerals
+
+  # This converts the number representation contained in an ExpSetter
+  # scaling the base of the significand.
+  #
+  # This is typically used when the ExpSetter base is 2 to render the number
+  # in C99 '%A' format, i.e., in hexadecimal base. Only the significand is
+  # shown in base 16; the exponent is still a power of two, and represented
+  # in base 10.
+  #
+  # This is a generalization of the %A format where any base which is a
+  # power of the original base can be used for the significand.
+  #
+  # The number exponent is previously adjusted in the ExpSetter and that
+  # doesn't change, only the significand parts are converted from the
+  # original base `base` to the new base `base**base_scale`.
+  #
+  # This will require adjusting the repeating digits position and length,
+  # and adding leading 0s (in the original base) to the signficant
+  # and/or trailing digits may be required.
+  #
+  class Format::BaseScaler
+
+    def initialize(exp_setter, base_scale)
+      @setter = exp_setter
+      @numeral = @setter.numeral
+      @base_scale = base_scale
+      @scaled_base = @setter.base**@base_scale
+      adjust
+    end
+
+    include ModalSupport::BracketConstructor
+
+    attr_reader :base_scale, :scaled_base, :numeral
+
+    extend Forwardable
+    def_delegators :@setter,
+                   :exponent_base, :exponent, :special?, :special,
+                   :repeating?, :sign
+
+    def base
+      scaled_base
+    end
+
+    def fractional_part
+      ungrouped = @setter.fractional_part + (0...@scaling_trailing_size).map{|i| repeat_digit(i)}
+      grouped_digits ungrouped
+    end
+
+    def fractional_part_size
+      (@setter.fractional_part_size + @scaling_trailing_size)/@base_scale
+    end
+
+    def fractional_insignificant_size
+      if @setter.numeral.approximate?
+        (@setter.fractional_insignificant_size + @scaling_trailing_size)/@base_scale
+      else
+        0
+      end
+    end
+
+    def integer_part
+      ungrouped = [0]*@scaling_leading_size + @setter.integer_part
+      grouped_digits ungrouped
+    end
+
+    def integer_part_size
+      (@setter.integer_part_size + @scaling_leading_size)/@base_scale
+    end
+
+    def integer_insignificant_size
+      if @setter.numeral.approximate?
+        (@setter.integer_insignificant_size + @scaling_leading_size)/@base_scale
+      else
+        0
+      end
+    end
+
+    def repeat_size_size
+      @repeat_length/@base_scale
+    end
+
+    def repeat_insignificant_size
+      0
+    end
+
+    def repeat_part
+      ungrouped = (@scaling_trailing_size...@scaling_trailing_size+@repeat_length).map{|i| repeat_digit(i)}
+      grouped_digits ungrouped
+    end
+
+    private
+
+    # Return the `scaled_base` digit corresponding to a group of `base_scale` `exponent_base` digits
+    def scaled_digit(group)
+      unless group.size == @base_scale
+        raise "Invalid digits group size for scaled_digit (is #{group.size}; should be #{@base_scale})"
+      end
+      v = 0
+      group.each do |digit|
+        v *= @setter.base
+        v += digit
+      end
+      v
+    end
+
+    # Convert base `exponent_base` digits to base `scaled_base` digits
+    # the number of digits must be a multiple of base_scale
+    def grouped_digits(digits)
+      unless (digits.size % @base_scale) == 0
+        raise "Invalid number of digits for group_digits (#{digits.size} is not a multiple of #{@base_scale})"
+      end
+      digits.each_slice(@base_scale).map{|group| scaled_digit(group)}
+    end
+
+    # Number of digits (base `exponent_base`) to be added to make the number
+    # of digits a multiple of `base_scale`.
+    def padding_size(digits_size)
+      (@base_scale - digits_size) % @base_scale
+    end
+
+    def adjust
+      return if special?
+      @setter_repeat_part = @setter.repeat_part
+      @setter_repeat_part_size = @setter.repeat_part_size
+
+      @scaling_trailing_size =  padding_size(@setter.fractional_part_size)
+      @scaling_leading_size = padding_size(@setter.integer_part_size)
+
+      @repeat_length = @setter.repeat_part_size
+      while (@repeat_length % @base_scale) != 0
+        @repeat_length += @setter.repeat_part_size
+      end
+    end
+
+    def repeat_digit(i)
+      if @setter_repeat_part_size > 0
+        @setter_repeat_part[i % @setter_repeat_part_size]
+      else
+        0
+      end
+    end
+
+    # Convert base digits to scaled base digits
+    def self.ugrouped_digits(digits, base, base_scale)
+      digits.flat_map { |d|
+        group = Numeral::Digits[base: base]
+        group.value = d
+        ungrouped = group.digits_array
+        if ungrouped.size < base_scale
+          ungrouped = [0]*(base_scale - ungrouped.size) + ungrouped
+        end
+        ungrouped
+      }
+    end
+  end
+
+end

data/lib/numerals/format/exp_setter.rb

@@ -0,0 +1,218 @@
+module Numerals
+
+  # Adjust exponent to be used in a Numeral expression;
+  # break up the numeral into integer, fractional and repeating parts.
+  #
+  #   setter = ExpSetter[numeral]
+  #   # To use 'fixed' format:
+  #   setter.exponent = 0
+  #   # To use scientific notation:
+  #   setter.integer_part_size = 1
+  #   # To adjust scientific notation to engineering mode:
+  #   setter.integer_part_size += 1 (while setter.exponent % 3) != 0
+  #   # To automatically choose between fixed/scientific format:
+  #   setter.exponent = 0 # fixed
+  #   if setter.leading_size > 6 || setter.trailing_size > 0
+  #     setter.integer_part_size = 1 # scientific
+  #   end
+  #
+  #   # To access the numeric parts for formatting:
+  #   setter.sign
+  #   setter.integer_part # digits before radix point
+  #   setter.fractional_part # digits after radix point, before repetition
+  #   setter.repeating_part  # repeated digits
+  #   setter.base            # base for exponent
+  #   setter.exponent        # exponent
+  #
+  class Format::ExpSetter
+
+    def initialize(numeral, options={})
+      @insignificant_digits = options[:insignificant_digits] || 0
+      @numeral = numeral
+      @integer_part_size = @numeral.point
+      @digits = @numeral.digits
+      @exponent = 0
+      @repeat_size = @numeral.repeating? ? @digits.size - @numeral.repeat : 0
+      adjust
+    end
+
+    attr_reader :numeral
+
+    include ModalSupport::BracketConstructor
+    attr_reader :integer_part_size, :exponent
+    attr_reader :trailing_size, :leading_size
+
+    def base
+      @numeral.base
+    end
+
+    def exponent_base
+      base
+    end
+
+    def special?
+      @numeral.special?
+    end
+
+    def special
+      @numeral.special
+    end
+
+    def repeating?
+      @numeral.repeating?
+    end
+
+    def sign
+      @numeral.sign
+    end
+
+    def exponent=(v)
+      if @exponent != v
+        @integer_part_size -= (v - @exponent)
+        @exponent = v
+        adjust
+      end
+    end
+
+    def integer_part_size=(v)
+      if @integer_part_size != v
+        @exponent -= (v - @integer_part_size)
+        @integer_part_size = v
+        adjust
+      end
+    end
+
+    def repeat_part
+      if @numeral.repeating?
+        if @repeat_phase != 0 || @numeral.repeat < 0
+          start = @numeral.repeat + @repeat_phase
+          (start...start+repeat_part_size).map{|i| @numeral.digit_value_at(i)}
+        else
+          @digits[@numeral.repeat..-1]
+        end
+      else
+        []
+      end
+    end
+
+    def repeat_part_size
+      if @numeral.repeating?
+        @digits.size - @numeral.repeat
+      else
+        0
+      end
+    end
+
+    def fractional_part
+      leading + @digits[@fractional_start...@fractional_end]
+    end
+
+    def integer_part
+      @digits[@integer_start...@integer_end] + trailing
+    end
+
+    def fractional_part_size
+      @fractional_end - @fractional_start + @leading_size
+    end
+
+    attr_reader :integer_insignificant_size, :fractional_insignificant_size
+
+    def repeat_insignificant_size
+      0
+    end
+
+    private
+
+    def trailing
+      if @trailing_size > 0
+        (@digits.size...@digits.size+@trailing_size).map{|i| @numeral.digit_value_at(i)}
+      else
+        []
+      end
+    end
+
+    def leading
+      n = @leading_size
+      if @fractional_end < @fractional_start
+        n += @fractional_end - @fractional_start
+      end
+      if n > 0
+        [0]*n
+      else
+        []
+      end
+    end
+
+    def adjust
+      raise "Inconsistet number of insignficant digits" if @numeral.repeating? && @insignificant_digits > 0
+      if special?
+        @leading_size = @trailing_size = 0
+        @integer_start = @integer_end = 0
+        @fractional_start = @fractional_end = 0
+        @repeat_phase = 0
+        @integer_insignificant_size = @fractional_insignificant_size = 0
+      elsif @integer_part_size <= 0
+        @trailing_size = 0
+        # integer_part == []
+        @integer_start = @integer_end = @digits.size
+        @integer_insignificant_size = 0
+        if !@numeral.repeating? || @numeral.repeat >= 0 || @integer_part_size >= @numeral.repeat
+          @leading_size = -@integer_part_size
+          @fractional_start = 0
+          if @numeral.repeat
+            if @numeral.repeat >= 0
+              @fractional_end  = @numeral.repeat
+            else
+              @fractional_end = @digits.size
+            end
+            @fractional_insignificant_size = 0
+          else
+            @fractional_end = @digits.size
+            @fractional_insignificant_size = [@insignificant_digits, @digits.size].min
+          end
+          @repeat_phase = 0
+        else
+          @leading_size = @numeral.repeat - @integer_part_size
+          @trailing_size = 0
+          @fractional_start = @fractional_end = @digits.size
+          @fractional_insignificant_size = 0
+          @repeat_phase = 0
+        end
+      elsif @integer_part_size >= @digits.size
+        @trailing_size = @integer_part_size - @digits.size
+        @leading_size = 0
+        @integer_start = 0
+        @integer_end = @digits.size
+        @integer_insignificant_size = @insignificant_digits
+        if @numeral.approximate?
+          @integer_insignificant_size += @trailing_size
+        end
+        @fractional_insignificant_size = 0
+        if @numeral.repeating?
+          @repeat_phase = @trailing_size % repeat_part_size
+          @fractional_start = @fractional_end = @digits.size
+        else
+          @repeat_phase = 0
+          @fractional_start = @fractional_end = @digits.size
+        end
+      else
+        @trailing_size = @leading_size = 0
+        @integer_start = 0
+        @integer_end   = @integer_part_size
+        @integer_insignificant_size = [@insignificant_digits - (@digits.size - @integer_part_size), 0].max
+        if @numeral.repeating? && @numeral.repeat < @integer_part_size
+          @repeat_phase = (@integer_end - @numeral.repeat) % repeat_part_size
+          @fractional_start = @fractional_end = @digits.size
+          @fractional_insignificant_size = 0
+        else
+          @repeat_phase = 0
+          @fractional_start = @integer_part_size
+          @fractional_end   = @numeral.repeat || @digits.size
+          @fractional_insignificant_size = [@insignificant_digits, @fractional_end - @fractional_start].min
+        end
+      end
+    end
+
+  end
+
+end