string_to_number 0.1.4 → 0.2.1

data/benchmark.rb

@@ -0,0 +1,178 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Performance benchmark script for StringToNumber gem
+# Run with: ruby benchmark.rb
+
+require_relative 'lib/string_to_number'
+require 'benchmark'
+
+class StringToNumberBenchmark
+  # Test data organized by complexity
+  TEST_CASES = {
+    simple: %w[
+      un vingt cent mille
+    ],
+    medium: [
+      'vingt et un', 'deux cent cinquante', 'mille deux cent'
+    ],
+    complex: [
+      'trois milliards cinq cents millions',
+      'soixante-quinze million trois cent quarante six mille sept cent quatre-vingt-dix neuf'
+    ],
+    edge_cases: %w[
+      VINGT une septante quatre-vingts
+    ]
+  }.freeze
+
+  def self.run_benchmark
+    puts 'StringToNumber Performance Benchmark'
+    puts '=' * 50
+    puts "Ruby version: #{RUBY_VERSION}"
+    puts "Platform: #{RUBY_PLATFORM}"
+    puts
+
+    # Warm up
+    puts 'Warming up...'
+    TEST_CASES.values.flatten.each { |text| StringToNumber.in_numbers(text) }
+    puts
+
+    total_results = {}
+
+    TEST_CASES.each do |category, test_cases|
+      puts "#{category.to_s.capitalize} Numbers:"
+      puts '-' * 30
+
+      results = benchmark_category(test_cases)
+      total_results[category] = results
+
+      puts "Cases: #{test_cases.size}"
+      puts "Total time: #{results[:total_time].round(4)}s"
+      puts "Average per conversion: #{results[:avg_time_ms].round(4)}ms"
+      puts "Conversions per second: #{results[:ops_per_sec].round(0)}"
+      puts
+
+      # Show individual case performance for complex numbers
+      next unless category == :complex
+
+      puts 'Individual case breakdown:'
+      test_cases.each_with_index do |text, index|
+        individual_time = Benchmark.realtime do
+          1000.times { StringToNumber.in_numbers(text) }
+        end
+        avg_ms = (individual_time / 1000) * 1000
+        puts "  #{index + 1}. #{avg_ms.round(4)}ms - '#{text[0..50]}#{'...' if text.length > 50}'"
+      end
+      puts
+    end
+
+    # Summary
+    puts '=' * 50
+    puts 'PERFORMANCE SUMMARY'
+    puts '=' * 50
+
+    total_results.each do |category, results|
+      status = case results[:avg_time_ms]
+               when 0..0.1 then '🟢 Excellent'
+               when 0.1..0.5 then '🟡 Good'
+               when 0.5..1.0 then '🟠 Acceptable'
+               else '🔴 Needs optimization'
+               end
+
+      puts "#{category.to_s.capitalize.ljust(12)} #{status.ljust(15)} #{results[:avg_time_ms].round(4)}ms avg"
+    end
+
+    puts
+    puts 'Memory efficiency test...'
+    test_memory_usage
+
+    puts
+    puts 'Scalability test...'
+    test_scalability
+  end
+
+  def self.benchmark_category(test_cases, iterations = 2000)
+    total_time = Benchmark.realtime do
+      test_cases.each do |text|
+        iterations.times do
+          StringToNumber.in_numbers(text)
+        end
+      end
+    end
+
+    total_conversions = test_cases.size * iterations
+    avg_time_ms = (total_time / total_conversions) * 1000
+    ops_per_sec = total_conversions / total_time
+
+    {
+      total_time: total_time,
+      avg_time_ms: avg_time_ms,
+      ops_per_sec: ops_per_sec
+    }
+  end
+
+  def self.test_memory_usage
+    # Test memory efficiency
+    if Object.const_defined?(:ObjectSpace)
+      GC.start
+      initial_objects = ObjectSpace.count_objects[:TOTAL]
+
+      # Perform intensive operations
+      500.times do
+        TEST_CASES.values.flatten.each { |text| StringToNumber.in_numbers(text) }
+      end
+
+      GC.start
+      final_objects = ObjectSpace.count_objects[:TOTAL]
+      object_growth = final_objects - initial_objects
+
+      puts "Object creation: #{object_growth} new objects (#{object_growth > 1000 ? '🔴 High' : '🟢 Low'})"
+    else
+      puts 'Memory tracking not available on this platform'
+    end
+  end
+
+  def self.test_scalability
+    # Test how performance scales with input complexity
+    inputs = [
+      'un',                                                           # 2 chars
+      'vingt et un',                                                  # 11 chars
+      'mille deux cent trente-quatre',                               # 29 chars
+      'trois milliards cinq cents millions deux cent mille et une'   # 58 chars
+    ]
+
+    puts 'Input length vs. performance:'
+
+    results = inputs.map do |input|
+      time = Benchmark.realtime do
+        1000.times { StringToNumber.in_numbers(input) }
+      end
+      avg_ms = (time / 1000) * 1000
+
+      { length: input.length, time: avg_ms, input: input }
+    end
+
+    results.each do |result|
+      complexity_ratio = result[:time] / results.first[:time]
+      status = if complexity_ratio < 5
+                 '🟢'
+               else
+                 complexity_ratio < 10 ? '🟡' : '🔴'
+               end
+
+      puts "  #{result[:length].to_s.rjust(2)} chars: #{result[:time].round(4)}ms #{status} " \
+           "(#{complexity_ratio.round(1)}x baseline)"
+    end
+
+    # Check if performance degrades reasonably
+    worst_ratio = results.last[:time] / results.first[:time]
+    if worst_ratio < 10
+      puts "✅ Scalability: Good (#{worst_ratio.round(1)}x degradation)"
+    else
+      puts "❌ Scalability: Poor (#{worst_ratio.round(1)}x degradation)"
+    end
+  end
+end
+
+# Run the benchmark
+StringToNumberBenchmark.run_benchmark if __FILE__ == $PROGRAM_NAME

