instance method number_to_human

Pretty prints (formats and approximates) a number in a way it is more readable by humans (e.g.: 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 (e.g.: 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 number of significant_digits. If false, the number 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

• :raise - If true, raises InvalidNumberError when the argument is invalid.

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"

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

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

number_to_human(12.00001) # => “12” number_to_human(12.00001, strip_insignificant_zeros: false) # => “12.0”

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"