human_number 0.1.10 → 0.2.1

data/lib/human_number/number_system.rb

@@ -0,0 +1,657 @@
+# frozen_string_literal: true
+
+require "action_view"
+require "i18n"
+
+module HumanNumber
+  # Number system determination and formatting for international standards compliance.
+  #
+  # This module provides the core logic for determining which number formatting system
+  # to use based on locale or currency context. It supports three distinct number
+  # systems that align with different cultural and linguistic number naming conventions:
+  #
+  # * **Default System** (Western): thousand, million, billion, trillion (K/M/B/T)
+  # * **East Asian System**: ten thousand (만/万), hundred million (억/億), trillion (조/兆)
+  # * **Indian System**: thousand, lakh, crore
+  #
+  # The module automatically maps locales and currencies to their culturally
+  # appropriate number system, ensuring that formatted numbers follow the
+  # conventions expected by users in different regions.
+  #
+  # @example Determining number system by locale
+  #   HumanNumber::NumberSystem.number_system(locale: :en)     #=> :default
+  #   HumanNumber::NumberSystem.number_system(locale: :ko)     #=> :east_asian
+  #   HumanNumber::NumberSystem.number_system(locale: :hi)     #=> :indian
+  #
+  # @example Determining number system by currency
+  #   HumanNumber::NumberSystem.currency_number_system(currency_code: 'USD')  #=> :default
+  #   HumanNumber::NumberSystem.currency_number_system(currency_code: 'KRW')  #=> :east_asian
+  #   HumanNumber::NumberSystem.currency_number_system(currency_code: 'INR')  #=> :indian
+  #
+  # @see HumanNumber.number_system
+  # @see HumanNumber.currency_number_system
+  # @since 0.1.10
+  module NumberSystem
+    # Currency-to-number-system mapping for culturally appropriate formatting.
+    #
+    # Maps ISO 4217 currency codes to their regionally appropriate number
+    # formatting systems. Currencies not listed default to the Western system.
+    #
+    # @example East Asian currencies (powers of 10,000 progression)
+    #   'KRW' => Korean Won, 'JPY' => Japanese Yen, 'CNY' => Chinese Yuan
+    #   'SGD' => Singapore Dollar, 'HKD' => Hong Kong Dollar
+    #
+    # @example Indian subcontinent currencies (lakh/crore system)
+    #   'INR' => Indian Rupee
+    #
+    # @see currency_number_system
+    CURRENCY_SYSTEM_MAPPING = {
+      east_asian: %w[KRW JPY CNY SGD HKD].freeze,
+      indian: %w[INR].freeze,
+      # All other currencies use the default system (K/M/B/T)
+    }.freeze
+
+    # Locale-to-number-system mapping for linguistic and cultural consistency.
+    #
+    # Maps locale identifiers to their culturally appropriate number formatting
+    # systems, considering how speakers of each language conceptualize and
+    # express large numbers. Locales not listed default to the Western system.
+    #
+    # @example East Asian locales (万/億/兆 or 만/억/조 progression)
+    #   :ko => Korean, :ja => Japanese, :zh => Chinese (generic)
+    #   :'zh-CN' => Chinese (Simplified), :'zh-TW' => Chinese (Traditional)
+    #
+    # @example Indian subcontinent locales (thousand/lakh/crore progression)
+    #   :hi => Hindi, :ur => Urdu, :bn => Bengali, :'en-IN' => Indian English
+    #
+    # @see number_system
+    LOCALE_SYSTEM_MAPPING = {
+      east_asian: %i[ko ja zh zh-CN zh-TW].freeze,
+      indian: %i[hi ur bn en-IN].freeze,
+      # All other locales use the default system (K/M/B/T)
+    }.freeze
+
+    module_function
+
+    # Determines the appropriate number system for a given locale.
+    #
+    # This method maps locale codes to their culturally appropriate number
+    # formatting system. It considers regional numbering conventions and
+    # linguistic patterns to select the most suitable system.
+    #
+    # @param locale [Symbol, String, nil] The locale code to evaluate.
+    #   When nil, defaults to the current I18n.locale setting.
+    #   Accepts both symbol and string formats (e.g., :ko or 'ko').
+    #
+    # @return [Symbol] The number system identifier:
+    #   * `:default` - Western system using K/M/B/T (thousand/million/billion/trillion)
+    #   * `:east_asian` - Asian system using 만/억/조 or 万/億/兆 patterns
+    #   * `:indian` - South Asian system using thousand/lakh/crore
+    #
+    # @example Basic locale determination
+    #   NumberSystem.number_system(locale: :en)        #=> :default
+    #   NumberSystem.number_system(locale: :ko)        #=> :east_asian
+    #   NumberSystem.number_system(locale: :hi)        #=> :indian
+    #
+    # @example Regional locale variants
+    #   NumberSystem.number_system(locale: :'zh-CN')   #=> :east_asian
+    #   NumberSystem.number_system(locale: :'zh-TW')   #=> :east_asian
+    #   NumberSystem.number_system(locale: :'en-IN')   #=> :indian
+    #
+    # @example String input and nil handling
+    #   NumberSystem.number_system(locale: 'ja')       #=> :east_asian
+    #   NumberSystem.number_system(locale: nil)        #=> (uses I18n.locale)
+    #
+    # @example Unknown locales default to Western system
+    #   NumberSystem.number_system(locale: :unknown)   #=> :default
+    #   NumberSystem.number_system(locale: :xyz)       #=> :default
+    #
+    # @see LOCALE_SYSTEM_MAPPING
+    # @since 0.1.10
+    def number_system(locale: I18n.locale)
+      locale = (locale || I18n.locale).to_sym
+
+      LOCALE_SYSTEM_MAPPING.each do |system, locales|
+        return system if locales.include?(locale)
+      end
+
+      :default
+    end
+
+    # Determines the appropriate number system for a given currency code.
+    #
+    # This method maps ISO 4217 currency codes to their culturally and
+    # geographically appropriate number formatting systems. It considers
+    # the regional context where the currency is primarily used and the
+    # number formatting conventions of those regions.
+    #
+    # @param currency_code [String, nil] The ISO 4217 currency code to evaluate.
+    #   Expected format is 3-letter uppercase (e.g., 'USD', 'EUR', 'KRW').
+    #   Case-insensitive and handles whitespace automatically.
+    #   When nil, returns `:default`.
+    #
+    # @return [Symbol] The number system identifier:
+    #   * `:default` - Western system for most global currencies (USD, EUR, GBP, etc.)
+    #   * `:east_asian` - Asian system for East Asian currencies (KRW, JPY, CNY, etc.)
+    #   * `:indian` - South Asian system for Indian subcontinent currencies (INR)
+    #
+    # @example Major currency mappings
+    #   NumberSystem.currency_number_system(currency_code: 'USD')   #=> :default
+    #   NumberSystem.currency_number_system(currency_code: 'EUR')   #=> :default
+    #   NumberSystem.currency_number_system(currency_code: 'KRW')   #=> :east_asian
+    #   NumberSystem.currency_number_system(currency_code: 'JPY')   #=> :east_asian
+    #   NumberSystem.currency_number_system(currency_code: 'INR')   #=> :indian
+    #
+    # @example East Asian currencies
+    #   NumberSystem.currency_number_system(currency_code: 'CNY')   #=> :east_asian  # Chinese Yuan
+    #   NumberSystem.currency_number_system(currency_code: 'SGD')   #=> :east_asian  # Singapore Dollar
+    #   NumberSystem.currency_number_system(currency_code: 'HKD')   #=> :east_asian  # Hong Kong Dollar
+    #
+    # @example Case handling and whitespace
+    #   NumberSystem.currency_number_system(currency_code: 'krw')   #=> :east_asian  # lowercase
+    #   NumberSystem.currency_number_system(currency_code: ' USD ') #=> :default     # with spaces
+    #   NumberSystem.currency_number_system(currency_code: 'KrW')   #=> :east_asian  # mixed case
+    #
+    # @example Edge cases and unknown currencies
+    #   NumberSystem.currency_number_system(currency_code: nil)     #=> :default
+    #   NumberSystem.currency_number_system(currency_code: '')      #=> :default
+    #   NumberSystem.currency_number_system(currency_code: 'XYZ')   #=> :default  # unknown
+    #
+    # @see CURRENCY_SYSTEM_MAPPING
+    # @see https://en.wikipedia.org/wiki/ISO_4217
+    # @since 0.1.10
+    def currency_number_system(currency_code:)
+      return :default unless currency_code
+
+      currency_code = currency_code.upcase.strip
+
+      CURRENCY_SYSTEM_MAPPING.each do |system, currencies|
+        return system if currencies.include?(currency_code)
+      end
+
+      :default
+    end
+  end
+
+  # Constants for string literals and magic numbers used by system classes
+  ZERO_STRING = "0"
+  EMPTY_SEPARATOR = ""
+  SPACE_SEPARATOR = " "
+  DECIMAL_FORMAT_TEMPLATE = "%.%df"
+  MINIMUM_UNIT_COUNT = 1.0
+  SINGLE_DIGIT_LIMIT = 1
+
+  # I18n key templates
+  I18N_DECIMAL_UNITS_KEY = "number.human.decimal_units"
+  I18N_ABBR_UNITS_SECTION = "abbr_units"
+  I18N_UNITS_SECTION = "units"
+
+  module NumberSystem
+    # Western/Default number formatting system using standard thousand-based units.
+    #
+    # This system implements the standard Western number formatting convention
+    # using powers of 1000 progression: thousand, million, billion, trillion.
+    # It's used by most Western languages and global financial contexts.
+    #
+    # @example Formatting examples
+    #   # Via HumanNumber.human_number (using :en locale)
+    #   HumanNumber.human_number(1_234)         #=> "1K 234"
+    #   HumanNumber.human_number(1_234_567)     #=> "1M 234K 567"
+    #   HumanNumber.human_number(1_234_567_890) #=> "1B 234M 567K 890"
+    #
+    #   # Abbreviated mode
+    #   HumanNumber.human_number(1_234_567, max_digits: 2) #=> "1.2M"
+    #
+    # @example Supported locales
+    #   # European languages: English, German, French, Spanish, Italian, etc.
+    #   [:en, :de, :fr, :es, :it, :pt, :ru, :nl, :sv, :da, :no]
+    #
+    # @see UNIT_DEFINITIONS
+    # @since 0.1.10
+    class DefaultSystem
+      extend ActionView::Helpers::NumberHelper
+
+      UNIT_DEFINITIONS = [
+        { key: :trillion, divisor: 1_000_000_000_000 },
+        { key: :billion, divisor: 1_000_000_000 },
+        { key: :million, divisor: 1_000_000 },
+        { key: :thousand, divisor: 1_000 },
+      ].freeze
+
+      class << self
+        def format_number(number, locale:, abbr_units: true, min_unit: nil, max_digits: 2, trim_zeros: true)
+          return ZERO_STRING if number.zero?
+
+          # Check if number meets minimum unit threshold for human formatting
+          return format_below_min_unit(number, locale) if min_unit && number.abs < min_unit
+
+          parts = if max_digits.nil?
+                    format_in_complete_mode(number, locale, abbr_units, min_unit)
+                  else
+                    format_in_abbreviated_mode(number, locale, abbr_units, max_digits, trim_zeros, min_unit)
+                  end
+
+          return number.to_s if parts.nil?
+
+          finalize_result(number, parts)
+        end
+
+        def format_in_complete_mode(number, locale, abbr_units, _min_unit)
+          # Complete mode shows all units: "1M 234K 567"
+          unit_breakdown = break_down_into_all_units(number)
+          return nil if unit_breakdown.empty?
+
+          format_all_unit_parts(unit_breakdown, locale, abbr_units)
+        end
+
+        def format_in_abbreviated_mode(number, locale, abbr_units, max_digits, trim_zeros, _min_unit)
+          # Abbreviated mode shows single largest unit: "1.2M"
+          unit_breakdown = break_down_into_largest_unit(number)
+          return nil if unit_breakdown.empty?
+
+          format_abbreviated_unit_parts(unit_breakdown, locale, abbr_units, max_digits, trim_zeros)
+        end
+
+        # Format numbers below min_unit threshold with locale-appropriate delimiters
+        def format_below_min_unit(number, locale)
+          number_with_delimiter(number, locale: locale) || number.to_s
+        end
+
+        private
+
+        def breakdown_number(number)
+          result = []
+          remaining = number.abs
+
+          unit_definitions.each do |unit|
+            next unless remaining >= unit[:divisor]
+
+            count = remaining.to_f / unit[:divisor]
+            result << { unit_key: unit[:key], count: count, divisor: unit[:divisor] }
+            break # Only use the largest applicable unit
+          end
+
+          # If no unit matched, use the raw number
+          result << { unit_key: :units, count: remaining, divisor: 1 } if result.empty?
+
+          result
+        end
+
+        # Find the largest applicable unit for abbreviated display
+        # Example: 1,234,567 -> [{million: 1.234567}]
+        def break_down_into_largest_unit(number)
+          absolute_amount = number.abs
+
+          # Find the first (largest) unit where the count would be >= 1.0
+          unit_definitions.each do |unit|
+            unit_count = absolute_amount.to_f / unit[:divisor]
+
+            return [create_unit_part(unit[:key], unit_count, unit[:divisor])] if unit_count >= MINIMUM_UNIT_COUNT
+          end
+
+          # If no unit is applicable, return the raw number
+          [create_unit_part(:units, absolute_amount, 1)]
+        end
+
+        def unit_definitions
+          UNIT_DEFINITIONS
+        end
+
+        # Helper method to create consistent unit part structure
+        def create_unit_part(unit_key, count, divisor)
+          { unit_key: unit_key, count: count, divisor: divisor }
+        end
+
+        # Filter out units below the minimum threshold
+        def filter_by_minimum_unit_threshold(breakdown, min_unit)
+          return breakdown unless min_unit
+
+          breakdown.select { |unit_info| unit_info[:divisor] >= min_unit }
+        end
+
+        # Format unit parts for abbreviated display (e.g., "1.2M")
+        def format_abbreviated_unit_parts(breakdown, locale, abbr_units, max_digits, trim_zeros)
+          # Check if we're in human formatting mode (any non-:units parts exist)
+          human_formatting_applied = breakdown.any? { |unit_info| unit_info[:unit_key] != :units }
+
+          breakdown.map do |unit_info|
+            if unit_info[:unit_key] == :units
+              if human_formatting_applied
+                # Part of human formatting - no delimiters
+                unit_info[:count].to_s
+              else
+                # Numbers below minimum unit threshold - apply locale formatting
+                format_below_min_unit(unit_info[:count], locale)
+              end
+            else
+              # Format with unit symbol (e.g., "1.2" + "M" = "1.2M")
+              format_number_with_unit_symbol(unit_info, locale, abbr_units, max_digits, trim_zeros)
+            end
+          end
+        end
+
+        # Format raw number without unit symbols
+        def format_raw_number_count(count, max_digits, trim_zeros)
+          format_unit_count(count, max_digits:, trim_zeros:, apply_rounding: false)
+        end
+
+        # Format number with unit symbol (e.g., "1.2M")
+        def format_number_with_unit_symbol(unit_info, locale, abbr_units, max_digits, trim_zeros)
+          symbol = lookup_unit_symbol(locale, unit_info[:unit_key], abbr_units)
+          format_with_symbol(unit_info[:count], symbol, abbr_units, max_digits:, trim_zeros:)
+        end
+
+        # Format unit with symbol for complete mode (e.g., "234K")
+        def format_complete_unit_with_symbol(unit_info, locale, abbr_units)
+          symbol = lookup_unit_symbol(locale, unit_info[:unit_key], abbr_units)
+          count_text = unit_info[:count].to_i.to_s
+          separator = determine_unit_value_separator(abbr_units)
+          formatted_symbol = apply_symbol_formatting_rules(symbol, abbr_units)
+          "#{count_text}#{separator}#{formatted_symbol}"
+        end
+
+        def format_unit_count(count, max_digits: 2, trim_zeros: true, apply_rounding: true)
+          return count.to_s unless count.is_a?(Numeric)
+
+          rounded = apply_rounding ? round_to_significant_digits(count, max_digits) : count
+
+          format_rounded_count(rounded, max_digits, trim_zeros, apply_rounding, count)
+        end
+
+        def format_rounded_count(rounded, max_digits, trim_zeros, apply_rounding, original_count)
+          if trim_zeros
+            format_with_trimmed_zeros(rounded)
+          elsif apply_rounding
+            format_with_fixed_decimals(rounded, max_digits)
+          else
+            original_count.to_s
+          end
+        end
+
+        def format_with_trimmed_zeros(rounded)
+          if rounded == rounded.to_i
+            rounded.to_i.to_s
+          else
+            rounded.to_s
+          end
+        end
+
+        def format_with_fixed_decimals(rounded, max_digits)
+          integer_digits = rounded.to_i.to_s.length
+          decimal_places = [0, max_digits - integer_digits].max
+          format("%.#{decimal_places}f", rounded)
+        end
+
+        def round_to_significant_digits(number, digits)
+          return handle_edge_cases(number, digits) if should_handle_edge_case?(number, digits)
+
+          abs_num = number.abs
+
+          # Simple significant digits rounding using scientific notation
+          magnitude = Math.log10(abs_num).floor
+          scale_factor = 10**(digits - 1 - magnitude)
+
+          rounded = (abs_num * scale_factor).round / scale_factor.to_f
+          apply_sign(number, rounded)
+        end
+
+        def should_handle_edge_case?(number, digits)
+          number.zero? || digits <= 0
+        end
+
+        def handle_edge_cases(number, _digits)
+          return 0.0 if number.zero?
+
+          number
+        end
+
+        def apply_sign(original_number, result)
+          original_number.negative? ? -result : result
+        end
+
+        def count_integer_digits(int_part)
+          int_part.zero? ? SINGLE_DIGIT_LIMIT : int_part.to_s.length
+        end
+
+        # Look up the localized symbol for a unit (e.g., 'M' for million)
+        def lookup_unit_symbol(locale, unit_key, abbr_units)
+          section = abbr_units ? I18N_ABBR_UNITS_SECTION : I18N_UNITS_SECTION
+
+          I18n.t("#{I18N_DECIMAL_UNITS_KEY}.#{section}.#{unit_key}", locale:, default: nil) ||
+            I18n.t("#{I18N_DECIMAL_UNITS_KEY}.#{section}.#{unit_key}", locale: :en, default: nil) ||
+            unit_key.to_s.upcase
+        end
+
+        def format_with_symbol(value, symbol, abbr_units, max_digits: 2, trim_zeros: true)
+          # Apply significant digits rounding to unit values
+          formatted_count = format_unit_count(value, max_digits:, trim_zeros:, apply_rounding: true)
+          separator = determine_unit_value_separator(abbr_units)
+          formatted_symbol = apply_symbol_formatting_rules(symbol, abbr_units)
+          "#{formatted_count}#{separator}#{formatted_symbol}"
+        end
+
+        # Determine separator between number and unit ("1M" vs "1 million")
+        def determine_unit_value_separator(abbr_units)
+          abbr_units ? EMPTY_SEPARATOR : SPACE_SEPARATOR
+        end
+
+        # Apply locale-specific formatting rules to unit symbols
+        def apply_symbol_formatting_rules(symbol, abbr_units)
+          return symbol if abbr_units || symbol.length <= 1
+
+          symbol.downcase # Western lowercase rule for full words
+        end
+
+        # Break down number into all applicable units for complete display
+        # Example: 1,234,567 -> [{million: 1}, {thousand: 234}, {units: 567}]
+        def break_down_into_all_units(number)
+          unit_breakdown = UnitBreakdown.new(number.abs, unit_definitions)
+          unit_breakdown.extract_all_units
+        end
+
+        # Helper class to manage unit breakdown state
+        class UnitBreakdown
+          def initialize(amount, unit_definitions)
+            @remaining_amount = amount
+            @unit_definitions = unit_definitions
+            @unit_parts = []
+          end
+
+          def extract_all_units
+            extract_major_units
+            add_remaining_as_units
+            @unit_parts
+          end
+
+          private
+
+          def extract_major_units
+            @unit_definitions.each do |unit|
+              extract_single_unit(unit) if @remaining_amount >= unit[:divisor]
+            end
+          end
+
+          def extract_single_unit(unit)
+            unit_count = (@remaining_amount / unit[:divisor]).to_i
+            return if unit_count.zero?
+
+            @unit_parts << create_unit_part(unit[:key], unit_count, unit[:divisor])
+            @remaining_amount %= unit[:divisor]
+          end
+
+          def add_remaining_as_units
+            return unless @remaining_amount.positive?
+
+            @unit_parts << create_unit_part(:units, @remaining_amount, 1)
+          end
+
+          def create_unit_part(unit_key, count, divisor)
+            { unit_key: unit_key, count: count, divisor: divisor }
+          end
+        end
+
+        # Format unit parts for complete display (e.g., "1M 234K 567")
+        def format_all_unit_parts(breakdown, locale, abbr_units)
+          # Check if we're in human formatting mode (any non-:units parts exist)
+          human_formatting_applied = breakdown.any? { |unit_info| unit_info[:unit_key] != :units }
+
+          breakdown.map do |unit_info|
+            if unit_info[:unit_key] == :units
+              if human_formatting_applied
+                # Part of human formatting - no delimiters
+                unit_info[:count].to_i.to_s
+              else
+                # Numbers below minimum unit threshold - apply locale formatting
+                format_below_min_unit(unit_info[:count].to_i, locale)
+              end
+            else
+              # Format each unit part with its symbol
+              format_complete_unit_with_symbol(unit_info, locale, abbr_units)
+            end
+          end
+        end
+
+        # Apply sign and join all parts into final result
+        def finalize_result(number, formatted_parts)
+          combined_result = formatted_parts.join(SPACE_SEPARATOR)
+          number.negative? ? "-#{combined_result}" : combined_result
+        end
+      end
+    end
+
+    # East Asian number formatting system using traditional Asian unit progression.
+    #
+    # This system implements the traditional East Asian number formatting convention
+    # using powers of 10,000 (万) progression for mid-range numbers, then jumping
+    # to 100,000,000 (억/億) and 1,000,000,000,000 (조/兆). This aligns with how
+    # numbers are conceptualized and spoken in Korean, Japanese, and Chinese.
+    #
+    # The system uses culturally appropriate separators and maintains the original
+    # case for Asian characters, unlike the Western system which lowercases full words.
+    #
+    # @example Formatting examples
+    #   # Korean (만/억/조)
+    #   HumanNumber.human_number(12_345, locale: :ko)     #=> "1만 2345"
+    #   HumanNumber.human_number(123_456_789, locale: :ko) #=> "1억 2345만 6789"
+    #
+    #   # Japanese (万/億/兆)
+    #   HumanNumber.human_number(12_345, locale: :ja)     #=> "1万 2345"
+    #
+    #   # Chinese (万/億/兆)
+    #   HumanNumber.human_number(12_345, locale: :'zh-CN') #=> "1万 2345"
+    #
+    #   # Abbreviated mode
+    #   HumanNumber.human_number(123_456_789, locale: :ko, max_digits: 2) #=> "1.2억"
+    #
+    # @example Supported locales and currencies
+    #   # Locales: [:ko, :ja, :zh, :'zh-CN', :'zh-TW']
+    #   # Currencies: ['KRW', 'JPY', 'CNY', 'SGD', 'HKD']
+    #
+    # @example Cultural separators
+    #   # Uses locale-specific separators (no space for some Asian languages)
+    #   HumanNumber.human_number(12_345_678, locale: :ko) #=> "1234만 5678"
+    #
+    # @see UNIT_DEFINITIONS
+    # @see EastAsianSystem#finalize_result
+    # @since 0.1.10
+    class EastAsianSystem < DefaultSystem
+      UNIT_DEFINITIONS = [
+        { key: :trillion, divisor: 1_000_000_000_000 },
+        { key: :hundred_million, divisor: 100_000_000 },
+        { key: :ten_thousand, divisor: 10_000 },
+      ].freeze
+
+      class << self
+        def format_number(number, locale:, abbr_units: true, min_unit: nil, max_digits: 2, trim_zeros: true)
+          @current_locale = locale.to_sym
+          super
+        end
+
+        private
+
+        def unit_definitions
+          UNIT_DEFINITIONS
+        end
+
+        def format_with_symbol(value, symbol, _abbr_units, max_digits: 2, trim_zeros: true)
+          # East Asian: no separator regardless of abbr_units
+          # Apply significant digits rounding to unit values
+          formatted_count = format_unit_count(value, max_digits:, trim_zeros:, apply_rounding: true)
+          formatted_symbol = apply_symbol_formatting_rules(symbol, true)
+          "#{formatted_count}#{formatted_symbol}"
+        end
+
+        # Keep original case for Asian characters (만, 억, 조)
+        def apply_symbol_formatting_rules(symbol, _abbr_units)
+          symbol
+        end
+
+        # Apply culturally appropriate separators for East Asian languages
+        def finalize_result(number, formatted_parts)
+          separator = lookup_decimal_separator(@current_locale)
+          combined_result = formatted_parts.join(separator)
+          number.negative? ? "-#{combined_result}" : combined_result
+        end
+
+        # Look up separator from locale file, default to space
+        def lookup_decimal_separator(locale)
+          I18n.t("#{I18N_DECIMAL_UNITS_KEY}.separator", locale: locale, default: SPACE_SEPARATOR)
+        end
+      end
+    end
+
+    # Indian subcontinent number formatting system using traditional South Asian units.
+    #
+    # This system implements the traditional Indian number formatting convention
+    # using the progression: thousand (1,000), lakh (100,000), crore (10,000,000).
+    # This aligns with how large numbers are conceptualized and spoken in Hindi,
+    # Urdu, Bengali, and Indian English contexts.
+    #
+    # The system follows a mixed base progression: thousands up to lakh,
+    # then lakhs up to crore, maintaining the linguistic patterns familiar
+    # to speakers of Indian subcontinent languages.
+    #
+    # @example Formatting examples
+    #   # Indian English
+    #   HumanNumber.human_number(123_456, locale: :'en-IN')  #=> "1 lakh 23K 456"
+    #   HumanNumber.human_number(12_345_678, locale: :'en-IN') #=> "1 crore 23 lakh 45K 678"
+    #
+    #   # Hindi/Urdu/Bengali contexts
+    #   HumanNumber.human_number(100_000, locale: :hi)       #=> "1 lakh"
+    #   HumanNumber.human_number(10_000_000, locale: :ur)    #=> "1 crore"
+    #
+    #   # Abbreviated mode
+    #   HumanNumber.human_number(12_345_678, locale: :'en-IN', max_digits: 2) #=> "1.2 crore"
+    #
+    # @example Supported locales and currencies
+    #   # Locales: [:hi, :ur, :bn, :'en-IN']
+    #   # Currencies: ['INR']
+    #
+    # @example Unit progression
+    #   # 1,000 = 1 thousand
+    #   # 100,000 = 1 lakh (not "100 thousand")
+    #   # 10,000,000 = 1 crore (not "10 million")
+    #
+    # @note Unlike Western and East Asian systems, the Indian system
+    #   uses a mixed base progression that doesn't follow strict powers
+    #   of 10 or 1000, reflecting the unique linguistic structure.
+    #
+    # @see UNIT_DEFINITIONS
+    # @since 0.1.10
+    class IndianSystem < DefaultSystem
+      UNIT_DEFINITIONS = [
+        { key: :crore, divisor: 10_000_000 },
+        { key: :lakh, divisor: 100_000 },
+        { key: :thousand, divisor: 1_000 },
+      ].freeze
+
+      class << self
+        private
+
+        def unit_definitions
+          UNIT_DEFINITIONS
+        end
+      end
+    end
+  end
+end

data/lib/human_number/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HumanNumber
-  VERSION = "0.1.10"
+  VERSION = "0.2.1"
 end