numerals 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 20e32ed4a377f88140d75db5dce2070dceca3b30
-  data.tar.gz: 835f3416de372cf7fa26f2607b74176b666d88b5
+  metadata.gz: 0e7931e88c73e54a2d95c47f45d222562dc03a02
+  data.tar.gz: 0179555b287f177e458d854708929838c9619bcc
 SHA512:
-  metadata.gz: a97323fa538d4e1fe2cc9c57b5fc9bc2e09dcf67260b8a74828be88415d7672efb6f314eefa6e23f41542d739bc291cf0c3f36c8b446eaf82c359b8beb0a7e7a
-  data.tar.gz: e894386209dbfbc2e3471a00cf866a39e320a99a00e8f6c467dfa4c3947a87eac6797409036efe4c6446041dbb9d8ad4a1dfeb83a7d8a3ae5522932d5a81d40d
+  metadata.gz: fbdfea7324a61b2d25888c0553acefac0911e97ed9ddd5e9217064694f1f66fefea0ba968941cead3634e0b9c5a4bfa55e12cfcb16896c42407f057724446580
+  data.tar.gz: ea99d01ee36c91692c926d64f022e08274f89b0a3f4f4eb96f0a4dcaaac1c4340c1c6484d9a1b29f235ae370a2fce903624b1e5656f3297ee1026728cf4d6b87

data/README.md

@@ -1,9 +1,146 @@
-numerals
+Numerals
 ========
 
-Number representation as text.
+The Numerals module provides formatted input/output for numeric types.
 
