@spec number_to_si(NumberFormatter.t(), Keyword.t()) :: String.t()

Format numbers using SI notation

Parameters

• number - A value to convert. Can be any value that implements NumberFormatter.Conversion.to_float/1.

• options - A keyword list of options. See the documentation below for all available options.

Options

• :base - Use 1024 if you wish to format bytes. Default: 1000

• :separator - The string to place between the scaled number and the prefix + unit. Perhaps you want a space here. Default: ""

• :unit - The unit of measurement, e.g. "M" for Meters. Default: ""

• :precision - The number of decimal places to include. Default: 2

• :trim - Trim trailing zeros. Default: false

Default configuration for these options can be specified in the NumberFormatter application configuration.

config :number_formatter,
  si: [
    separator: " ",
    precision: 4,
    trim: true
  ]

Examples

iex> NumberFormatter.SI.number_to_si(nil)
nil

iex> NumberFormatter.SI.number_to_si(1210000000, unit: "W")
"1.21GW"

iex> NumberFormatter.SI.number_to_si(1210000000, unit: "W", precision: 1)
"1.2GW"

iex> NumberFormatter.SI.number_to_si(1210000000, unit: "W", precision: 3, separator: " ")
"1.210 GW"

iex> NumberFormatter.SI.number_to_si(1210000000, unit: "W", precision: 5, trim: true)
"1.21GW"

iex> NumberFormatter.SI.number_to_si(1210000000)
"1.21G"

iex> NumberFormatter.SI.number_to_si(Decimal.new(1210000000))
"1.21G"

iex> NumberFormatter.SI.number_to_si(~c"charlist")
** (ArgumentError) number must be a float, integer or implement `NumberFormatter.Conversion` protocol, was ~c"charlist"