Number.Currency (number v1.0.3)

Provides functions for converting numbers into formatted currency strings.

Link to this section Summary


Converts a number to a formatted currency string.

Link to this section Functions

Link to this function

number_to_currency(number, options \\ [])


number_to_currency(Number.t(), list()) :: String.t()

Converts a number to a formatted currency string.


  • number - A float or integer to convert.

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


  • :unit - The currency symbol to use. Default: "$"

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

  • :delimiter - The character to use to delimit the number by thousands. Default: ","

  • :separator - The character to use to separate the number from the decimal places. Default: "."

  • :format - The format of the number. This can be used to put the currency symbol in a different place. See the examples for usage. There are two supported format string placeholders:

    • %u - Represents the currency symbol, or unit.
    • %n - Represents the number.
  • :negative_format - The format of the number when it is negative. Uses the same formatting placeholders as the :format option.

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

config :number, currency: [
                  unit: "£",
                  precision: 2,
                  delimiter: ",",
                  separator: ".",
                  format: "%u%n",           # "£30.00"
                  negative_format: "(%u%n)" # "(£30.00)"


iex> Number.Currency.number_to_currency(nil)

iex> Number.Currency.number_to_currency(1000)

iex> Number.Currency.number_to_currency(1000, unit: "£")

iex> Number.Currency.number_to_currency(-1000)

iex> Number.Currency.number_to_currency(-234234.23)

iex> Number.Currency.number_to_currency(1234567890.50)

iex> Number.Currency.number_to_currency(1234567890.506)

iex> Number.Currency.number_to_currency(1234567890.506, precision: 3)

iex> Number.Currency.number_to_currency(-1234567890.50, negative_format: "(%u%n)")

iex> Number.Currency.number_to_currency(1234567890.50, unit: "R$", separator: ",", delimiter: "")

iex> Number.Currency.number_to_currency(1234567890.50, unit: "R$", separator: ",", delimiter: "", format: "%n %u")
"1234567890,50 R$"

iex> Number.Currency.number_to_currency(Decimal.from_float(50.0))

iex> Number.Currency.number_to_currency(Decimal.from_float(-100.01))

iex> Number.Currency.number_to_currency(Decimal.from_float(-100.01), unit: "$", separator: ",", delimiter: ".", negative_format: "- %u %n")
"- $ 100,01"