plurimath 0.11.0 → 0.11.1

data/README.adoc

@@ -513,7 +513,7 @@ formatter = Plurimath::NumberFormatter.new(
 <1> Locale to be used for number formatting.
 <2> String pattern to define the number formatting.
 <3> Hash containing relevant options for number formatting.
-<4> Number of decimal places to round.
+<4> Number of decimal places to keep; the fraction is truncated, not rounded.
 
 Where,
 
@@ -534,7 +534,8 @@ options for number formatting. Use either `localize_number` or
 See <<localizer_symbols,format options hash>> for details.
 
 `precision: <precision-number>`:: (optional, default `nil`)
-Number of decimal places to round. Accepts an integer value.
+Number of decimal places to keep; the fraction is truncated, not
+rounded. Accepts an integer value.
 +
 .Specifying a precision of 6 digits
 [example]
@@ -571,6 +572,28 @@ through a Hash object containing specified options.
 
 This Hash object is called the "format options Hash".
 
+Option values follow a common handling policy:
+
+* Count options (`precision`, `significant`, `digit_count`, `group_digits`,
+  `fraction_group_digits`, `padding_digits`, `padding_group_digits`) accept an
+  `Integer` or its `String`/`Symbol` numeric equivalent (`"4"`). Any other
+  value, including negative numbers, raises `Plurimath::ConfigurationError`.
+* Separator options (`decimal`, `group`, `fraction_group`, `base_prefix`,
+  `base_postfix`) accept free-form strings. An explicitly passed `nil`
+  disables the separator — for `decimal` this renders the digits without a
+  decimal mark, and output correctness is then the caller's responsibility.
+  One exception: `group: nil` falls back to the default separator instead of
+  disabling (use `group: ""` to disable grouping). Boolean values raise
+  `Plurimath::ConfigurationError`.
+* Enumerated options (`notation`, `number_sign`, `exponent_sign`, `e`,
+  `times`, `hex_capital`) accept their documented values as `Symbol` or
+  `String`; unrecognized `String`/`Symbol` values fall back to the default
+  behavior. Any other type raises `Plurimath::ConfigurationError` — including
+  Boolean, except for `hex_capital`, where `true`/`false` are documented values.
+* The `locale` always falls back to `:en` for unsupported or wrong-typed
+  values; it never raises.
+* Invalid number input raises `Plurimath::Errors::InvalidNumber`.
+
 Available options are explained below.
 
 NOTE: Each option takes an input of a certain specified type. Using an input
@@ -584,6 +607,15 @@ The same option keys can be passed through `localizer_symbols`, through the
 per-call `format:` hash, or through `Plurimath::Formatter::Standard`'s
 `options:` argument.
 
+When rendering through `Plurimath::Math::Formula` serialization methods
+(`to_asciimath`, `to_latex`, `to_mathml`, `to_unicodemath`, `to_html`),
+per-element overrides can be supplied via `options[:format]`. The hash is
+forwarded to `NumberFormatter#localized_number`'s `format:` keyword, taking
+precedence over the configured formatter's symbols for that one element.
+Custom formatters with a simpler `localized_number(value)` signature are
+unaffected unless `options[:format]` is supplied, in which case their method
+must accept the `format:` keyword.
+
 
 `decimal`:: (`String` value)
 Symbol to use for the decimal point. Accepts a character.
@@ -695,12 +727,12 @@ Missing integer digits are inserted before grouping using the configured
 "32"    with `padding_group_digits: 4, group: ""` => "0032"
 "32123" with `padding_group_digits: 4, group: ""` => "00032123"
 ====
-====
 
 `base`:: (`Numeric` value)
 Sets the numeric base (radix) used to render both the integer and fractional parts of the number.
 Supported values are 2 (binary), 8 (octal), 10 (decimal, default) and 16 (hexadecimal).
-Passing any other value for `base` raises `Plurimath::Formatter::UnsupportedBase`.
+The value is also accepted as its `String` or `Symbol` equivalent (`"16"`).
+Passing any other value for `base` raises `Plurimath::Errors::UnsupportedBase`.
 +
 .Rendering numbers in different bases
 [example]
@@ -752,6 +784,10 @@ uppercase letters. This includes both hexadecimal digits and any separators
 Use `:numbers_only` to uppercase generated hexadecimal digits without changing
 separator characters. It has no effect for other bases.
 +
+Both values are also accepted as their `String` or `Symbol` equivalents
+(`"true"`, `:true`, `"numbers_only"`). Matching is case-sensitive; any other
+value (including any form of `false`) disables uppercasing.
++
 .Uppercase hexadecimal output
 [example]
 ====
@@ -1027,8 +1063,11 @@ In this example it is `' '` (a space).
 ----
 formatter = Plurimath::NumberFormatter.new(:en, localize_number: "#,##0.### ###")
 formatter.localized_number("1234.56789")
-# => "1,234.568 9"
+# => "1,234.567 89"
 ----
+
+NOTE: A space used as a group or fraction-group delimiter in the
+`localize_number` pattern is emitted as U+00A0 NO-BREAK SPACE in the output.
 ====
 
 
@@ -1052,7 +1091,7 @@ formatter.localized_number(
 ----
 <1> The number to be formatted.
 <2> The locale to be used for number formatting.
-<3> The number of decimal places to round the number to.
+<3> The number of decimal places to keep; the fraction is truncated, not rounded.
 <4> Hash containing the relevant options for number formatting.
 
 Where,
@@ -1065,8 +1104,8 @@ Value is a symbol.
 Overrides the locale set during the creation of the `NumberFormatter` object. If
 not provided, the locale of the `NumberFormatter` instance will be used.
 
-`precision: <precision-number>`:: (optional) The number of decimal places to round the
-number to. If not provided, the precision of the `NumberFormatter` instance will
+`precision: <precision-number>`:: (optional) The number of decimal places to keep
+(the fraction is truncated, not rounded). If not provided, the precision of the `NumberFormatter` instance will
 be used.
 
 `format: <format-hash>`:: (optional, default `{}`) A Hash containing the relevant
@@ -1075,7 +1114,8 @@ configuration of the `NumberFormatter`.
 Takes a Hash in the form of the <<localizer_symbols,format options hash>>.
 
 `precision: <precision-number>`::
-Number of decimal places to round. Accepts an integer value.
+Number of decimal places to keep; the fraction is truncated, not
+rounded. Accepts an integer value.
 +
 .Specifying a precision of 6 digits
 [example]

data/lib/plurimath/deprecation.rb

@@ -6,7 +6,8 @@ module Plurimath
     DEFAULT_BEHAVIOR = :collect
 
     class << self
-      def warn(feature:, message: nil, replacement: nil, since: nil, remove_in: nil)
+      def warn(feature:, message: nil, replacement: nil, since: nil,
+remove_in: nil)
         feature = validate_feature(feature)
         return if behavior == :collect && emitted_features[feature]
 

data/lib/plurimath/errors/configuration_error.rb

@@ -2,10 +2,11 @@
 
 module Plurimath
   class ConfigurationError < Error
-    def initialize(type, value: nil, supported: nil)
+    def initialize(type, value: nil, supported: nil, option: nil)
       @type = type
       @value = value
       @supported = supported
+      @option = option
       super(message)
     end
 
@@ -19,6 +20,9 @@ module Plurimath
       when :conflicting_formatter_options
         "formatter options cannot be used together: choose either " \
         ":padding_digits or :padding_group_digits"
+      when :invalid_formatter_option
+        "invalid value #{@value.inspect} for formatter option " \
+        "#{@option.inspect}#{" (expected #{@supported})" if @supported}"
       else
         "invalid Plurimath configuration"
       end

data/lib/plurimath/errors/deprecation_error.rb

@@ -6,7 +6,8 @@ module Plurimath
 
     attr_reader :feature, :replacement, :since, :remove_in
 
-    def initialize(feature:, message: nil, replacement: nil, since: nil, remove_in: nil)
+    def initialize(feature:, message: nil, replacement: nil, since: nil,
+remove_in: nil)
       @feature = feature
       @replacement = replacement
       @since = since

data/lib/plurimath/errors/invalid_number.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    class InvalidNumber < Plurimath::Error
+      def initialize(value)
+        @value = value
+        super(message)
+      end
+
+      def message
+        "[plurimath] Invalid number #{@value.inspect} for number formatting. " \
+          "Expected a numeric string such as \"1234\", \"-12.34\", or \"1.2e5\"."
+      end
+    end
+  end
+end

data/lib/plurimath/errors/unsupported_base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    class UnsupportedBase < Plurimath::Error
+      def initialize(base, supported_bases)
+        @base = base
+        @supported = supported_bases.keys.join(", ")
+        super(message)
+      end
+
+      def message
+        "[plurimath] Unsupported base `#{@base}` for number formatting. " \
+          "[plurimath] The formatter `:base` option must be one of: #{@supported}."
+      end
+    end
+  end
+end

data/lib/plurimath/errors/{formatter/unsupported_locale.rb → unsupported_locale.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Plurimath
-  module Formatter
+  module Errors
     class UnsupportedLocale < Plurimath::Error
       def initialize(locale, supported_locales)
         @locale = locale

data/lib/plurimath/errors.rb

@@ -1 +1,9 @@
 # frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    autoload :InvalidNumber, "#{__dir__}/errors/invalid_number"
+    autoload :UnsupportedBase, "#{__dir__}/errors/unsupported_base"
+    autoload :UnsupportedLocale, "#{__dir__}/errors/unsupported_locale"
+  end
+end

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

@@ -22,7 +22,12 @@ module Plurimath
         end
 
         def apply(string)
-          rendered = upcase_hex? ? string.tr(Base::HEX_DIGITS, Base::HEX_DIGITS.upcase) : string
+          rendered = if upcase_hex?
+                       string.tr(Base::HEX_DIGITS,
+                                 Base::HEX_DIGITS.upcase)
+                     else
+                       string
+                     end
           return rendered if default?
 
           "#{base_prefix}#{rendered}#{base_postfix}"
@@ -59,7 +64,7 @@ module Plurimath
         def validate_base!
           return if self.class.supported?(base)
 
-          raise UnsupportedBase.new(base, DEFAULT_PREFIXES)
+          raise Plurimath::Errors::UnsupportedBase.new(base, DEFAULT_PREFIXES)
         end
       end
     end

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

@@ -32,11 +32,16 @@ module Plurimath
         end
 
         def base
-          symbols[:base] || Base::DEFAULT_BASE
+          value = symbols[:base]
+          return Base::DEFAULT_BASE if value.nil?
+
+          # Numeric String/Symbol forms are normalized; anything else is left
+          # raw so BaseNotation reports it through UnsupportedBase.
+          coerce_integer(value) { return value }
         end
 
         def base_prefix
-          symbols[:base_prefix].to_s
+          separator_option(:base_prefix).to_s
         end
 
         def base_prefix?
@@ -44,7 +49,7 @@ module Plurimath
         end
 
         def base_postfix
-          symbols[:base_postfix]
+          separator_option(:base_postfix)
         end
 
         def base_postfix?
@@ -52,56 +57,84 @@ module Plurimath
         end
 
         def decimal
-          symbols.fetch(:decimal, DEFAULT_DECIMAL)
+          # An explicitly passed nil renders without a separator; output
+          # correctness is then the caller's responsibility.
+          separator_option(:decimal, default: DEFAULT_DECIMAL)
         end
 
         def digit_count
-          symbols[:digit_count].to_i
+          integer_option(:digit_count, default: 0)
         end
 
         def fraction_group
-          symbols[:fraction_group].to_s
+          separator_option(:fraction_group).to_s
         end
 
         def fraction_group_digits
-          symbols[:fraction_group_digits]
+          integer_option(:fraction_group_digits)
         end
 
         def group
-          symbols[:group] || DEFAULT_GROUP
+          # Unlike decimal, an explicit nil group falls back to the default
+          # separator; use "" to disable grouping.
+          (separator_option(:group,
+                            default: DEFAULT_GROUP) || DEFAULT_GROUP).to_s
         end
 
         def group_digits
-          symbols[:group_digits] || DEFAULT_GROUP_DIGITS
+          integer_option(:group_digits, default: DEFAULT_GROUP_DIGITS)
         end
 
         def hex_capital
-          symbols[:hex_capital]
+          value = symbols[:hex_capital]
+          # nil is handled first: under Opal `when nil` spuriously matches
+          # non-nil values (nil === 1.5 is true there), so it must not appear
+          # in the type whitelist below.
+          return if value.nil?
+
+          # Accept only Boolean/String/Symbol and reject any other type.
+          # Attribute-parsing callers deliver String/Symbol (:true,
+          # "numbers_only"), so the accepted forms normalize through to_s.
+          case value
+          when true, false, String, Symbol
+            case value.to_s
+            when "true" then true
+            when "numbers_only" then :numbers_only
+            end
+          else
+            invalid_option!(:hex_capital, value)
+          end
         end
 
         def number_sign
-          symbols[:number_sign]
+          symbol_option(:number_sign)
         end
 
         def padding
-          value = symbols.fetch(:padding, DEFAULT_PADDING).to_s
+          value = separator_option(:padding, default: DEFAULT_PADDING).to_s
           value.empty? ? DEFAULT_PADDING : value[0]
         end
 
         def padding_digits
-          symbols[:padding_digits].to_i
+          integer_option(:padding_digits, default: 0)
         end
 
         def padding_group_digits
-          symbols[:padding_group_digits].to_i
+          integer_option(:padding_group_digits, default: 0)
         end
 
         def notation_supported?
           NotationRenderer.supported?(notation)
         end
 
+        # Whether precision came from the caller (kwarg or symbols) rather
+        # than being inferred from the source by the resolver.
+        def explicit_precision?
+          @explicit_precision
+        end
+
         def significant
-          symbols[:significant].to_i
+          integer_option(:significant, default: 0)
         end
 
         def to_h
@@ -111,7 +144,19 @@ module Plurimath
         private
 
         def resolve_precision(source, precision, precision_resolver)
-          effective_precision = precision || symbols[:precision]
+          # A nil check (not ||) so that explicit false reaches validation.
+          effective_precision = precision.nil? ? symbols[:precision] : precision
+          unless effective_precision.nil?
+            value = effective_precision
+            effective_precision = coerce_integer(value) do
+              invalid_option!(:precision, value)
+            end
+            if effective_precision.negative?
+              invalid_option!(:precision, value,
+                              expected: "a non-negative integer")
+            end
+          end
+          @explicit_precision = !effective_precision.nil?
           return effective_precision unless precision_resolver
 
           precision_resolver.resolve(
@@ -119,12 +164,73 @@ module Plurimath
             precision: effective_precision,
             base: base,
             significant: significant,
+            digit_count: digit_count,
             notation_supported: notation_supported?,
           )
         end
 
+        # Counts must be non-negative Integers; numeric String/Symbol forms are
+        # normalized because attribute-parsing callers deliver those.
+        def integer_option(key, default: nil)
+          value = symbols[key]
+          return default if value.nil?
+
+          integer = coerce_integer(value) { invalid_option!(key, value) }
+          if integer.negative?
+            invalid_option!(key, value,
+                            expected: "a non-negative integer")
+          end
+
+          integer
+        end
+
+        def coerce_integer(value)
+          # Note on Opal: JS has a single number type, so a whole-valued Float
+          # (4.0) is indistinguishable from the Integer 4 (same value, same
+          # to_s "4") — under Opal it is treated as that integer. MRI rejects
+          # Floats here; non-whole Floats (1.5) are rejected in both runtimes.
+          case value
+          when ::Integer then value
+          when true, false, Float then yield
+          else
+            begin
+              Integer(value.to_s, 10)
+            rescue ArgumentError, TypeError
+              yield
+            end
+          end
+        end
+
+        # Separators are free-form strings; explicit nil disables the
+        # separator, and Booleans are always a caller bug.
+        def separator_option(key, default: nil)
+          value = symbols.fetch(key, default)
+          invalid_option!(key, value) if [true, false].include?(value)
+
+          value
+        end
+
         def symbol_option(key)
-          symbols[key]&.to_sym
+          value = symbols[key]
+          return if value.nil?
+
+          # Enumerated/symbol options accept only String or Symbol; reject
+          # other types (and booleans) instead of coercing arbitrary input.
+          unless value.is_a?(String) || value.is_a?(Symbol)
+            invalid_option!(key,
+                            value)
+          end
+
+          value.to_sym
+        end
+
+        def invalid_option!(key, value, expected: nil)
+          raise Plurimath::ConfigurationError.new(
+            :invalid_formatter_option,
+            option: key,
+            value: value,
+            supported: expected,
+          )
         end
 
         def validate_padding_options!

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

@@ -28,9 +28,12 @@ module Plurimath
           @integer_digits = parts.integer_digits
 
           fraction = parts.fraction_digits
-          fraction = change_base(fraction, precision) if !base_default? && fraction.match?(/[1-9]/)
+          if !base_default? && fraction.match?(/[1-9]/)
+            fraction = change_base(fraction,
+                                   precision)
+          end
           number = if @digit_count.positive?
-                     digit_count_format(fraction, precision)
+                     digit_count_format(fraction)
                    else
                      format(fraction, precision)
                    end
@@ -67,7 +70,7 @@ module Plurimath
 
         # 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)
+        def digit_count_format(fraction)
           integer = integer_digits + DEFAULT_STRINGS[:dot] + fraction
           int_length = integer.length.pred # integer length; excluding the decimal point
           if int_length > @digit_count
@@ -79,24 +82,12 @@ module Plurimath
             end
             round_base_string(fraction)
           elsif int_length < @digit_count
-            fraction + (DEFAULT_STRINGS[:zero] * (update_digit_count(fraction, precision) - int_length))
+            fraction + (DEFAULT_STRINGS[:zero] * (@digit_count - int_length))
           else
             fraction
           end
         end
 
-        def update_digit_count(number, precision)
-          return @digit_count unless zeros_count_in(number) == precision
-
-          @digit_count - precision + 1
-        end
-
-        def zeros_count_in(number)
-          return unless number.chars.all?(DEFAULT_STRINGS[:zero])
-
-          number.length
-        end
-
         def round_base_string(fraction)
           digits = fraction[0..frac_digit_count].chars
           discard_char = digits.pop

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

@@ -24,6 +24,9 @@ module Plurimath
         def format_groups(string)
           string = capitalize_hex_digits(string)
           string = pad_integer(string)
+          # group_digits: 0 disables grouping, mirroring fraction grouping.
+          return string unless groups.positive?
+
           tokens = []
 
           until string.empty?

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

@@ -44,7 +44,11 @@ module Plurimath
         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[0] = localize_parts(
+            source,
+            parts[0],
+            precision: engineering_precision(source, parts[0]),
+          )
           parts.join(" #{options.times} 10^")
         end
 
@@ -66,7 +70,10 @@ module Plurimath
         end
 
         def notation_parts(source)
-          return [source.to_parts(base: options.base), 0] if source.decimal.zero?
+          if source.decimal.zero?
+            return [source.to_parts(base: options.base),
+                    0]
+          end
 
           parts = source.to_parts(base: Base::DEFAULT_BASE)
           digits, exponent = significant_digits_and_exponent(parts)
@@ -87,7 +94,9 @@ module Plurimath
           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")
+          integer_digits = digits[0...integer_length].to_s.ljust(
+            integer_length, "0"
+          )
 
           [
             Parts.new(
@@ -100,10 +109,30 @@ module Plurimath
           ]
         end
 
-        def engineering_precision(source)
-          return precision if precision.positive?
+        # The inferred budget covers the source's significant digits; the
+        # engineering shift moves one to three of them into the integer part
+        # (per exponent mod 3), so the fraction budget must subtract the
+        # shifted integer width. Only a positive explicit precision is taken
+        # as a literal fraction width; precision: 0 falls through to inference.
+        def engineering_precision(source, coefficient)
+          # precision: 0 is intentionally not literal here; it infers.
+          return precision if options.explicit_precision? && precision.positive?
+          # Zero sources carry their stated fraction width; an explicit
+          # precision: 0 still infers (consistent with non-zero engineering).
+          return source.notation_precision if source.decimal.zero?
+
+          integer_length = coefficient.integer_digits.length
+          budget = [options.significant, options.digit_count].max
+          unless budget.positive?
+            return [source.significant_digit_count - integer_length,
+                    0].max
+          end
 
-          [source.significant_digit_count - 1, 0].max
+          fraction_budget = [budget - integer_length, 0].max
+          # Leave one digit for Significant's rounding pass when the source
+          # carries more digits than the requested budget.
+          fraction_budget += 1 if source.significant_digit_count > budget
+          fraction_budget
         end
 
         def significant_digits_and_exponent(parts)

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

@@ -26,15 +26,18 @@ module Plurimath
           render_precision = precision || options.precision || source_precision
           parts = source.to_parts(
             base: options.base,
-            precision: render_precision,
+            precision: decimal_precision_for(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,
-          )
+          decimal_precision = decimal_precision_for(precision)
+          unless decimal_precision.nil?
+            parts = parts.with_digits(
+              fraction_digits: parts.fraction_digits[0...decimal_precision.to_i].to_s,
+            )
+          end
           parts = renderable_parts(parts, precision: precision)
 
           parts = significant_format.apply_parts(parts) if significant_format.active?
@@ -60,6 +63,15 @@ module Plurimath
 
           source.fraction_digits.length
         end
+
+        # Precision budgets target-base digits, so the decimal fraction must
+        # stay intact until Fraction#change_base generates them; truncating
+        # decimal digits first loses value (0.07 in hex became 0x0.0).
+        def decimal_precision_for(precision)
+          return precision if options.base == Base::DEFAULT_BASE
+
+          nil
+        end
       end
     end
   end