string_to_number 0.1.4 → 0.2.0

data/lib/string_to_number/parser.rb

@@ -0,0 +1,230 @@
+# 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('|')})/
+    QUATRE_VINGT_PATTERN = /(quatre(-|\s)vingt(s?)((-|\s)dix)?)((-|\s)?)(\w*)/
+    
+    # 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
+
+        return 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], '')
+
+        return extract_optimized(sentence, keys) +
+               WORD_VALUES[normalize_str] + (WORD_VALUES[m[8]] || 0)
+      else
+        return 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?
 
+      # 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)
-        # Deleting matching element
+        # Remove the matched portion from sentence for further processing
         sentence.gsub!($&, '') if $&
 
-        # Extract matching element
-        factor          = EXCEPTIONS[result[:f]] || match(result[:f])
-        factor          = 1 if factor.zero?
+        # Parse the factor part (number before the multiplier)
+        # Example: "cinq" -> 5, "deux cent" -> 200
+        factor = EXCEPTIONS[result[:f]] || match(result[:f])
+        
+        # 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
 
+        # Final calculation: process any remaining sentence + current factor*multiplier
+        # Example: For "trois millions cinq cents", this handles the "cinq cents" part
         return extract(sentence, keys) + factor * multiple_of_ten
 
+      # 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 sum of: remaining sentence + normalized quatre-vingt value + any suffix
+        # Example: "quatre-vingt-cinq" -> EXCEPTIONS["quatre-vingt"] + EXCEPTIONS["cinq"]
         return extract(sentence, keys) +
                EXCEPTIONS[normalize_str] + (EXCEPTIONS[m[8]] || 0)
       else
+        # Fallback: use match() method for simple word combinations
         return 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
+          # 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,3 @@
 module StringToNumber
-  VERSION = '0.1.4'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/string_to_number.rb

@@ -1,10 +1,97 @@
 require 'string_to_number/version'
+
+# Load original implementation first for constant definitions
 require 'string_to_number/to_number'
 
+# Then load optimized implementation
+require 'string_to_number/parser'
+
 module StringToNumber
+  # Main interface for converting French text to numbers
+  #
+  # This module provides a simple interface to the high-performance French
+  # number parser with backward compatibility options.
+  #
+  # @example Basic usage
+  #   StringToNumber.in_numbers('vingt et un') #=> 21
+  #   StringToNumber.in_numbers('trois millions') #=> 3_000_000
+  #
+  # @example Backward compatibility
+  #   StringToNumber.in_numbers('cent', use_optimized: false) #=> 100
+  #
   class << self
-    def in_numbers(sentence)
-      StringToNumber::ToNumber.new(sentence).to_number
+    # Convert French text to number
+    #
+    # @param sentence [String] French number text to convert
+    # @param use_optimized [Boolean] Whether to use optimized parser (default: true)
+    # @return [Integer] The numeric value
+    # @raise [ArgumentError] if sentence is not convertible to string
+    #
+    # @example Standard usage
+    #   in_numbers('vingt et un') #=> 21
+    #
+    # @example Using original implementation
+    #   in_numbers('cent', use_optimized: false) #=> 100
+    #
+    def in_numbers(sentence, use_optimized: true)
+      if use_optimized
+        Parser.convert(sentence)
+      else
+        # Fallback to original implementation for compatibility testing
+        ToNumber.new(sentence).to_number
+      end
+    end
+
+    # Convert using original implementation (for compatibility testing)
+    #
+    # @param sentence [String] French text to convert
+    # @return [Integer] The numeric value
+    def in_numbers_original(sentence)
+      ToNumber.new(sentence).to_number
+    end
+
+    # Clear all internal caches
+    #
+    # Useful for testing, memory management, or when processing
+    # large volumes of unique inputs.
+    #
+    # @return [void]
+    def clear_caches!
+      Parser.clear_caches!
+    end
+
+    # Get cache performance statistics
+    #
+    # @return [Hash] Cache statistics including sizes and hit ratios
+    # @example
+    #   stats = StringToNumber.cache_stats
+    #   puts "Cache hit ratio: #{stats[:cache_hit_ratio]}"
+    #
+    def cache_stats
+      Parser.cache_stats
+    end
+
+    # Check if a string contains valid French number words
+    #
+    # @param text [String] Text to validate
+    # @return [Boolean] true if text appears to contain French numbers
+    #
+    def valid_french_number?(text)
+      return false unless text.respond_to?(:to_s)
+      
+      normalized = text.to_s.downcase.strip
+      return false if normalized.empty?
+      
+      # Check if any words are recognized French number words
+      words = normalized.tr('-', ' ').split(/\s+/)
+      recognized_words = words.count do |word|
+        word == 'et' || 
+        Parser::WORD_VALUES.key?(word) || 
+        Parser::MULTIPLIERS.key?(word)
+      end
+      
+      # Require at least 50% recognized words for validation
+      recognized_words.to_f / words.size >= 0.5
     end
   end
-end
+end