-This will be a successor gem to Nio.
+## Use
+
+    require 'numerals'
+    include Numerals
+
+The Numeral class is used internally to hold the representation of a numeric
+quantity as numeral in a positional system. Since repeating figures are
+supported in Numeral, a Numeral can represent exactly any rational number.
+
+Numerals can be exact or approximate. Exact numerals don't keep trailing zeros:
+they don't specify a fixed precision. Repeating numerals are always exact.
+
+Approximate numerals may have trailing zeros and have a determinate number
+of significant digits. Approximate numerals cannot held repeating figures,
+since they have limited precision.
+
+The Conversions module provides conversions between Numerals and the
+numeric types Integer, Rational, Float, Flt::Num and BigDecimal.
+
+The Format class holds formatting settings. It can be constructed
+with this bracket syntax:
+
+    format = Format[mode: :general, rounding: [precision: 10]]
+
+Which is a shortcut for:
+
+    format = Format[mode: Format::Mode[:general], rounding: Rounding[precision: 10]]
+
+And can also be expressed as:
+
+    format = Format[Format::Mode[:general], Rounding[precision: 10]]
+    puts format.rounding.precision                 # -> 10
+    puts format.rounding.mode                      # -> half_even
+
+New formats can be derived from an existing one by overriding some of
+its properties using the brackets operator on it:
+
+    format2 = format[rounding: :half_down]
+    puts format2.rounding.precision                # -> 10
+    puts format2.rounding.mode                     # -> half_down
+
+## Output
+
+Let's see how to use a Format to format a number into text form. By
+default the shortest possible output (that preserves the value) is produced:
+
+    puts Format[].write(0.1)                       # -> 0.1
+
+This is because the default Rounding property of Format is Rounding[:short]
+(rounding to :short precision), so the above is equivalent to:
+
+    puts Format[:short].write(0.1)                 # -> 0.1
+    puts Format[rounding: :short].write(0.1)       # -> 0.1
+
+To produce a numeric representation that shows explicitly all the precision
+of the number, the :free rounding precision can be used:
+
+    puts Format[:free].write(0.1)                  # -> 0.10000000000000001
+
+Specific precision can be obtained like this:
+
+    puts Format[precision: 6].write(0.1)           # -> 0.100000
+
+But this won't show digits that are insignificant (when the input number
+is regarded as an approximation):
+
+    puts Format[precision: 20].write(0.1)          # -> 0.10000000000000001
+    puts Format[precision: 20].write(Rational(1,10))# -> 0.10000000000000000000
+
+Although a Float is considered an approximation by default (since
+it cannot represent arbitrary precision exactly), we can
+reinterpret it as an exact quantity with the :exact_input Format option:
+
+    puts Format[:exact_input, precision: 20].write(0.1)# -> 0.10000000000000000555
+    puts Format[:exact_input].write(0.1)           # -> 0.1000000000000000055511151231257827021181583404541015625
+
+Rationals are always 'exact' quantities, and they may require infinite
+digits to be represented exactly in some output bases. This is handled
+by repeating numerals, which can be represented as text in two modes:
+
+    puts Format[].write(Rational(1,3))             # -> 0.333...
+    puts Format[symbols: [repeat_delimited: true]].write(Rational(1,3))# -> 0.<3>
+
+## Input
+
+The same Format class can be used to read formatted text into numeric values
+with the Format#read() method.
+
+    puts Format[].read('1.0', type: Float)         # -> 1.0
+
+For Flt types such as Flt::DecNum or Flt::BinNum there are a few options
+to determine the result, since these types can hold arbitrary precision.
+
+By default, these types are considered 'approximate'. Thus, the result
+will be a variable-precision result based on the input. The default
+Format, which has :short (simplifying) precision will produce a simple
+result with as few significant digits as possible:
+
+    puts Format[:short].read('1.000', type: Flt::DecNum)# -> 1
+    puts Format[:short].read('0.100', type: Flt::BinNum)# -> 0.1
+
+To retain the precision of the input text, the :free precision should be
+used:
+
+    puts Format[:free].read('1.000', type: Flt::DecNum)# -> 1.000
+    puts Format[:free].read('0.100', type: Flt::BinNum)# -> 0.1
+
+As an alternative, the precision implied by the text input can be ignored
+and the result adjusted to the precision of the destination context. This
+is done by regarding the input as 'exact'.
+
+    puts Format[:exact_input].read('1.000', type: Flt::DecNum)# -> 1.000000000000000000000000000
+    puts Format[:exact_input].read('0.100', type: Flt::BinNum)# -> 0.1
+    Flt::DecNum.context.precision = 8
+    puts Format[:exact_input].read('1.000', type: Flt::DecNum)# -> 1.0000000
+
+If the input specifies repeating digits, then it is automatically regarded
+exact and rounded according to the destination context:
+
+    puts Format[:exact_input].read('0.333...', type: Flt::DecNum)# -> 0.33333333
+
+Note that the repeating digits have been automatically detected. This
+happens because the repeating suffix '...' has ben found (it is defined
+by the Format::Symbols property of Format). An alternative way of
+specifying repeating digits is by the repeating delimiters specified
+in Symbols, which are <> by default:
+
+    puts Format[:exact_input].read('0.<3>', type: Flt::DecNum)# -> 0.33333333
+
+
+A Format can also be used to read a formatted number into a Numeral:
+
+    puts Format[].read('1.25', type: Numeral)      # -> Numeral[1, 2, 5, :sign=>1, :point=>1, :normalize=>:approximate, :base=>10]
+    puts Format[].read('1.<3>', type: Numeral)     # -> Numeral[1, 3, :sign=>1, :point=>1, :repeat=>1, :base=>10]
+
+Other examples:
+
+    puts Format[:free, base: 2].read('0.1', type: Flt::DecNum)# -> 0.5
 
 Roadmap
 =======
@@ -17,8 +154,15 @@ Done:
 
 * Rounding can be applied to Numerals (with rounding options)
 
-Pending:
-
 * Numerals can be written into text form using Formatting options
 
 * Numerals con be read from text form using Formatting options
+
+* Handling of 'unsignificant' digits: show them either as special
+  symbol, as zeros or omit them (comfigured in Symbols)
+
+Pending:
+
+* Padding aspect of formatting on output
+
+* Show base indicators on output

data/lib/numerals/conversions/bigdecimal.rb

@@ -1,30 +1,230 @@
 require 'numerals/conversions'
+require 'bigdecimal'
+require 'singleton'
 
-class Numerals::BigDecimalConversion
+class Numerals::BigDecimalConversion < Numerals::ContextConversion
+
+  # Options:
+  #
+  # * :input_rounding (optional, a non-exact Rounding or rounding mode)
+  #   which is used when input is approximate as the assumed rounding
+  #   mode which would be used so that the result numeral rounds back
+  #   to the input number
+  #
+  def initialize(options = {})
+    super BigDecimal, options
+  end
 
   def order_of_magnitude(value, options={})
     base = options[:base] || 10
     if base == 10
       value.exponent
     else
