Module: ActiveSupport::NumberHelper
Class Method Summary
Autoload
- Extended
Instance Method Summary
-
#number_to_currency(number, options = {})
Formats a
number
into a currency string. -
#number_to_delimited(number, options = {})
Formats
number
by grouping thousands with a delimiter. -
#number_to_human(number, options = {})
Formats
number
into a more human-friendly representation. -
#number_to_human_size(number, options = {})
Formats
number
as bytes into a more human-friendly representation. -
#number_to_percentage(number, options = {})
Formats
number
as a percentage string. -
#number_to_phone(number, options = {})
Formats
number
into a phone number. -
#number_to_rounded(number, options = {})
Formats
number
to a specific level of precision.
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"
# File 'activesupport/lib/active_support/number_helper.rb', line 139
def number_to_currency(number, = {}) NumberToCurrencyConverter.convert(number, ) 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"
# File 'activesupport/lib/active_support/number_helper.rb', line 242
def number_to_delimited(number, = {}) NumberToDelimitedConverter.convert(number, ) 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"
# File 'activesupport/lib/active_support/number_helper.rb', line 453
def number_to_human(number, = {}) NumberToHumanConverter.convert(number, ) 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.
# File 'activesupport/lib/active_support/number_helper.rb', line 351
def number_to_human_size(number, = {}) NumberToHumanSizeConverter.convert(number, ) 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 preservenumber
‘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 %"
# File 'activesupport/lib/active_support/number_helper.rb', line 201
def number_to_percentage(number, = {}) NumberToPercentageConverter.convert(number, ) 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"
# File 'activesupport/lib/active_support/number_helper.rb', line 66
def number_to_phone(number, = {}) NumberToPhoneConverter.convert(number, ) 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 preservenumber
‘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"
# File 'activesupport/lib/active_support/number_helper.rb', line 298
def number_to_rounded(number, = {}) NumberToRoundedConverter.convert(number, ) end