plurimath 0.10.7 → 0.11.0

data/lib/plurimath/formatter/numbers/fraction.rb

@@ -3,37 +3,42 @@
 module Plurimath
   module Formatter
     module Numbers
+      # Transforms fraction digits on Parts before localized rendering.
       class Fraction < Base
         attr_reader :decimal, :precision, :separator, :group
 
-        DEFAULT_PRECISION = 3
-        DEFAULT_STRINGS = { empty: "", zero: "0", dot: ".", f: "F" }.freeze
+        DEFAULT_PRECISION = FormatOptions::DEFAULT_FRACTION_PRECISION
+        DEFAULT_STRINGS = { empty: "", zero: "0", dot: "." }.freeze
 
-        def initialize(symbols = {})
+        def initialize(options)
           super
-          @group       = symbols[:fraction_group_digits]
-          @decimal     = symbols.fetch(:decimal, DEFAULT_STRINGS[:dot])
-          @int_group   = symbols[:group]
-          @separator   = symbols[:fraction_group].to_s
-          @precision   = symbols.fetch(:precision, DEFAULT_PRECISION)
-          @digit_count = symbols[:digit_count].to_i
+          @group = self.options.fraction_group_digits
+          @decimal = self.options.decimal
+          @separator = self.options.fraction_group
+          @precision = self.options.precision || DEFAULT_PRECISION
+          @digit_count = self.options.digit_count
         end
 
-        def apply(fraction, result, integer_formatter)
-          precision = symbols[:precision] || @precision
-          @result = result
-          @integer_formatter = integer_formatter
-          return DEFAULT_STRINGS[:empty] unless precision.positive?
+        # Keep fraction preparation on structured parts; localized rendering and
+        # grouping happen later at the PartsRenderer boundary.
+        def apply_parts(parts, precision: self.precision)
+          precision = precision.to_i
+          return parts.with_digits(fraction_digits: DEFAULT_STRINGS[:empty]) unless precision.positive?
 
-          fraction = change_base(fraction) if !base_default? && fraction.match?(/[1-9]/)
+          @integer_digits = parts.integer_digits
 
+          fraction = parts.fraction_digits
+          fraction = change_base(fraction, precision) if !base_default? && fraction.match?(/[1-9]/)
           number = if @digit_count.positive?
-                     digit_count_format(fraction)
+                     digit_count_format(fraction, precision)
                    else
                      format(fraction, precision)
                    end
-          formatted_number = format_groups(number) if number && !number.empty?
-          formatted_number ? decimal + formatted_number : DEFAULT_STRINGS[:empty]
+
+          parts.with_digits(
+            integer_digits: integer_digits,
+            fraction_digits: number.to_s,
+          )
         end
 
         def format(number, precision)
@@ -43,6 +48,7 @@ module Plurimath
         end
 
         def format_groups(string, length = group)
+          string = capitalize_hex_digits(string)
           length = string.length if group.to_i.zero?
 
           change_format(string, length)
@@ -59,32 +65,30 @@ module Plurimath
           tokens.compact.join(separator)
         end
 
-        def digit_count_format(fraction)
-          integer = raw_integer + DEFAULT_STRINGS[:dot] + fraction
+        # The digit_count option is a total visible-digit budget, so fraction
+        # rounding can carry back into the integer digits.
+        def digit_count_format(fraction, precision)
+          integer = integer_digits + DEFAULT_STRINGS[:dot] + fraction
           int_length = integer.length.pred # integer length; excluding the decimal point
           if int_length > @digit_count
-            # When digit_count is less than or equal to the integer length,
-            # omit the fractional part entirely and handle rounding in the integer
-            if @digit_count <= raw_integer.length
-              # Check if we need to round the integer up based on the fractional part
-              if fraction[0] && DIGIT_VALUE[fraction[0]] >= threshold
-                # Round up the integer part
-                round_integer([], 1)
-              end
+            # When digit_count is within the integer length, omit the fraction
+            # and let the integer carry handle rounding.
+            if @digit_count <= integer_digits.length
+              round_integer([], 1) if digit_sequence.round_up?(fraction[0])
               return DEFAULT_STRINGS[:empty]
             end
             round_base_string(fraction)
           elsif int_length < @digit_count
