123456789_123456789_123456789_123456789_123456789_

Module: ActiveSupport::NumberHelper

Overview

Number Helper

Provides methods for formatting numbers into currencies, percentages, phone numbers, and more.

Example usage in a class:

class Topic
  include ActiveSupport::NumberHelper

  def price
    number_to_currency(@price)
  end
end

Example usage in a module:

require "active_support/number_helper"

module NumberFormatting
  def format_price(price)
    ActiveSupport::NumberHelper.number_to_currency(price)
  end
end

Class Method Summary

Autoload - Extended

autoload, autoload_at, autoload_under, eager_autoload, eager_load!

Instance Method Summary

Instance Method Details

#number_to_currency(number, options = {})

Formats a number into a currency string.

number_to_currency(1234567890.50)  # => "$1,234,567,890.50"
number_to_currency(1234567890.506) # => "$1,234,567,890.51"
number_to_currency("12x34")        # => "$12x34"

number_to_currency(1234567890.50, unit: "£", separator: ",", delimiter: "")
# => "£1234567890,50"

The currency unit and number formatting of the current locale will be used unless otherwise specified via options. No currency conversion is performed. If the user is given a way to change their locale, they will also be able to change the relative value of the currency displayed with this helper. If your application will ever support multiple locales, you may want to specify a constant :locale option or consider using a library capable of currency conversion.

Options

:locale

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

number_to_currency(1234567890.506, locale: :fr)
# => "1 234 567 890,51 €"
:precision

The level of precision. Defaults to 2.

number_to_currency(1234567890.123, precision: 3) # => "$1,234,567,890.123"
number_to_currency(0.456789, precision: 0)       # => "$0"
:round_mode

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

number_to_currency(1234567890.01, precision: 0, round_mode: :up)
# => "$1,234,567,891"
:unit

The denomination of the currency. Defaults to "$".

:separator

The decimal separator. Defaults to ".".

:delimiter

The thousands delimiter. Defaults to ",".

:format

The format for non-negative numbers. %u represents the currency, and %n represents the number. Defaults to "%u%n".

number_to_currency(1234567890.50, format: "%n %u")
# => "1,234,567,890.50 $"
:negative_format

The format for negative numbers. %u and %n behave the same as in :format, but %n represents the absolute value of the number. Defaults to the value of :format prepended with -.

number_to_currency(-1234567890.50, negative_format: "(%u%n)")
# => "($1,234,567,890.50)"
:strip_insignificant_zeros

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

number_to_currency(1234567890.50, strip_insignificant_zeros: true)
# => "$1,234,567,890.5"
[ GitHub ] 

  


# File 'activesupport/lib/active_support/number_helper.rb', line 161



def number_to_currency(number, options = {})
  NumberToCurrencyConverter.convert(number, options)
end


  








  

    #number_to_delimited(number, options = {})  
  



  

    

Formats number by grouping thousands with a delimiter.



number_to_delimited(12345678)      # => "12,345,678"
number_to_delimited("123456")      # => "123,456"
number_to_delimited(12345678.9876) # => "12,345,678.9876"
number_to_delimited("12x34")       # => "12x34"

number_to_delimited(12345678.9876, delimiter: ".", separator: ",")
# => "12.345.678,9876"



Options


:locale




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



number_to_delimited(12345678.05, locale: :fr)
# => "12 345 678,05"


:delimiter




The thousands delimiter. Defaults to ",".



number_to_delimited(12345678, delimiter: ".")
# => "12.345.678"


:separator




The decimal separator. Defaults to ".".



number_to_delimited(12345678.05, separator: " ")
# => "12,345,678 05"


:delimiter_pattern




A regexp to determine the placement of delimiters. Helpful when using currency formats like INR.



number_to_delimited("123456.78", delimiter_pattern: /(\d?)(?=(\d\d)(\d)(?!\d))/)
# => "1,23,456.78"




  



  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/number_helper.rb', line 264



def number_to_delimited(number, options = {})
  NumberToDelimitedConverter.convert(number, options)
end


  








  

    #number_to_human(number, options = {})  
  



  

    

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"




  



  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/number_helper.rb', line 475



def number_to_human(number, options = {})
  NumberToHumanConverter.convert(number, options)
end


  








  

    #number_to_human_size(number, options = {})  
  



  

    

Formats number as bytes into a more human-friendly representation. Useful for reporting file sizes to users.



number_to_human_size(123)                 # => "123 Bytes"
number_to_human_size(1234)                # => "1.21 KB"
number_to_human_size(12345)               # => "12.1 KB"
number_to_human_size(1234567)             # => "1.18 MB"
number_to_human_size(1234567890)          # => "1.15 GB"
number_to_human_size(1234567890123)       # => "1.12 TB"
number_to_human_size(1234567890123456)    # => "1.1 PB"
number_to_human_size(1234567890123456789) # => "1.07 EB"



See #number_to_human if you want to pretty-print a generic number.



Options


:locale




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


:precision




The level of precision. Defaults to 3.



number_to_human_size(123456, precision: 2)  # => "120 KB"
number_to_human_size(1234567, precision: 2) # => "1.2 MB"


