instance method number_to_human

Formats number into a more human-friendly representation. Useful for numbers that can become very large and too hard to read.

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"

See #number_to_human_size if you want to pretty-print a file size.

Options

:locale

The locale to use for formatting. Defaults to the current locale.

:precision

The level of precision. Defaults to 3.

number_to_human(123456, precision: 2) # => "120 Thousand"
number_to_human(123456, precision: 4) # => "123.5 Thousand"

:round_mode

Specifies how rounding is performed. See BigDecimal.mode. Defaults to :default.

number_to_human(123456, precision: 2, round_mode: :up)
# => "130 Thousand"

:significant

Whether :precision should be applied to significant digits instead of fractional digits. Defaults to true.

:separator

The decimal separator. Defaults to ".".

number_to_human(123456, precision: 4, separator: ",")
# => "123,5 Thousand"

:delimiter

The thousands delimiter. Defaults to ",".

:strip_insignificant_zeros

Whether to remove insignificant zeros after the decimal separator. Defaults to true.

number_to_human(1000000)                                   # => "1 Million"
number_to_human(1000000, strip_insignificant_zeros: false) # => "1.00 Million"
number_to_human(10.01)                                     # => "10"
number_to_human(10.01, strip_insignificant_zeros: false)   # => "10.0"

:format

The format of the output. %n represents the number, and %u represents the quantifier (e.g., “Thousand”). Defaults to "%n %u".

:units

A Hash of custom unit quantifier names.

number_to_human(1, units: { unit: "m", thousand: "km" })        # => "1 m"
number_to_human(100, units: { unit: "m", thousand: "km" })      # => "100 m"
number_to_human(1000, units: { unit: "m", thousand: "km" })     # => "1 km"
number_to_human(100000, units: { unit: "m", thousand: "km" })   # => "100 km"
number_to_human(10000000, units: { unit: "m", thousand: "km" }) # => "10000 km"

The following keys are supported for integer units: :unit, :ten, :hundred, :thousand, :million, :billion, :trillion, :quadrillion. Additionally, the following keys are supported for fractional units: :deci, :centi, :mili, :micro, :nano, :pico, :femto.

The Hash can also be defined as a scope in an I18n locale. For example:

en:
  distance:
    centi:
      one: "centimeter"
      other: "centimeters"
    unit:
      one: "meter"
      other: "meters"
    thousand:
      one: "kilometer"
      other: "kilometers"

Then it can be specified by name:

number_to_human(1, units: :distance)        # => "1 meter"
number_to_human(100, units: :distance)      # => "100 meters"
number_to_human(1000, units: :distance)     # => "1 kilometer"
number_to_human(100000, units: :distance)   # => "100 kilometers"
number_to_human(10000000, units: :distance) # => "10000 kilometers"
number_to_human(0.1, units: :distance)      # => "10 centimeters"
number_to_human(0.01, units: :distance)     # => "1 centimeter"