instance method number_to_human

Pretty prints (formats and approximates) a number in a way it is more readable by humans (eg.: 1200000000 becomes “1.2 Billion”). This is useful for numbers that can get very large (and too hard to read).

See number_to_human_size if you want to print a file size.

You can also define your own unit-quantifier names if you want to use other decimal units (eg.: 1500 becomes “1.5 kilometers”, 0.150 becomes “150 milliliters”, etc). You may define a wide range of unit quantifiers, even fractional ones (centi, deci, mili, etc).

Options

• :locale - Sets the locale to be used for formatting (defaults to current locale).

• :precision - Sets the precision of the number (defaults to 3).

• :significant - If true, precision will be the # of significant_digits. If false, the # of fractional digits (defaults to true)

• :separator - Sets the separator between the fractional and integer digits (defaults to “.”).

• :delimiter - Sets the thousands delimiter (defaults to “”).

• :strip_insignificant_zeros - If true removes insignificant zeros after the decimal separator (defaults to true)

• :units - A Hash of unit quantifier names. Or a string containing an i18n scope where to find this hash. It might have the following keys:

  • integers: :unit, :ten, *:hundred, :thousand, :million, *:billion, :trillion, *:quadrillion

  • fractionals: :deci, :centi, *:mili, :micro, :nano, *:pico, :femto

• :format - Sets the format of the output string (defaults to “%n %u”). The field types are:

  • %u - The quantifier (ex.: ‘thousand’)

  • %n - The number

Examples

number_to_human(123)                         # => "123"
number_to_human(1234)                        # => "1.23 Thousand"
number_to_human(12345)                       # => "12.3 Thousand"
number_to_human(1234567)                     # => "1.23 Million"
number_to_human(1234567890)                  # => "1.23 Billion"
number_to_human(1234567890123)               # => "1.23 Trillion"
number_to_human(1234567890123456)            # => "1.23 Quadrillion"
number_to_human(1234567890123456789)         # => "1230 Quadrillion"
number_to_human(489939, precision: 2)        # => "490 Thousand"
number_to_human(489939, precision: 4)        # => "489.9 Thousand"
number_to_human(1234567, precision: 4,
                         significant: false) # => "1.2346 Million"
number_to_human(1234567, precision: 1,
                         separator: ',',
                         significant: false) # => "1,2 Million"

Non-significant zeros after the decimal separator are stripped out by default (set :strip_insignificant_zeros to false to change that):

number_to_human(12345012345, significant_digits: 6) # => "12.345 Billion"
number_to_human(500000000, precision: 5)            # => "500 Million"

Custom Unit Quantifiers

You can also use your own custom unit quantifiers:

number_to_human(500000, units: { unit: 'ml', thousand: 'lt' })  # => "500 lt"

If in your I18n locale you have:

distance:
  centi:
    one: "centimeter"
    other: "centimeters"
  unit:
    one: "meter"
    other: "meters"
  thousand:
    one: "kilometer"
    other: "kilometers"
  billion: "gazillion-distance"

Then you could do:

number_to_human(543934, units: :distance)            # => "544 kilometers"
number_to_human(54393498, units: :distance)          # => "54400 kilometers"
number_to_human(54393498000, units: :distance)       # => "54.4 gazillion-distance"
number_to_human(343, units: :distance, precision: 1) # => "300 meters"
number_to_human(1, units: :distance)                 # => "1 meter"
number_to_human(0.34, units: :distance)              # => "34 centimeters"