implemented Number#as_human

[druzn3k]

This commit closes issue #25. Ugly but implements the functionalities.

[duijf]

Currently, because of the way the @doc statements are structured, all documentation is bound to the as_human! function. The non-throwing version doesn't have any docs associated with it.

Redid them for you (with the format I was experimenting with yesterday — this seems to look best):

  @doc ~S"""
  Formats and approximates `number` for human readability.

  `1200000000` becomes `"1.2 Billion"`. This is useful as larger numbers become
  harder 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).

  # Options

  - `:locale` (atom) --- Locale to be used for formatting. *Default:*
  current locale.
  - `:precision` (integer) --- Precision of the number. *Default:* `3`
  - `:significant` - If true, precision will be the # of significant_digits. If
  false, the # of fractional digits (defaults to true)
  - `:separator` (string) --- Separator between the fractional and integer
  digits. *Default:* `"."`
  - `:delimiter` (string) --- Thousands delimiter. *Default:* `""`
  -`:units` (keyword list/string) --- Keyword list of unit quantifier names,
  *or* a string containing an i18n scope pointing to it.
  - `:format` (string) --- Format of the output string. `%u` is the quantifier,
  `%n` is the number. *Default:* `"%n %u"`

  # i18n

  This function takes a keyword list of quantifier names to use for formatting.
  It supports the following keys:

  - `:unit`
  - `:ten`
  - `:hundred`
  - `:thousand`
  - `:million`
  - `:billion`
  - `:trillion`
  - `:quadrillion`
  - `:deci`
  - `:centi`
  - `:milli`
  - `:micro`
  - `:nano`
  - `:pico`
  - `:femto`

  # 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 argument in arithmetic expression
  """

  def as_human(...) do

  [...]

  @doc ~S"""
  Throwing version of `as_human`, raises if the input is not a valid number.
  """
  def as_human!(...) do

  [...]

[druzn3k]

corrected errors

[duijf]

👍

[CyrusNuevoDia]

precision = Math.max(opts[:precision], 0)