Module: HumanNumber

Extended by:
ActionView::Helpers::NumberHelper
Defined in:
lib/human_number.rb,
lib/human_number/railtie.rb,
lib/human_number/version.rb,
lib/human_number/number_system.rb,
lib/human_number/rails/helpers.rb,
lib/human_number/locale_support.rb,
lib/human_number/formatters/number.rb,
lib/human_number/formatters/currency.rb

Defined Under Namespace

Modules: Formatters, LocaleSupport, NumberSystem, Rails Classes: Error, Railtie

Constant Summary collapse

VERSION = 
"0.2.2"
ZERO_STRING =

Constants for string literals and magic numbers used by system classes

"0"
EMPTY_SEPARATOR = 
""
SPACE_SEPARATOR = 
" "
DECIMAL_FORMAT_TEMPLATE = 
"%.%df"
MINIMUM_UNIT_COUNT = 
1.0
SINGLE_DIGIT_LIMIT = 
1
I18N_DECIMAL_UNITS_KEY =

I18n key templates

"number.human.decimal_units"
I18N_ABBR_UNITS_SECTION = 
"abbr_units"
I18N_UNITS_SECTION = 
"units"

Class Method Summary collapse

Class Method Details

.currency(number, currency_code:, locale: I18n.locale, **options) ⇒ String

Note:

Only numeric formatting options are supported. Currency symbols and formats are automatically determined by ISO 4217 standards and locale conventions.

Note:

Precision is determined by currency's native locale unless overridden via :precision option

Formats a currency amount with standard precision and symbol placement.

This method provides currency formatting with automatic precision rules based on international standards, ensuring consistent display across different locales:

  • Currency-specific precision: 2 decimals for USD/EUR, 0 for JPY/KRW
  • Native locale rules: Precision determined by currency's origin locale
  • Cross-locale consistency: USD shows 2 decimals regardless of display locale
  • Symbol placement: Follows locale-specific conventions ($1,234 vs 1,234원)

Examples:

Basic currency formatting

HumanNumber.currency(1234.56, currency_code: 'USD', locale: :en) #=> "$1,234.56"
HumanNumber.currency(50000, currency_code: 'KRW', locale: :ko)   #=> "50,000원"
HumanNumber.currency(1234.99, currency_code: 'JPY', locale: :ja) #=> "1,235円"

Custom precision and formatting

HumanNumber.currency(1234.56, currency_code: 'USD', precision: 1)                    #=> "$1,234.6"
HumanNumber.currency(1234.56, currency_code: 'USD', delimiter: " ")                  #=> "$1 234.56"
HumanNumber.currency(1234.50, currency_code: 'USD', strip_insignificant_zeros: true) #=> "$1,234.5"

Cross-locale precision consistency

# USD always shows 2 decimals regardless of display locale
HumanNumber.currency(1234.56, currency_code: 'USD', locale: :ko) #=> "$1,234.56"

# JPY always shows 0 decimals regardless of display locale
HumanNumber.currency(1234.56, currency_code: 'JPY', locale: :en) #=> "1,235円"

Edge cases

HumanNumber.currency(0, currency_code: 'USD')      #=> "$0.00"
HumanNumber.currency(-1234.56, currency_code: 'USD') #=> "-$1,234.56"

Parameters:

  • number (Numeric) —

    The amount to format

  • currency_code (String) —

    ISO 4217 currency code (e.g., 'USD', 'EUR', 'KRW', 'JPY')

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

    Display locale for formatting rules (default: current I18n locale) Determines delimiter, separator, and symbol placement conventions

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :precision (Integer) —

    Decimal precision level. Overrides currency-specific precision

  • :round_mode (Symbol) —

    Rounding mode (see BigDecimal.mode). Defaults to :default

  • :separator (String) —

    Decimal separator. Defaults to locale-specific separator

  • :delimiter (String) —

    Thousands delimiter. Defaults to locale-specific delimiter

  • :strip_insignificant_zeros (Boolean) — default: false —

    Remove trailing decimal zeros

Returns:

  • (String) —

    The formatted currency string

See Also:



123
124
125
126
127
128
129
130
 
# File 'lib/human_number.rb', line 123