-      Conversions.order_of_magnitude(Flt::DecNum(value.to_s), options)
+      (Math.log(value.abs)/Math.log(base)).floor + 1
     end
   end
 
-  def number_to_numeral(number, options={})
-    mode = options[:mode] || :fixed
+  def number_of_digits(value, options={})
     base = options[:base] || 10
-    rounding = options[:rounding] || Rounding[:exact]
+    precision = x.precs.first
+    decimal_digits = x.split[1].size
+    n = decimal_digits # or use precision?
+    if base == 10
+      n
+    else
+      Flt::DecNum.context[precision: n].necessary_digits(base)
+    end
+  end
+
+  def exact?(value, options={})
+    options[:exact]
+  end
+
+  def number_to_numeral(number, mode, rounding)
+    if @context.special?(number)
+      special_num_to_numeral number
+    else
+      if mode == :exact
+        exact_num_to_numeral number, rounding
+      else # mode == :approximate
+        approximate_num_to_numeral(number, rounding)
+      end
+    end
+  end
+
+  def numeral_to_number(numeral, mode)
+    if numeral.special?
+      special_numeral_to_num numeral
+    elsif mode == :fixed
+      fixed_numeral_to_num numeral
+    else # mode == :free
+      free_numeral_to_num numeral
+    end
+  end
+
+  def write(number, exact_input, output_rounding)
+    output_base = output_rounding.base
+    input_base = @context.radix
+
+    if @context.special?(number)
+      special_num_to_numeral number
+    elsif exact_input
+      if output_base == input_base && output_rounding.free?
+        # akin to number.format(base: output_base, simplified: true)
+        if true
+          # ALT.1 just like approximate :short
+          general_num_to_numeral number, output_rounding, false
+        else
+          # ALT.2 just like different bases
+          exact_num_to_numeral number, output_rounding
+        end
+      else
+        # akin to number.format(base: output_base, exact: true)
+        exact_num_to_numeral number, output_rounding
+      end
+    else
+      if output_base == input_base && output_rounding.preserving?
+        # akin to number.format(base: output_base)
+        sign, coefficient, exponent = @context.split(number)
+        Numerals::Numeral.from_coefficient_scale sign*coefficient, exponent, approximate: true
+      elsif output_rounding.simplifying?
+        # akin to number.forma(base: output_base, simplify: true)
+        general_num_to_numeral number, output_rounding, false
+      else
+        # akin to number.forma(base: output_base, all_digits: true)
+        general_num_to_numeral number, output_rounding, true
+      end
+    end
+  end
+
+  def read(numeral, exact_input, approximate_simplified)
+    if numeral.special?
+      special_numeral_to_num numeral
+    elsif numeral.approximate? && !exact_input
+      if approximate_simplified
+        # akin to @context.Num(numeral_text, :short)
+        short_numeral_to_num numeral
+      else
+        # akin to @context.Num(numeral_text, :free)
+        free_numeral_to_num numeral
+      end
+    else
+      # akin to @context.Num(numeral_text, :fixed)
+      fixed_numeral_to_num numeral
+    end
+  end
+
+  private
+
+  def special_num_to_numeral(x)
+    if x.nan?
+      Numerals::Numeral.nan
+    elsif x.infinite?
+      Numerals::Numeral.infinity @context.sign(x)
+    end
+  end
+
+  def exact_num_to_numeral(number, rounding)
+    quotient = number.to_r
+    numeral = Numerals::Numeral.from_quotient(quotient, base: rounding.base)
+    unless rounding.free?
+      numeral = rounding.round(numeral)
+    end
+    numeral
+  end
 
+  def approximate_num_to_numeral(number, rounding)
+    all_digits = !rounding.free?
+    general_num_to_numeral(number, rounding, all_digits)
   end
 