data/lib/string_to_number/parser.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module StringToNumber
+  # High-performance French text to number parser
+  #
+  # This class provides a clean, optimized implementation that maintains
+  # compatibility with the original algorithm while adding significant
+  # performance improvements through caching and memoization.
+  #
+  # @example Basic usage
+  #   parser = StringToNumber::Parser.new
+  #   parser.parse('vingt et un')  #=> 21
+  #   parser.parse('trois millions') #=> 3_000_000
+  #
+  # @example Class method usage
+  #   StringToNumber::Parser.convert('mille deux cent') #=> 1200
+  #
+  class Parser
+    # Import the proven data structures from the original implementation
+    WORD_VALUES = StringToNumber::ToNumber::EXCEPTIONS.freeze
+    MULTIPLIERS = StringToNumber::ToNumber::POWERS_OF_TEN.freeze
+
+    # Pre-compiled regex patterns for optimal performance
+    MULTIPLIER_KEYS = MULTIPLIERS.keys.reject { |k| %w[un dix].include?(k) }
+                                 .sort_by(&:length).reverse.freeze
+    MULTIPLIER_PATTERN = /(?<f>.*?)\s?(?<m>#{MULTIPLIER_KEYS.join('|')})/.freeze
+    QUATRE_VINGT_PATTERN = /(quatre(-|\s)vingt(s?)((-|\s)dix)?)((-|\s)?)(\w*)/.freeze
+
+    # Cache configuration
+    MAX_CACHE_SIZE = 1000
+    private_constant :MAX_CACHE_SIZE
+
+    # Thread-safe class-level caches
+    @conversion_cache = {}
+    @cache_access_order = []
+    @instance_cache = {}
+    @cache_mutex = Mutex.new
+    @instance_mutex = Mutex.new
+
+    class << self
+      # Convert French text to number using cached parser instance
+      #
+      # @param text [String] French number text to convert
+      # @return [Integer] The numeric value
+      # @raise [ArgumentError] if text is not a string
+      def convert(text)
+        validate_input!(text)
+
+        normalized = normalize_text(text)
+        return 0 if normalized.empty?
+
+        # Check conversion cache first
+        cached_result = get_cached_conversion(normalized)
+        return cached_result if cached_result
+
+        # Get or create parser instance and convert
+        parser = get_cached_instance(normalized)
+        result = parser.parse_optimized(normalized)
+
+        # Cache the result
+        cache_conversion(normalized, result)
+        result
+      end
+
+      # Clear all caches
+      def clear_caches!
+        @cache_mutex.synchronize do
+          @conversion_cache.clear
+          @cache_access_order.clear
+        end
+
+        @instance_mutex.synchronize do
+          @instance_cache.clear
+        end
+      end
+
+      # Get cache statistics
+      def cache_stats
+        @cache_mutex.synchronize do
+          {
+            conversion_cache_size: @conversion_cache.size,
+            conversion_cache_limit: MAX_CACHE_SIZE,
+            instance_cache_size: @instance_cache.size,
+            cache_hit_ratio: calculate_hit_ratio
+          }
+        end
+      end
+
+      private
+
+      def validate_input!(text)
+        raise ArgumentError, 'Input must be a string' unless text.respond_to?(:to_s)
+      end
+
+      def normalize_text(text)
+        text.to_s.downcase.strip
+      end
+
+      def get_cached_conversion(normalized_text)
+        @cache_mutex.synchronize do
+          if @conversion_cache.key?(normalized_text)
+            # Update LRU order
+            @cache_access_order.delete(normalized_text)
+            @cache_access_order.push(normalized_text)
+            return @conversion_cache[normalized_text]
+          end
+        end
+        nil
+      end
+
+      def cache_conversion(normalized_text, result)
+        @cache_mutex.synchronize do
+          # LRU eviction
+          if @conversion_cache.size >= MAX_CACHE_SIZE
+            oldest = @cache_access_order.shift
+            @conversion_cache.delete(oldest)
+          end
+
+          @conversion_cache[normalized_text] = result
+          @cache_access_order.push(normalized_text)
+        end
+      end
+
+      def get_cached_instance(normalized_text)
+        @instance_mutex.synchronize do
+          @instance_cache[normalized_text] ||= new(normalized_text)
+        end
+      end
+
+      def calculate_hit_ratio
+        return 0.0 if @cache_access_order.empty?
+
+        @conversion_cache.size.to_f / @cache_access_order.size
+      end
+    end
+
+    # Initialize parser with normalized text
+    def initialize(text = '')
+      @normalized_text = self.class.send(:normalize_text, text)
+    end
+
+    # Parse the text to numeric value
+    def parse
+      self.class.convert(@normalized_text)
+    end
+
+    # Internal optimized parsing method using the original proven algorithm
+    # but with performance optimizations
+    def parse_optimized(text)
+      return 0 if text.nil? || text.empty?
+
+      # Direct lookup (fastest path)
+      return WORD_VALUES[text] if WORD_VALUES.key?(text)
+
+      # Use the proven extraction algorithm from the original implementation
+      extract_optimized(text, MULTIPLIER_KEYS.join('|'))
+    end
+
+    private
+
+    # Optimized version of the original extract method
+    # This maintains the exact logic of the working implementation
+    # but with performance improvements
+    def extract_optimized(sentence, keys, detail: false)
+      return 0 if sentence.nil? || sentence.empty?
+
+      # Direct lookup
+      return WORD_VALUES[sentence] if WORD_VALUES.key?(sentence)
+
+      # Main pattern matching using pre-compiled regex
+      if (result = MULTIPLIER_PATTERN.match(sentence))
+        # Remove matched portion
+        sentence = sentence.gsub(result[0], '') if result[0]
+
+        # Extract factor
+        factor = WORD_VALUES[result[:f]] || match_optimized(result[:f])
+        factor = 1 if factor.zero? && !detail
+        multiple_of_ten = 10**(MULTIPLIERS[result[:m]] || 0)
+
+        # Handle compound numbers
+        if higher_multiple_exists?(result[:m], sentence)
+          details = extract_optimized(sentence, keys, detail: true)
+          factor = (factor * multiple_of_ten) + details[:factor]
+          multiple_of_ten = details[:multiple_of_ten]
+          sentence = details[:sentence]
+        end
+
+        # Return based on mode
+        if detail
+          return {
+            factor: factor,
+            multiple_of_ten: multiple_of_ten,
+            sentence: sentence
+          }
+        end
+
+        extract_optimized(sentence, keys) + (factor * multiple_of_ten)
+
+      # Quatre-vingt special handling
+      elsif (m = QUATRE_VINGT_PATTERN.match(sentence))
+        normalize_str = m[1].tr(' ', '-')
+        normalize_str = normalize_str[0...-1] if normalize_str[-1] == 's'
+
+        sentence = sentence.gsub(m[0], '')
+
+        extract_optimized(sentence, keys) +
+          WORD_VALUES[normalize_str] + (WORD_VALUES[m[8]] || 0)
+      else
+        match_optimized(sentence)
+      end
+    end
+
+    # Optimized match method
+    def match_optimized(sentence)
+      return 0 if sentence.nil?
+
+      sentence.tr('-', ' ').split.reverse.sum do |word|
+        next 0 if word == 'et'
+
+        WORD_VALUES[word] || (MULTIPLIERS[word] ? 10 * MULTIPLIERS[word] : 0)
+      end
+    end
+
+    # Optimized higher multiple check
+    def higher_multiple_exists?(multiple, sentence)
+      current_power = MULTIPLIERS[multiple]
+      MULTIPLIERS.any? do |word, power|
+        power > current_power && sentence.include?(word)
+      end
+    end
+  end
+end

data/lib/string_to_number/to_number.rb

@@ -1,13 +1,23 @@
 # frozen_string_literal: true
 
 module StringToNumber
+  # ToNumber class handles the conversion of French text to numbers
+  # It uses a complex recursive parsing algorithm to handle French number grammar
   class ToNumber
     attr_accessor :sentence, :keys
 
+    # EXCEPTIONS contains direct mappings from French words to their numeric values
+    # This includes:
+    # - Basic numbers 0-90
+    # - Feminine forms ("une" for "un")
+    # - Regional variations (Belgian/Swiss French: "septante", "huitante", "nonante")
+    # - Special cases for "quatre-vingt" variations with/without 's'
+    # - Compound numbers like "dix-sept", "soixante-dix"
     EXCEPTIONS = {
-      'zéro' => 0,
-      'zero' => 0,
-      'un' => 1,
+      'zéro' => 0,    # Zero with accent
+      'zero' => 0,    # Zero without accent
+      'un' => 1,      # Masculine "one"
+      'une' => 1,     # Feminine "one"
       'deux' => 2,
       'trois' => 3,
       'quatre' => 4,
@@ -23,29 +33,44 @@ module StringToNumber
       'quatorze' => 14,
       'quinze' => 15,
       'seize' => 16,
-      'dix-sept' => 17,
-      'dix-huit' => 18,
-      'dix-neuf' => 19,
+      'dix-sept' => 17,   # Compound: "ten-seven"
+      'dix-huit' => 18,   # Compound: "ten-eight"
+      'dix-neuf' => 19,   # Compound: "ten-nine"
       'vingt' => 20,
       'trente' => 30,
       'quarante' => 40,
       'cinquante' => 50,
       'soixante' => 60,
-      'soixante-dix' => 70,
-      'quatre-vingts' => 80,
-      'quatre-vingt' => 80,
-      'quatre-vingt-dix' => 90,
-      'quatre-vingts-dix' => 90
+      'soixante-dix' => 70,     # Standard French: "sixty-ten"
+      'septante' => 70,         # Belgian/Swiss French alternative
+      'quatre-vingts' => 80,    # Standard French: "four-twenties" (plural)
+      'quatre-vingt' => 80,     # Standard French: "four-twenty" (singular)
+      'huitante' => 80,         # Swiss French alternative
+      'quatre-vingt-dix' => 90, # Standard French: "four-twenty-ten"
+      'quatre-vingts-dix' => 90, # Alternative with plural "vingts"
+      'nonante' => 90 # Belgian/Swiss French alternative
     }.freeze
 
+    # POWERS_OF_TEN maps French number words to their power of 10 exponents
+    # Used for multipliers like "cent" (10^2), "mille" (10^3), "million" (10^6)
+    # Includes both singular and plural forms for proper French grammar
+    # Uses French number scale where "billion" = 10^12 (not 10^9 as in English)
     POWERS_OF_TEN = {
-      'un' => 0,
-      'dix' => 1,
-      'cent' => 2,
-      'mille' => 3,
-      'million' => 6,
-      'billion' => 9,
-      'trillion' => 12,
+      'un' => 0,           # 10^0 = 1 (ones place)
+      'dix' => 1,          # 10^1 = 10 (tens place)
+      'cent' => 2,         # 10^2 = 100 (hundreds, singular)
+      'cents' => 2,        # 10^2 = 100 (hundreds, plural)
+      'mille' => 3,        # 10^3 = 1,000 (thousands, singular)
+      'milles' => 3,       # 10^3 = 1,000 (thousands, plural)
+      'million' => 6,      # 10^6 = 1,000,000 (millions, singular)
+      'millions' => 6,     # 10^6 = 1,000,000 (millions, plural)
+      'milliard' => 9,     # 10^9 = 1,000,000,000 (French billion, singular)
+      'milliards' => 9,    # 10^9 = 1,000,000,000 (French billion, plural)
+      'billion' => 12,     # 10^12 = 1,000,000,000,000 (French trillion, singular)
+      'billions' => 12,    # 10^12 = 1,000,000,000,000 (French trillion, plural)
+      'trillion' => 15,    # 10^15 (French quadrillion, singular)
+      'trillions' => 15,   # 10^15 (French quadrillion, plural)
+      # Extended list of large number names for completeness
       'quadrillion' => 15,
       'quintillion' => 18,
       'sextillion' => 21,
@@ -75,42 +100,88 @@ module StringToNumber
       'trigintillion' => 93,
       'untrigintillion' => 96,
       'duotrigintillion' => 99,
-      'googol' => 100
+      'googol' => 100 # Special case: 10^100
     }.freeze
 
+    # Initialize the ToNumber parser with a French sentence
+    # @param sentence [String] The French text to be converted to numbers
     def initialize(sentence = '')
-      @keys = POWERS_OF_TEN.keys.reject { |k| %w[un dix].include?(k) }.join('|')
-      @sentence = sentence
+      # Create regex pattern from POWERS_OF_TEN keys, excluding 'un' and 'dix'
+      # which are handled differently in the parsing logic
+      # Sort keys by length (longest first) to ensure longer matches are preferred
+      # This prevents "cent" from matching before "cents" in "cinq cents"
+      sorted_keys = POWERS_OF_TEN.keys.reject { |k| %w[un dix].include?(k) }.sort_by(&:length).reverse
+      @keys = sorted_keys.join('|') # Create regex alternation pattern
+      # Normalize input to lowercase for case-insensitive matching
+      @sentence = sentence&.downcase || ''
     end
 
+    # Main entry point to convert the French sentence to a number
+    # @return [Integer] The numeric value of the French text
     def to_number
       extract(@sentence, keys)
     end
 
     private
 
+    # Main recursive extraction method that parses French number patterns
+    # This is the core of the parsing algorithm
+    # @param sentence [String] The French text to parse
+    # @param keys [String] Regex pattern of power-of-ten multipliers
+    # @param detail [Boolean] If true, returns detailed parsing info for recursion
+    # @return [Integer, Hash] Numeric value or detailed parsing hash
     def extract(sentence, keys, detail: false)
+      # Base cases: handle empty/nil input
       return 0 if sentence.nil? || sentence.empty?
+
+      # Ensure case-insensitive matching
+      sentence = sentence.downcase
+
+      # Direct lookup for simple cases (e.g., "vingt" -> 20)
       return EXCEPTIONS[sentence] unless EXCEPTIONS[sentence].nil?
 
-      if result = /(?<f>.*?)\s?(?<m>#{keys})/.match(sentence)
-        # Deleting matching element
-        sentence.gsub!($&, '') if $&
+      # Main parsing logic: look for pattern "factor + multiplier"
+      # Example: "cinq cents" -> factor="cinq", multiplier="cents"
+      # Regex explanation:
+      #   (?<f>.*?) - Non-greedy capture of factor part (before multiplier)
+      #   \s?       - Optional space
+      #   (?<m>#{keys}) - Named capture of multiplier from keys pattern
+      if (result = /(?<f>.*?)\s?(?<m>#{keys})/.match(sentence))
+        # Remove the matched portion from sentence for further processing
+        sentence.gsub!(::Regexp.last_match(0), '') if ::Regexp.last_match(0)
+
+        # Parse the factor part (number before the multiplier)
+        # Example: "cinq" -> 5, "deux cent" -> 200
+        factor = EXCEPTIONS[result[:f]] || match(result[:f])
 
-        # Extract matching element
-        factor          = EXCEPTIONS[result[:f]] || match(result[:f])
-        factor          = 1 if factor.zero?
+        # Handle implicit factor of 1 for standalone multipliers
+        # Example: "million" -> factor=1, but only for top-level calls
+        # For recursive calls (detail=true), keep factor as 0 to avoid double-counting
+        factor = 1 if factor.zero? && !detail
+
+        # Calculate the multiplier value (10^exponent)
+        # Example: "cents" -> 10^2 = 100, "millions" -> 10^6 = 1,000,000
         multiple_of_ten = 10**(POWERS_OF_TEN[result[:m]] || 0)
 
-        # Check if this multiple is over
+        # Handle compound numbers with higher-order multipliers
+        # Example: "cinq cents millions" - after matching "cinq cents",
+        # check if "millions" (a higher multiplier than "cents") remains
         if /#{higher_multiple(result[:m]).keys.join('|')}/.match(sentence)
+          # Recursively process the higher multiplier
           details = extract(sentence, keys, detail: true)
 
-          factor          = (factor * multiple_of_ten) + details[:factor]
+          # Combine the current factor*multiplier with the higher multiplier
+          # Example: For "cinq cents millions":
+          #   - factor = 5, multiple_of_ten = 100 (from "cinq cents")
+          #   - details[:factor] = 0, details[:multiple_of_ten] = 1000000 (from "millions")
+          #   - result: factor = (5 * 100) + 0 = 500, multiple_of_ten = 1000000
+          #   - final: 500 * 1000000 = 500,000,000
+          factor = (factor * multiple_of_ten) + details[:factor]
           multiple_of_ten = details[:multiple_of_ten]
-          sentence        = details[:sentence]
+          sentence = details[:sentence]
         end
 
+        # Return detailed parsing info for recursive calls
         if detail
           return {
             factor: factor,
@@ -119,33 +190,69 @@ module StringToNumber
           }
         end
 
-        return extract(sentence, keys) + factor * multiple_of_ten
+        # Final calculation: process any remaining sentence + current factor*multiplier
+        # Example: For "trois millions cinq cents", this handles the "cinq cents" part
+        extract(sentence, keys) + (factor * multiple_of_ten)
 
-      elsif m = /(quatre(-|\s)vingt(s?)((-|\s)dix)?)((-|\s)?)(\w*)/.match(sentence)
+      # Special case handling for "quatre-vingt" variations
+      # This complex regex handles the irregular French "eighty" patterns:
+      # - "quatre-vingt" / "quatre vingts" (with/without 's')
+      # - "quatre-vingt-dix" / "quatre vingts dix" (90)
+      # - Space vs hyphen variations
+      elsif (m = /(quatre(-|\s)vingt(s?)((-|\s)dix)?)((-|\s)?)(\w*)/.match(sentence))
+        # Normalize spacing to hyphens for consistent lookup
         normalize_str = m[1].tr(' ', '-')
-        normalize_str = normalize_str[0...-1] if normalize_str[normalize_str.length] == 's'
 
+        # Remove trailing 's' from "quatre-vingts" if present
+        # Bug fix: use [-1] instead of [length] for last character
+        normalize_str = normalize_str[0...-1] if normalize_str[-1] == 's'
+
+        # Remove the matched portion from sentence
         sentence.gsub!(m[0], '')
 
-        return extract(sentence, keys) +
-               EXCEPTIONS[normalize_str] + (EXCEPTIONS[m[8]] || 0)
+        # Return sum of: remaining sentence + normalized quatre-vingt value + any suffix
+        # Example: "quatre-vingt-cinq" -> EXCEPTIONS["quatre-vingt"] + EXCEPTIONS["cinq"]
+        extract(sentence, keys) +
+          EXCEPTIONS[normalize_str] + (EXCEPTIONS[m[8]] || 0)
       else
-        return match(sentence)
+        # Fallback: use match() method for simple word combinations
+        match(sentence)
       end
     end
 
+    # Fallback method for parsing simple word sequences
+    # Used when the main extract() method can't find multiplier patterns
+    # @param sentence [String] French text to parse as individual words
+    # @return [Integer, nil] Sum of individual word values or nil if no sentence
     def match(sentence)
       return if sentence.nil?
 
-      sentence.tr('-', ' ').split(' ').reverse.sum do |word|
+      # Process words in reverse order for proper French number logic
+      # Example: "vingt et un" -> ["un", "et", "vingt"] -> 1 + 0 + 20 = 21
+      sentence.downcase.tr('-', ' ').split.reverse.sum do |word|
+        # Handle French "et" (and) conjunction by ignoring it in calculations
+        # Example: "vingt et un" -> ignore "et", sum "vingt" + "un"
+        next 0 if word == 'et'
+
+        # Look up word value in either EXCEPTIONS or POWERS_OF_TEN
         if EXCEPTIONS[word].nil? && POWERS_OF_TEN[word].nil?
+          # Unknown words contribute 0 to the sum
           0
         else
-          (EXCEPTIONS[word] || (10 * POWERS_OF_TEN[word]))
+          # Use EXCEPTIONS value if available, otherwise use 10 * power_of_ten
+          # Example: "dix" -> EXCEPTIONS["dix"] = 10
+          #          "cent" -> 10 * POWERS_OF_TEN["cent"] = 10 * 2 = 100
+          EXCEPTIONS[word] || (10 * POWERS_OF_TEN[word])
         end
       end
     end
 
+    # Helper method to find multipliers with higher powers than the given one
+    # Used to detect when compound numbers have higher-order multipliers
+    # @param multiple [String] The current multiplier word (e.g., "cents")
+    # @return [Hash] Hash of multipliers with higher powers of 10
+    # Example: higher_multiple("cents") returns {"mille"=>3, "million"=>6, ...}
+    #          because 10^3, 10^6, etc. are all > 10^2 (cents)
     def higher_multiple(multiple)
       POWERS_OF_TEN.select do |_k, v|
         v > POWERS_OF_TEN[multiple]

data/lib/string_to_number/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StringToNumber
-  VERSION = '0.1.4'.freeze
+  VERSION = '0.2.1'
 end