def currency(number, currency_code:, locale: I18n.locale, **options)
  validate_number_input!(number)
  validate_currency_code!(currency_code)
  validate_locale!(locale)

  formatted_number = Formatters::Number.format_with_currency_precision(number, currency_code:, locale:, **options)
  Formatters::Currency.format(formatted_number, currency_code:, locale:)
end

.currency_number_system(currency_code:) ⇒ Symbol

Determines the number system used for a given currency.

This method identifies which cultural number system is typically used when formatting amounts in the specified currency, based on the currency's primary cultural and linguistic context.

Examples:

Basic usage

HumanNumber.currency_number_system(currency_code: 'USD') #=> :default
HumanNumber.currency_number_system(currency_code: 'KRW') #=> :east_asian
HumanNumber.currency_number_system(currency_code: 'INR') #=> :indian

East Asian currencies

HumanNumber.currency_number_system(currency_code: 'JPY') #=> :east_asian
HumanNumber.currency_number_system(currency_code: 'CNY') #=> :east_asian
HumanNumber.currency_number_system(currency_code: 'HKD') #=> :east_asian

Default system currencies

HumanNumber.currency_number_system(currency_code: 'EUR') #=> :default
HumanNumber.currency_number_system(currency_code: 'GBP') #=> :default
HumanNumber.currency_number_system(currency_code: 'CAD') #=> :default

Parameters:

  • currency_code (String) —

    ISO 4217 currency code (e.g., 'USD', 'KRW', 'INR') The currency code to determine the number system for

Returns:

  • (Symbol) —

    The number system identifier

    • :default - Western system (K/M/B/T for thousand/million/billion/trillion)
    • :east_asian - East Asian system (만/억/조 or 万/億/兆)
    • :indian - Indian subcontinent system (thousand/lakh/crore)

See Also:



242
243
244
245
 
# File 'lib/human_number.rb', line 242

def currency_number_system(currency_code:)
  validate_currency_code!(currency_code)
  NumberSystem.currency_number_system(currency_code:)
end

.human_currency(number, currency_code:, locale: I18n.locale, **options) ⇒ String

Note:

Combines human number formatting with currency-specific symbol placement

Formats a currency amount with intelligent, locale-aware abbreviations.

This method combines human-readable number formatting with currency symbols, providing culturally-appropriate abbreviations while maintaining currency symbol and format conventions.

Examples:

Basic usage

HumanNumber.human_currency(1234567, currency_code: 'USD', locale: :en) #=> "$1.2M"
HumanNumber.human_currency(50000, currency_code: 'KRW', locale: :ko)   #=> "5만원"

Precision control

HumanNumber.human_currency(1234567, currency_code: 'USD', locale: :en, max_digits: 2) #=> "$1.2M"
HumanNumber.human_currency(1234567, currency_code: 'USD', locale: :en, max_digits: nil) #=> "$1M 234K 567"

Unit preferences

HumanNumber.human_currency(1000000, currency_code: 'USD', locale: :en, abbr_units: true)  #=> "$1M"
HumanNumber.human_currency(1000000, currency_code: 'USD', locale: :en, abbr_units: false) #=> "$1 million"

Cultural unit systems

HumanNumber.human_currency(12345678, currency_code: 'JPY', locale: :ja) #=> "1234.6万円"
HumanNumber.human_currency(10000000, currency_code: 'INR', locale: :hi) #=> "1 crore₹"

Parameters:

  • number (Numeric) —

    The amount to format

  • currency_code (String) —

    ISO 4217 currency code (e.g., 'USD', 'EUR', 'KRW', 'JPY')

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

    Locale for formatting and unit system selection

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :abbr_units (Boolean) — default: true —

    Use abbreviated unit symbols (K/M/B) vs full words. Only affects Western locales

  • :max_digits (Integer, nil) — default: 2 —

    Maximum significant digits to display. When nil, displays complete amount using multiple units without decimals

  • :min_unit (Integer, nil) — default: nil —

    Minimum unit threshold for abbreviation. Amounts below this won't be abbreviated

  • :trim_zeros (Boolean) — default: true —

    Remove trailing decimal zeros. Only applies in abbreviated mode (when max_digits is set)

Returns:

  • (String) —

    The formatted currency string with abbreviations