-  def numeral_to_number(numeral, options={})
-    mode = options[:mode] || :fixed
+  def general_num_to_numeral(x, rounding, all_digits)
+    sign, coefficient, exponent = @context.split(x)
+    # the actual number of digits is x.split[1].size
+    # but BigDecimal doesn't keep trailing zeros
+    # we'll use the internal precision which is an implementation detail
+    precision = x.precs.first
+    output_base = rounding.base
+
+    # here rounding_mode is not the output rounding mode, but the rounding mode used for input
+    rounding_mode = (@input_rounding || rounding).mode
+
+    # The minimum exponent of BigDecimal numbers is not well defined;
+    # depends of host architecture, version of BigDecimal, etc.
+    # We'll use an arbitrary conservative value.
+    min_exp = -100000000
+    formatter = Flt::Support::Formatter.new(
+      @context.radix, min_exp, output_base, raise_on_repeat: false
+    )
+    formatter.format(
+      x, coefficient, exponent, rounding_mode, precision, all_digits
+    )
+
+    dec_pos, digits = formatter.digits
 
+    normalization = :approximate
+
+    numeral = Numerals::Numeral[digits, sign: sign, point: dec_pos, rep_pos: formatter.repeat, base: output_base, normalize: normalization]
+
+    numeral = rounding.round(numeral, round_up: formatter.round_up)
+
+    numeral
+  end
+
+  def special_numeral_to_num(numeral)
+    case numeral.special
+    when :nan
+      @context.nan
+    when :inf
+      @context.infinity numeral.sign
+    end
+  end
+
+  def fixed_numeral_to_num(numeral)
+    # consider:
+    # return exact_numeral_to_num(numeral) if numeral.exact?
+    if numeral.base == 10
+      unless @context.exact?
+        rounding = Rounding[@context.rounding, precision: @context.precision, base: @context.radix]
+        numeral = rounding.round(numeral)
+      end
+      same_base_numeral_to_num numeral
+    else
+      general_numeral_to_num numeral, :fixed
+    end
+  end
+
+  def same_base_numeral_to_num(numeral)
+    sign, coefficient, scale = numeral.split
+    @context.Num sign, coefficient, scale
+  end
+
+  def exact_numeral_to_num(numeral)
+    @context.Num Rational(*numeral.to_quotient), :fixed
+  end
+
+  def free_numeral_to_num(numeral)
+    general_numeral_to_num numeral, :free
+  end
+
+  def general_numeral_to_num(numeral, mode)
+    sign, coefficient, scale = numeral.split
+    reader = Flt::Support::Reader.new(mode: mode)
+    if @input_rounding
+      rounding_mode = @input_rounding.mode
+    else
+       rounding_Mode = @context.rounding
+    end
+    dec_num_context = Flt::DecNum::Context(
+      precision: @context.precision,
+      rounding:  @context.rounding
+    )
+    dec_num = reader.read(dec_num_context, rounding_mode, sign, coefficient, scale, numeral.base)
+    @context.Num dec_num
   end
 
 end
 
-def BigDecimal.numerals_conversion
-  Numerals::BigDecimalConversion.new
+def BigDecimal.numerals_conversion(options = {})
+  Numerals::BigDecimalConversion.new(options)
 end

data/lib/numerals/conversions/context_conversion.rb

@@ -0,0 +1,40 @@
+require 'numerals/conversions'
+require 'flt'
+
+# Base class for Conversions of type with context
+class Numerals::ContextConversion
+
+  def initialize(context_or_type, options={})
+    if Class === context_or_type && context_or_type.respond_to?(:context)
+      @type = context_or_type
+      @context = @type.context
+    elsif context_or_type.respond_to?(:num_class)
+      @context = context_or_type
+      @type = @context.num_class
+    else
+      raise "Invalid Conversion definition"
+    end
+    self.input_rounding = options[:input_rounding]
+  end
+
+  attr_reader :context, :type, :input_rounding
+
+  def input_rounding=(rounding)
+    if rounding
+      if rounding == :context
+        @input_rounding = Rounding[@context.rounding, precision: @context.precision, base: @context.radix]
+      else
+        rounding = Rounding[base: @context.radix].set!(rounding)
+        if rounding.base == @context.radix
+          @input_rounding = rounding
+        else
+          # The rounding precision is not meaningful for the destination type on input
+          @input_rounding = Rounding[rounding.mode, base: @context.radix]
+        end
+      end
+    else
+      @input_rounding = nil
+    end
+  end
+
+end