Skip to content

Commit 53ba75d

Browse files
jonathanhefnerjonathanhefner
committed
Clean up AS::NumberHelper#number_to_human doc [ci-skip]
1 parent 2b801dc commit 53ba75d

File tree

1 file changed

+93
-100
lines changed

1 file changed

+93
-100
lines changed

‎activesupport/lib/active_support/number_helper.rb

Lines changed: 93 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -352,111 +352,104 @@ def number_to_human_size(number, options = {})
352352
NumberToHumanSizeConverter.convert(number, options)
353353
end
354354

355-
# Pretty prints (formats and approximates) a number in a way it
356-
# is more readable by humans (e.g.: 1200000000 becomes "1.2
357-
# Billion"). This is useful for numbers that can get very large
358-
# (and too hard to read).
355+
# Formats +number+ into a more human-friendly representation. Useful for
356+
# numbers that can become very large and too hard to read.
359357
#
360-
# See <tt>number_to_human_size</tt> if you want to print a file
361-
# size.
358+
# number_to_human(123) # => "123"
359+
# number_to_human(1234) # => "1.23 Thousand"
360+
# number_to_human(12345) # => "12.3 Thousand"
361+
# number_to_human(1234567) # => "1.23 Million"
362+
# number_to_human(1234567890) # => "1.23 Billion"
363+
# number_to_human(1234567890123) # => "1.23 Trillion"
364+
# number_to_human(1234567890123456) # => "1.23 Quadrillion"
365+
# number_to_human(1234567890123456789) # => "1230 Quadrillion"
362366
#
363-
# You can also define your own unit-quantifier names if you want
364-
# to use other decimal units (e.g.: 1500 becomes "1.5
365-
# kilometers", 0.150 becomes "150 milliliters", etc). You may
366-
# define a wide range of unit quantifiers, even fractional ones
367-
# (centi, deci, mili, etc).
367+
# See #number_to_human_size if you want to pretty-print a file size.
368368
#
369369
# ==== Options
370370
#
371-
# * <tt>:locale</tt> - Sets the locale to be used for formatting
372-
# (defaults to current locale).
373-
# * <tt>:precision</tt> - Sets the precision of the number
374-
# (defaults to 3).
375-
# * <tt>:round_mode</tt> - Determine how rounding is performed
376-
# (defaults to :default. See BigDecimal::mode)
377-
# * <tt>:significant</tt> - If +true+, precision will be the number
378-
# of significant_digits. If +false+, the number of fractional
379-
# digits (defaults to +true+)
380-
# * <tt>:separator</tt> - Sets the separator between the
381-
# fractional and integer digits (defaults to ".").
382-
# * <tt>:delimiter</tt> - Sets the thousands delimiter (defaults
383-
# to "").
384-
# * <tt>:strip_insignificant_zeros</tt> - If +true+ removes
385-
# insignificant zeros after the decimal separator (defaults to
386-
# +true+)
387-
# * <tt>:units</tt> - A Hash of unit quantifier names. Or a
388-
# string containing an i18n scope where to find this hash. It
389-
# might have the following keys:
390-
# * *integers*: <tt>:unit</tt>, <tt>:ten</tt>,
391-
# <tt>:hundred</tt>, <tt>:thousand</tt>, <tt>:million</tt>,
392-
# <tt>:billion</tt>, <tt>:trillion</tt>,
393-
# <tt>:quadrillion</tt>
394-
# * *fractionals*: <tt>:deci</tt>, <tt>:centi</tt>,
395-
# <tt>:mili</tt>, <tt>:micro</tt>, <tt>:nano</tt>,
396-
# <tt>:pico</tt>, <tt>:femto</tt>
397-
# * <tt>:format</tt> - Sets the format of the output string
398-
# (defaults to "%n %u"). The field types are:
399-
# * %u - The quantifier (ex.: 'thousand')
400-
# * %n - The number
401-
#
402-
# ==== Examples
403-
#
404-
# number_to_human(123) # => "123"
405-
# number_to_human(1234) # => "1.23 Thousand"
406-
# number_to_human(12345) # => "12.3 Thousand"
407-
# number_to_human(1234567) # => "1.23 Million"
408-
# number_to_human(1234567890) # => "1.23 Billion"
409-
# number_to_human(1234567890123) # => "1.23 Trillion"
410-
# number_to_human(1234567890123456) # => "1.23 Quadrillion"
411-
# number_to_human(1234567890123456789) # => "1230 Quadrillion"
412-
# number_to_human(489939, precision: 2) # => "490 Thousand"
413-
# number_to_human(489939, precision: 4) # => "489.9 Thousand"
414-
# number_to_human(489939, precision: 2
415-
# , round_mode: :down) # => "480 Thousand"
416-
# number_to_human(1234567, precision: 4,
417-
# significant: false) # => "1.2346 Million"
418-
# number_to_human(1234567, precision: 1,
419-
# separator: ',',
420-
# significant: false) # => "1,2 Million"
421-
#
422-
# number_to_human(500000000, precision: 5) # => "500 Million"
423-
# number_to_human(12345012345, significant: false) # => "12.345 Billion"
424-
#
425-
# Non-significant zeros after the decimal separator are stripped
426-
# out by default (set <tt>:strip_insignificant_zeros</tt> to
427-
# +false+ to change that):
428-
#
429-
# number_to_human(12.00001) # => "12"
430-
# number_to_human(12.00001, strip_insignificant_zeros: false) # => "12.0"
431-
#
432-
# ==== Custom Unit Quantifiers
433-
#
434-
# You can also use your own custom unit quantifiers:
435-
#
436-
# number_to_human(500000, units: { unit: 'ml', thousand: 'lt' }) # => "500 lt"
437-
#
438-
# If in your I18n locale you have:
439-
#
440-
# distance:
441-
# centi:
442-
# one: "centimeter"
443-
# other: "centimeters"
444-
# unit:
445-
# one: "meter"
446-
# other: "meters"
447-
# thousand:
448-
# one: "kilometer"
449-
# other: "kilometers"
450-
# billion: "gazillion-distance"
451-
#
452-
# Then you could do:
453-
#
454-
# number_to_human(543934, units: :distance) # => "544 kilometers"
455-
# number_to_human(54393498, units: :distance) # => "54400 kilometers"
456-
# number_to_human(54393498000, units: :distance) # => "54.4 gazillion-distance"
457-
# number_to_human(343, units: :distance, precision: 1) # => "300 meters"
458-
# number_to_human(1, units: :distance) # => "1 meter"
459-
# number_to_human(0.34, units: :distance) # => "34 centimeters"
371+
# [+:locale+]
372+
# The locale to use for formatting. Defaults to the current locale.
373+
#
374+
# [+:precision+]
375+
# The level of precision. Defaults to 3.
376+
#
377+
# number_to_human(123456, precision: 2) # => "120 Thousand"
378+
# number_to_human(123456, precision: 4) # => "123.5 Thousand"
379+
#
380+
# [+:round_mode+]
381+
# Specifies how rounding is performed. See +BigDecimal.mode+. Defaults to
382+
# +:default+.
383+
#
384+
# number_to_human(123456, precision: 2, round_mode: :up)
385+
# # => "130 Thousand"
386+
#
387+
# [+:significant+]
388+
# Whether +:precision+ should be applied to significant digits instead of
389+
# fractional digits. Defaults to true.
390+
#
391+
# [+:separator+]
392+
# The decimal separator. Defaults to <tt>"."</tt>.
393+
#
394+
# number_to_human(123456, precision: 4, separator: ",")
395+
# # => "123,5 Thousand"
396+
#
397+
# [+:delimiter+]
398+
# The thousands delimiter. Defaults to <tt>","</tt>.
399+
#
400+
# [+:strip_insignificant_zeros+]
401+
# Whether to remove insignificant zeros after the decimal separator.
402+
# Defaults to true.
403+
#
404+
# number_to_human(1000000) # => "1 Million"
405+
# number_to_human(1000000, strip_insignificant_zeros: false) # => "1.00 Million"
406+
# number_to_human(10.01) # => "10"
407+
# number_to_human(10.01, strip_insignificant_zeros: false) # => "10.0"
408+
#
409+
# [+:format+]
410+
# The format of the output. <tt>%n</tt> represents the number, and
411+
# <tt>%u</tt> represents the quantifier (e.g., "Thousand"). Defaults to
412+
# <tt>"%n %u"</tt>.
413+
#
414+
# [+:units+]
415+
# A Hash of custom unit quantifier names.
416+
#
417+
# number_to_human(1, units: { unit: "m", thousand: "km" }) # => "1 m"
418+
# number_to_human(100, units: { unit: "m", thousand: "km" }) # => "100 m"
419+
# number_to_human(1000, units: { unit: "m", thousand: "km" }) # => "1 km"
420+
# number_to_human(100000, units: { unit: "m", thousand: "km" }) # => "100 km"
421+
# number_to_human(10000000, units: { unit: "m", thousand: "km" }) # => "10000 km"
422+
#
423+
# The following keys are supported for integer units: +:unit+, +:ten+,
424+
# +:hundred+, +:thousand+, +:million+, +:billion+, +:trillion+,
425+
# +:quadrillion+. Additionally, the following keys are supported for
426+
# fractional units: +:deci+, +:centi+, +:mili+, +:micro+, +:nano+,
427+
# +:pico+, +:femto+.
428+
#
429+
# The Hash can also be defined as a scope in an I18n locale. For example:
430+
#
431+
# en:
432+
# distance:
433+
# centi:
434+
# one: "centimeter"
435+
# other: "centimeters"
436+
# unit:
437+
# one: "meter"
438+
# other: "meters"
439+
# thousand:
440+
# one: "kilometer"
441+
# other: "kilometers"
442+
#
443+
# Then it can be specified by name:
444+
#
445+
# number_to_human(1, units: :distance) # => "1 meter"
446+
# number_to_human(100, units: :distance) # => "100 meters"
447+
# number_to_human(1000, units: :distance) # => "1 kilometer"
448+
# number_to_human(100000, units: :distance) # => "100 kilometers"
449+
# number_to_human(10000000, units: :distance) # => "10000 kilometers"
450+
# number_to_human(0.1, units: :distance) # => "10 centimeters"
451+
# number_to_human(0.01, units: :distance) # => "1 centimeter"
452+
#
460453
def number_to_human(number, options = {})
461454
NumberToHumanConverter.convert(number, options)
462455
end

0 commit comments

Comments
 (0)