See Also:

  • For detailed number formatting options
  • For standard currency formatting without abbreviations


172
173
174
175
176
177
178
179
180
181
 
# File 'lib/human_number.rb', line 172

def human_currency(number, currency_code:, locale: I18n.locale, **options)
  validate_number_input!(number)
  validate_currency_code!(currency_code)
  validate_locale!(locale)

  final_options = Formatters::Number.default_options.merge(options)

  formatted_number = Formatters::Number.format(number, locale:, **final_options)
  Formatters::Currency.format(formatted_number, currency_code:, locale:)
end

.human_number(number, locale: I18n.locale, **options) ⇒ String

Note:

Complete mode (max_digits: nil) shows full precision across multiple units

Formats a number with intelligent, locale-aware abbreviations.

This method provides culturally-appropriate number formatting with automatic unit system selection based on locale:

  • Western locales: K/M/B/T (thousand/million/billion/trillion)
  • East Asian locales: 만/억/조 or 万/億/兆
  • Indian locales: thousand/lakh/crore

Examples:

Basic usage

HumanNumber.human_number(1234567)           #=> "1.2M"
HumanNumber.human_number(50000, locale: :ko) #=> "5만"

Precision control

HumanNumber.human_number(1234567, max_digits: 2)   #=> "1.2M"
HumanNumber.human_number(1234567, max_digits: nil) #=> "1M 234K 567"

Unit preferences

HumanNumber.human_number(1000000, abbr_units: true)  #=> "1M"
HumanNumber.human_number(1000000, abbr_units: false) #=> "1 million"

Minimum thresholds

HumanNumber.human_number(5000, min_unit: 10000)  #=> "5000"
HumanNumber.human_number(50000, min_unit: 10000) #=> "5만"

Zero trimming

HumanNumber.human_number(1000000, trim_zeros: true)  #=> "1M"
HumanNumber.human_number(1000000, trim_zeros: false) #=> "1.0M"

Parameters:

  • number (Numeric) —

    The number to format

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

    The locale for formatting (default: current I18n locale) Determines both number formatting rules and cultural unit systems

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :abbr_units (Boolean) — default: true —

    Use abbreviated unit symbols (K/M/B) vs full words. Only affects Western locales

  • :max_digits (Integer, nil) — default: 2 —

    Maximum significant digits to display. When nil, displays complete number using multiple units without decimals

  • :min_unit (Integer, nil) — default: nil —

    Minimum unit threshold for abbreviation. Numbers below this won't be abbreviated

  • :trim_zeros (Boolean) — default: true —

    Remove trailing decimal zeros. Only applies in abbreviated mode (when max_digits is set)

Returns:

  • (String) —

    The formatted number string

See Also:



64
65
66
67
68
69
70
71
 
# File 'lib/human_number.rb', line 64

def human_number(number, locale: I18n.locale, **options)
  validate_number_input!(number)
  validate_locale!(locale)

  final_options = Formatters::Number.default_options.merge(options)

  Formatters::Number.format(number, locale:, **final_options)
end

.number_system(locale: I18n.locale) ⇒ Symbol

Determines the number system used for a given locale.

This method identifies which cultural number system (Western, East Asian, or Indian) is used for formatting numbers in the specified locale.

Examples:

Basic usage

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

Cultural system examples

HumanNumber.number_system(locale: :ja)     #=> :east_asian (Japanese: 万/億/兆)
HumanNumber.number_system(locale: :"zh-CN") #=> :east_asian (Chinese: 万/億/兆)
HumanNumber.number_system(locale: :"en-IN") #=> :indian (Indian English: lakh/crore)

Parameters:

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

    The locale for system determination (default: current I18n locale) Determines which cultural number system to use for formatting

Returns:

  • (Symbol) —

    The number system identifier

    • :default - Western system (K/M/B/T for thousand/million/billion/trillion)
    • :east_asian - East Asian system (만/억/조 or 万/億/兆)
    • :indian - Indian subcontinent system (thousand/lakh/crore)

See Also:



207
208
209
210
 
# File 'lib/human_number.rb', line 207

def number_system(locale: I18n.locale)
  validate_locale!(locale)
  NumberSystem.number_system(locale:)
end