-            fraction + (DEFAULT_STRINGS[:zero] * (update_digit_count(fraction) - int_length))
+            fraction + (DEFAULT_STRINGS[:zero] * (update_digit_count(fraction, precision) - int_length))
           else
             fraction
           end
         end
 
-        def update_digit_count(number)
-          return @digit_count unless zeros_count_in(number) == @precision
+        def update_digit_count(number, precision)
+          return @digit_count unless zeros_count_in(number) == precision
 
-          @digit_count - @precision + 1
+          @digit_count - precision + 1
         end
 
         def zeros_count_in(number)
@@ -94,85 +98,38 @@ module Plurimath
         end
 
         def round_base_string(fraction)
-          # Extract the digits we need, plus one extra digit for rounding decision
           digits = fraction[0..frac_digit_count].chars
           discard_char = digits.pop
           return DEFAULT_STRINGS[:empty] unless discard_char
-          # If the discarded digit is below the rounding threshold (< base/2), truncate
-          return digits.join if DIGIT_VALUE[discard_char] < threshold
-
-          # Perform carry propagation for rounding up
-          carry = 1
-          rounded_reversed = []
-          digits.reverse_each do |digit|
-            next rounded_reversed << digit unless carry.positive?
-
-            # If current digit is at max value for this base (e.g., 'f' for base 16),
-            # set it to '0' and continue carrying
-            rounded_reversed << if DIGIT_VALUE[digit] == base.pred
-                                  DEFAULT_STRINGS[:zero]
-                                else
-                                  # Otherwise, increment this digit and stop carrying
-                                  carry = 0
-                                  next_mapping_char(digit)
-                                end
-          end
 
-          # If we still have a carry after processing all fractional digits,
-          # we need to round up the integer part
+          return digits.join unless digit_sequence.round_up?(discard_char)
+
+          rounded_reversed, carry = digit_sequence.increment_reversed(digits.reverse)
           round_integer(rounded_reversed, carry) if carry.positive?
           rounded_reversed.reverse.join unless rounded_reversed.empty?
         end
 
         def round_integer(fraction_digits_reversed, carry = 1)
