Module: HumanNumber::NumberSystem

Defined in:
lib/human_number/number_system.rb,
lib/human_number/number_system.rb

Overview

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.

Examples:

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

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 Also:

Since:

  • 0.1.10

Defined Under Namespace

Classes: DefaultSystem, EastAsianSystem, IndianSystem

Constant Summary collapse

CURRENCY_SYSTEM_MAPPING =

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.

Examples:

East Asian currencies (powers of 10,000 progression)

'KRW' => Korean Won, 'JPY' => Japanese Yen, 'CNY' => Chinese Yuan
'SGD' => Singapore Dollar, 'HKD' => Hong Kong Dollar

Indian subcontinent currencies (lakh/crore system)

'INR' => Indian Rupee

See Also:

Since:

  • 0.1.10

{
  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_SYSTEM_MAPPING =

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.

Examples:

East Asian locales (万/億/兆 or 만/억/조 progression)

:ko => Korean, :ja => Japanese, :zh => Chinese (generic)
:'zh-CN' => Chinese (Simplified), :'zh-TW' => Chinese (Traditional)

Indian subcontinent locales (thousand/lakh/crore progression)

:hi => Hindi, :ur => Urdu, :bn => Bengali, :'en-IN' => Indian English

See Also:

Since:

  • 0.1.10

{
  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

Class Method Summary collapse

Class Method Details

.currency_number_system(currency_code:) ⇒ Symbol

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.

Examples:

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

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

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

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

Parameters:

  • 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.

Returns:

  • (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)

See Also:

Since:

  • 0.1.10



163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/human_number/number_system.rb', line 163

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

.number_system(locale: I18n.locale) ⇒ Symbol

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.

Examples:

Basic locale determination

NumberSystem.number_system(locale: :en)        #=> :default
NumberSystem.number_system(locale: :ko)        #=> :east_asian
NumberSystem.number_system(locale: :hi)        #=> :indian

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

String input and nil handling

NumberSystem.number_system(locale: 'ja')       #=> :east_asian
NumberSystem.number_system(locale: nil)        #=> (uses I18n.locale)

Unknown locales default to Western system

NumberSystem.number_system(locale: :unknown)   #=> :default
NumberSystem.number_system(locale: :xyz)       #=> :default

Parameters:

  • locale (Symbol, String, nil) (defaults to: I18n.locale) —

    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').

Returns:

  • (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

See Also:

Since:

  • 0.1.10



111
112
113
114
115
116
117
118
119
 
# File 'lib/human_number/number_system.rb', line 111

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