:round_mode




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



number_to_human_size(123456, precision: 2, round_mode: :up)
# => "130 KB"


: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_size(1234567, separator: ",")
# => "1,18 MB"


:delimiter




The thousands delimiter. Defaults to ",".


:strip_insignificant_zeros




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




  



  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/number_helper.rb', line 373



def number_to_human_size(number, options = {})
  NumberToHumanSizeConverter.convert(number, options)
end


  








  

    #number_to_percentage(number, options = {})  
  



  

    

Formats number as a percentage string.



number_to_percentage(100)   # => "100.000%"
number_to_percentage("99")  # => "99.000%"
number_to_percentage("99x") # => "99x%"

number_to_percentage(12345.6789, delimiter: ".", separator: ",", precision: 2)
# => "12.345,68%"



Options


:locale




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



number_to_percentage(1000, locale: :fr)
# => "1000,000%"


:precision




The level of precision, or nil to preserve number‘s precision. Defaults to 2.



number_to_percentage(12.3456789, precision: 4) # => "12.3457%"
number_to_percentage(99.999, precision: 0)     # => "100%"
number_to_percentage(99.999, precision: nil)   # => "99.999%"


:round_mode




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



number_to_percentage(12.3456789, precision: 4, round_mode: :down)
# => "12.3456%"


:significant




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



number_to_percentage(12345.6789)                                  # => "12345.679%"
number_to_percentage(12345.6789, significant: true)               # => "12300%"
number_to_percentage(12345.6789, precision: 2)                    # => "12345.68%"
number_to_percentage(12345.6789, precision: 2, significant: true) # => "12000%"


:separator




The decimal separator. Defaults to ".".


:delimiter




The thousands delimiter. Defaults to ",".


:strip_insignificant_zeros




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


:format




The format of the output. %n represents the number. Defaults to "%n%".



number_to_percentage(100, format: "%n  %")
# => "100.000  %"




  



  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/number_helper.rb', line 223



def number_to_percentage(number, options = {})
  NumberToPercentageConverter.convert(number, options)
end


  








  

    #number_to_phone(number, options = {})  
  



  

    

Formats number into a phone number.



number_to_phone(5551234)    # => "555-1234"
number_to_phone("5551234")  # => "555-1234"
number_to_phone(1235551234) # => "123-555-1234"
number_to_phone("12x34")    # => "12x34"

number_to_phone(1235551234, delimiter: ".", country_code: 1, extension: 1343)
# => "+1.123.555.1234 x 1343"



Options


:area_code




Whether to use parentheses for the area code. Defaults to false.



number_to_phone(1235551234, area_code: true)
# => "(123) 555-1234"


:delimiter




The digit group delimiter to use. Defaults to "-".



number_to_phone(1235551234, delimiter: " ")
# => "123 555 1234"


:country_code




A country code to prepend.



number_to_phone(1235551234, country_code: 1)
# => "+1-123-555-1234"


:extension




An extension to append.



number_to_phone(1235551234, extension: 555)
# => "123-555-1234 x 555"


:pattern




A regexp that specifies how the digits should be grouped. The first three captures from the regexp are treated as digit groups.



number_to_phone(13312345678, pattern: /(\d{3})(\d{4})(\d{4})$/)
# => "133-1234-5678"
number_to_phone(75561234567, pattern: /(\d{1,4})(\d{4})(\d{4})$/, area_code: true)
# => "(755) 6123-4567"




  



  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/number_helper.rb', line 88



def number_to_phone(number, options = {})
  NumberToPhoneConverter.convert(number, options)
end


  








  

    #number_to_rounded(number, options = {})  
  



  

    

Formats number to a specific level of precision.



number_to_rounded(12345.6789)                # => "12345.679"
number_to_rounded(12345.6789, precision: 2)  # => "12345.68"
number_to_rounded(12345.6789, precision: 0)  # => "12345"
number_to_rounded(12345, precision: 5)       # => "12345.00000"



Options


:locale




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



number_to_rounded(111.234, locale: :fr)
# => "111,234"


:precision




The level of precision, or nil to preserve number‘s precision. Defaults to 3.



number_to_rounded(12345.6789, precision: nil)
# => "12345.6789"


:round_mode




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



number_to_rounded(12.34, precision: 0, round_mode: :up)
# => "13"


:significant




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



number_to_rounded(12345.6789)                                  # => "12345.679"
number_to_rounded(12345.6789, significant: true)               # => "12300"
number_to_rounded(12345.6789, precision: 2)                    # => "12345.68"
number_to_rounded(12345.6789, precision: 2, significant: true) # => "12000"


:separator




The decimal separator. Defaults to ".".


:delimiter




The thousands delimiter. Defaults to ",".


:strip_insignificant_zeros




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



number_to_rounded(12.34, strip_insignificant_zeros: false)  # => "12.340"
number_to_rounded(12.34, strip_insignificant_zeros: true)   # => "12.34"
number_to_rounded(12.3456, strip_insignificant_zeros: true) # => "12.346"




  



  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/number_helper.rb', line 320



def number_to_rounded(number, options = {})
  NumberToRoundedConverter.convert(number, options)
end