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 you 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"

Unsignificant 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"