Formats a number according to a locale-specific predefined format or a user-defined format.

As a performance optimization, all decimal formats known at compile time are compiled into function that roughly halves the time to format a number compared to a non-precompiled format.

The available format styles for a locale can be returned by:

iex> Cldr.Number.Format.decimal_format_styles_for "en"
[:accounting, :currency, :currency_long, :percent, :scientific, :standard]

This allows a number to be formatted in a locale-specific way but using a standard method of describing the purpose of the format.

Examples

iex> Number.to_string 1234, format: :accounting, currency: "JPY"
"¥1,234"

iex> Number.to_string -1234, format: :accounting, currency: "JPY"
"(¥1,234)"

User defined formats can also be used. See Cldr.Number.Format for more information on defining number formats.

Examples:

iex> Number.to_string 12345, format: "#,##0.00"
"12,345.00"

iex> Number.to_string 12345, format: "0000.00"
"2345.00"

iex> Number.to_string 12345, format: "000000"
"012345"

# Rounds to the nearest 6.00
iex> Number.to_string 12345, format: "#,##6.00"
"12,348.00"