-          # Propagate carry into the integer part, updating the formatted result
-          incremented, carry = increment_integer_digits(
-            raw_integer.chars.reverse, carry
+          incremented, carry = digit_sequence.increment_reversed(
+            integer_digits.chars.reverse,
+            carry: carry,
           )
+          incremented = incremented.reverse.join
           new_integer = [incremented]
           if carry.positive?
-            # If carry propagates through all integer digits (e.g., 9+1=10 in base 10),
-            # we need to prepend '1' and remove one fractional digit to maintain digit_count
             fraction_digits_reversed.pop
             new_integer.insert(0, "1")
           end
-          # Update the result array with the new integer value
-          @result[0] = @integer_formatter.format_groups(new_integer.join)
-        end
-
-        def increment_integer_digits(digits, carry)
-          # Skip over separator characters while propagating carry through integer digits
-          str_chars = [decimal, @int_group]
-          digits.each_with_index do |digit, index|
-            next if str_chars.include?(digit)
-
-            if DIGIT_VALUE[digit] == base.pred
-              # Digit is at max value (e.g., 'f' for base 16), set to '0' and continue carry
-              digits[index] = DEFAULT_STRINGS[:zero]
-            else
-              # Increment this digit and stop carrying
-              digits[index] = next_mapping_char(digit)
-              break carry = 0
-            end
-          end
-
-          [digits.reverse.join, carry]
+          @integer_digits = new_integer.join
         end
 
-        def change_base(number)
-          # Convert fractional part from base 10 to target base using rational arithmetic
-          # to avoid floating-point rounding errors.
-          # Algorithm: repeatedly multiply fraction by base, extract integer part as next digit
-          # Represent the fractional part exactly as a rational number to avoid
-          # binary floating-point rounding errors when converting bases.
-          # Note: The input `number` is always in decimal (base 10) format,
-          # so we use 10 as the denominator base regardless of the target base.
+        def change_base(number, precision = self.precision)
+          # Keep the decimal fraction exact while converting to the target base.
           fraction = Rational(number.to_i, 10**number.length)
 
           base_result = []
-          digits = @precision || number.length
 
-          digits.times do
+          precision.times do
             fraction *= base
             digit = fraction.to_i
             alpha_digit = HEX_ALPHANUMERIC[digit]
@@ -183,12 +140,12 @@ module Plurimath
           base_result.join
         end
 
-        def raw_integer
-          @result[0].delete(@int_group.to_s)
+        def integer_digits
+          @integer_digits
         end
 
         def frac_digit_count
-          @digit_count - raw_integer.length
+          @digit_count - integer_digits.length
         end
       end
     end

data/lib/plurimath/formatter/numbers/integer.rb

@@ -3,15 +3,18 @@
 module Plurimath
   module Formatter
     module Numbers
+      # Converts integer digits to the target base and applies integer grouping.
       class Integer < Base
-        attr_reader :separator, :groups
+        attr_reader :separator, :groups, :padding, :padding_digits,
+                    :padding_group_digits
 
-        DEFAULT_SEPARATOR = ","
-
-        def initialize(symbols = {})
+        def initialize(options)
           super
-          @groups    = symbols[:group_digits] || 3
-          @separator = symbols[:group] || DEFAULT_SEPARATOR
+          @groups = self.options.group_digits
+          @separator = self.options.group
+          @padding = self.options.padding
+          @padding_digits = self.options.padding_digits
+          @padding_group_digits = self.options.padding_group_digits
         end
 
         def apply(number)
@@ -19,6 +22,8 @@ module Plurimath
         end
 
         def format_groups(string)
+          string = capitalize_hex_digits(string)
+          string = pad_integer(string)
           tokens = []
 
           until string.empty?
@@ -38,6 +43,25 @@ module Plurimath
 
           number.to_i.to_s(base)
         end
+
+        private
+
+        def pad_integer(string)
+          target_width = padding_target_width(string)
+          return string unless target_width > string.length
+
+          string.rjust(target_width, padding)
+        end
+
+        def padding_target_width(string)
+          return padding_digits if padding_digits.positive?
+          return string.length unless padding_group_digits.positive?
+
+          remainder = string.length % padding_group_digits
+          return string.length if remainder.zero?
+
+          string.length + padding_group_digits - remainder
+        end
       end
     end
   end

data/lib/plurimath/formatter/numbers/notation_renderer.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Builds e/scientific/engineering notation while delegating coefficient
+      # localization back through the structured renderer.
+      class NotationRenderer
+        SUPPORTED_NOTATIONS = %i[e scientific engineering].freeze
+
+        def initialize(options)
+          @options = options
+          @precision = (@options.precision || 0).to_i
+          @exponent_sign_renderer = SignRenderer.new(@options.exponent_sign)
+        end
+
+        def render(source, notation)
+          case notation.to_sym
+          when :e
+            render_e(source)
+          when :scientific
+            render_scientific(source)
+          when :engineering
+            render_engineering(source)
+          end
+        end
+
+        def self.supported?(notation)
+          SUPPORTED_NOTATIONS.include?(notation&.to_sym)
+        end
+
+        private
+
+        attr_reader :exponent_sign_renderer, :options, :precision
+
+        def render_e(source)
+          localized_notation_parts(source).join(options.exponent_separator.to_s)
+        end
+
+        def render_scientific(source)
+          localized_notation_parts(source).join(" #{options.times} 10^")
+        end
+
+        def render_engineering(source)
+          parts = notation_parts(source)
+          parts = engineering_notation_parts(parts) unless source.decimal.zero?
+          parts[0] = localize_parts(source, parts[0], precision: engineering_precision(source))
+          parts.join(" #{options.times} 10^")
+        end
+
+        def localize_parts(source, parts, precision:)
+          NumberRenderer.new(
+            source,
+            options,
+          ).format_parts(
+            parts,
+            precision: precision,
+          )
+        end
+
+        def localized_notation_parts(source)
+          parts = notation_parts(source)
+          parts[0] = localize_parts(source, parts[0], precision: precision)
+          parts[1] = render_exponent(parts[1])
+          parts
+        end
+
+        def notation_parts(source)
+          return [source.to_parts(base: options.base), 0] if source.decimal.zero?
+
+          parts = source.to_parts(base: Base::DEFAULT_BASE)
+          digits, exponent = significant_digits_and_exponent(parts)
+          [
+            Parts.new(
+              sign: parts.sign,
+              base: options.base,
+              integer_digits: digits[0],
+              fraction_digits: digits[1..].to_s,
+            ),
+            exponent,
+          ]
+        end
+
+        def engineering_notation_parts(parts)
+          coefficient, exponent = parts
+          index = exponent % 3
+          exponent -= index
+          digits = "#{coefficient.integer_digits}#{coefficient.fraction_digits}"
+          integer_length = index + 1
+          integer_digits = digits[0...integer_length].to_s.ljust(integer_length, "0")
+
+          [
+            Parts.new(
+              sign: coefficient.sign,
+              base: options.base,
+              integer_digits: integer_digits,
+              fraction_digits: digits[integer_length..].to_s,
+            ),
+            render_exponent(exponent),
+          ]
+        end
+
+        def engineering_precision(source)
+          return precision if precision.positive?
+
+          [source.significant_digit_count - 1, 0].max
+        end
+
+        def significant_digits_and_exponent(parts)
+          if parts.integer_zero?
+            index = parts.fraction_digits.index(/[1-9]/)
+            [parts.fraction_digits[index..], -(index + 1)]
+          else
+            digits = "#{parts.integer_digits}#{parts.fraction_digits}"
+            index = digits.index(/[1-9]/)
+            [digits[index..], parts.integer_digits.length - index - 1]
+          end
+        end
+
+        def render_exponent(exponent)
+          return "0" if exponent.zero?
+
+          exponent_sign_renderer.apply(exponent, exponent.abs.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/formatter/numbers/number_renderer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Orchestrates Source and Parts through numeric transforms and final
+      # renderers; low-level digit rules stay in composed helpers.
+      class NumberRenderer
+        attr_reader :options, :source
+
+        def initialize(source, options)
+          @source = source
+          @options = options
+          @base_notation = BaseNotation.new(@options)
+          @integer_format = Integer.new(@options)
+          @fraction_format = Fraction.new(@options)
+          @significant_format = Significant.new(@options)
+          @parts_renderer = PartsRenderer.new(
+            integer_formatter: @integer_format,
+            fraction_formatter: @fraction_format,
+          )
+          @sign_renderer = SignRenderer.new(@options.number_sign)
+        end
+
+        def format(precision: nil)
+          render_precision = precision || options.precision || source_precision
+          parts = source.to_parts(
+            base: options.base,
+            precision: render_precision,
+          )
+          format_parts(parts, precision: render_precision)
+        end
+
+        def format_parts(parts, precision:)
+          parts = parts.with_digits(
+            fraction_digits: parts.fraction_digits[0...precision.to_i].to_s,
+          )
+          parts = renderable_parts(parts, precision: precision)
+
+          parts = significant_format.apply_parts(parts) if significant_format.active?
+          result = parts_renderer.render(parts)
+
+          sign_renderer.apply(parts, base_notation.apply(result))
+        end
+
+        private
+
+        attr_reader :base_notation, :fraction_format, :integer_format,
+                    :parts_renderer, :significant_format, :sign_renderer
+
+        def renderable_parts(parts, precision:)
+          parts = parts.with_digits(
+            integer_digits: integer_format.number_to_base(parts.integer_digits),
+          )
+          fraction_format.apply_parts(parts, precision: precision)
+        end
+
+        def source_precision
+          return 0 if source.decimal.fix == source.decimal
+
+          source.fraction_digits.length
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/formatter/numbers/parts.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Normalized digit value object passed between transforms before
+      # localization.
+      class Parts
+        attr_reader :base, :fraction_digits, :integer_digits, :sign
+
+        def initialize(
+          sign:,
+          base:,
+          integer_digits:,
+          fraction_digits:
+        )
+          @sign = sign
+          @base = base
+          @integer_digits = normalize_integer(integer_digits)
+          @fraction_digits = fraction_digits.to_s
+        end
+
+        def fractional?
+          !fraction_digits.empty?
+        end
+
+        def integer_zero?
+          integer_digits == "0"
+        end
+
+        def negative?
+          sign.negative?
+        end
+
+        def significant_digit_count
+          digits.sub(/\A0+/, "").length
+        end
+
+        def with_digits(
+          integer_digits: self.integer_digits,
+          fraction_digits: self.fraction_digits
+        )
+          self.class.new(
+            sign: sign,
+            base: base,
+            integer_digits: integer_digits,
+            fraction_digits: fraction_digits,
+          )
+        end
+
+        def to_s
+          number = fractional? ? "#{integer_digits}.#{fraction_digits}" : integer_digits
+          negative? ? "-#{number}" : number
+        end
+
+        private
+
+        def digits
+          "#{integer_digits}#{fraction_digits}"
+        end
+
+        def normalize_integer(value)
+          normalized = value.to_s.sub(/\A0+(?=.)/, "")
+          normalized.empty? ? "0" : normalized
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/formatter/numbers/parts_renderer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Renders already-transformed Parts into localized integer/fraction text.
+      class PartsRenderer
+        def initialize(integer_formatter:, fraction_formatter:)
+          @integer_formatter = integer_formatter
+          @fraction_formatter = fraction_formatter
+        end
+
+        def render(parts)
+          rendered = integer_formatter.format_groups(parts.integer_digits)
+          return rendered unless parts.fractional?
+
+          "#{rendered}#{fraction_formatter.decimal}#{formatted_fraction(parts)}"
+        end
+
+        private
+
+        attr_reader :fraction_formatter, :integer_formatter
+
+        def formatted_fraction(parts)
+          fraction_formatter.format_groups(parts.fraction_digits)
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/formatter/numbers/precision_resolver.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Chooses which precision source wins for one render call.
+      class PrecisionResolver
+        def resolve(source, precision:, base:, significant:, notation_supported:)
+          return precision if precision
+
+          significant_precision = significant_base_precision(source, base, significant)
+          return significant_precision if significant_precision
+
+          # Source owns input-derived digit lengths; this resolver only decides
+          # which precision rule wins. Plain decimal rendering preserves
+          # fractional scale, while notation precision controls coefficient
+          # digits after the leading digit.
+          return source.notation_precision if notation_supported
+
+          source.decimal_precision
+        end
+
+        private
+
+        # When precision is omitted, infer the target-base fractional digits
+        # needed to satisfy :significant. Cap the count to the source significant
+        # digits so base conversion does not invent precision for values like 0.1.
+        # Add one extra digit when the source has more significant digits so
+        # Significant can still perform the final rounding pass.
+        def significant_base_precision(source, base, significant)
+          return unless target_base?(base)
+
+          return if significant.zero?
+
+          return 0 unless source.fractional?
+
+          source_significant = source.significant_digit_count
+          effective_significant = [significant, source_significant].min
+          target_precision = [
+            effective_significant - source.target_base_integer_length(base),
+            0,
+          ].max
+
+          target_precision += 1 if source_significant > effective_significant
+          target_precision
+        end
+
+        def target_base?(base)
+          BaseNotation::DEFAULT_PREFIXES.key?(base) && base != Base::DEFAULT_BASE
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/formatter/numbers/sign_renderer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Applies the final sign prefix to already-rendered number text.
+      class SignRenderer
+        def initialize(positive_sign = nil)
+          @positive_sign = positive_sign
+        end
+
+        def apply(number, rendered)
+          "#{prefix(number)}#{rendered}"
+        end
+
+        private
+
+        attr_reader :positive_sign
+
+        def prefix(number)
+          return "-" if number.negative?
+
+          "+" if positive_sign&.to_sym == :plus
+        end
+      end
+    end
+  end
+end