Crutches.Format.Number.as_human

[mykewould]

@doc ~S"""
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 `as_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).

The `as_human!` method raises an exception if the input is not a valid 
number

# 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

  iex> Number.as_human(123)                                          
  "123"

  iex> Number.as_human(1234)                                         
  "1.23 Thousand"

  iex> Number.as_human(12345)                                        
  "12.3 Thousand"

  iex> Number.as_human(1234567)                                      
  "1.23 Million"

  iex> Number.as_human(1234567890)                                   
  "1.23 Billion"

  iex> Number.as_human(1234567890123)                                
  "1.23 Trillion"

  iex> Number.as_human(1234567890123456)                             
  "1.23 Quadrillion"

  iex> Number.as_human(1234567890123456789)                          
  "1230 Quadrillion"

  iex> Number.as_human(489939, precision: 2)                         
  "490 Thousand"

  iex> Number.as_human(489939, precision: 4)                         
  "489.9 Thousand"

  iex> Number.as_human(1234567, precision: 4, significant: false)    
  "1.2346 Million"

  iex> Number.as_human(1234567, precision: 1,separator: ',', significant: false)
  "1,2 Million"

  iex> Number.as_human(500000000, precision: 5)                      
  "500 Million"

  iex> Number.as_human(12345012345, significant: false)              
  "12.345 Billion"

  iex> Number.as_human!("abc")
  ** (ArithmeticError) bad input number

"""

[druzn3k]

Updated the description of the issue

[druzn3k]

working on this 👍