@spec all() :: [BeamLabCountries.Currency.t()]

Returns all currencies as a list of Currency structs, sorted by code.

Examples

iex> currencies = BeamLabCountries.Currencies.all()
iex> length(currencies) > 100
true
iex> %BeamLabCountries.Currency{} = hd(currencies)

@spec all_codes() :: [String.t()]

Returns all currency codes as a list.

Examples

iex> codes = BeamLabCountries.Currencies.all_codes()
iex> "USD" in codes
true
iex> "EUR" in codes
true

@spec count() :: non_neg_integer()

Returns the count of supported currencies.

Examples

iex> BeamLabCountries.Currencies.count()
155

@spec countries_for_currency(String.t()) :: [BeamLabCountries.Country.t()]

Returns all countries that use a given currency.

Examples

iex> countries = BeamLabCountries.Currencies.countries_for_currency("EUR")
iex> length(countries) > 10
true
iex> "Germany" in Enum.map(countries, & &1.name)
true

iex> countries = BeamLabCountries.Currencies.countries_for_currency("USD")
iex> "United States of America" in Enum.map(countries, & &1.name)
true

@spec decimal_digits(String.t()) :: non_neg_integer() | nil

Returns the number of decimal digits for the given currency.

This is useful for formatting currency amounts correctly. Most currencies use 2 decimal places, but some (like JPY) use 0, and others (like BHD, KWD) use 3.

Examples

iex> BeamLabCountries.Currencies.decimal_digits("USD")
2

iex> BeamLabCountries.Currencies.decimal_digits("JPY")
0

iex> BeamLabCountries.Currencies.decimal_digits("KWD")
3

iex> BeamLabCountries.Currencies.decimal_digits("INVALID")
nil

@spec for_country(String.t()) :: BeamLabCountries.Currency.t() | nil

Returns the Currency struct for a given country's alpha2 code.

Uses the currency_code field from the country data.

Examples

iex> currency = BeamLabCountries.Currencies.for_country("US")
iex> currency.code
"USD"

iex> currency = BeamLabCountries.Currencies.for_country("JP")
iex> currency.code
"JPY"

iex> BeamLabCountries.Currencies.for_country("INVALID")
nil

@spec format(number(), String.t(), keyword()) :: String.t() | nil

Formats an amount with the currency symbol.

Uses the currency's decimal_digits to format the number correctly.

Options

• :native - Use the native symbol instead of international symbol (default: false)
• :symbol_position - Position of symbol, :before or :after (default: :before)

Examples

iex> BeamLabCountries.Currencies.format(1234.56, "USD")
"$1,234.56"

iex> BeamLabCountries.Currencies.format(1234, "JPY")
"¥1,234"

iex> BeamLabCountries.Currencies.format(1234.567, "KWD")
"KD1,234.567"

iex> BeamLabCountries.Currencies.format(1234.56, "EUR", symbol_position: :after)
"1,234.56€"

iex> BeamLabCountries.Currencies.format(1234.56, "RUB", native: true)
"₽1,234.56"

iex> BeamLabCountries.Currencies.format(-1234.56, "USD")
"$-1,234.56"

iex> BeamLabCountries.Currencies.format(-0.5, "USD")
"$-0.50"

Intended for display purposes only; uses float arithmetic.

@spec get(String.t()) :: BeamLabCountries.Currency.t() | nil

Returns a Currency struct for the given ISO 4217 currency code.

Examples

iex> currency = BeamLabCountries.Currencies.get("USD")
iex> currency.name
"US Dollar"
iex> currency.symbol
"$"

iex> BeamLabCountries.Currencies.get("EUR")
%BeamLabCountries.Currency{code: "EUR", name: "Euro", name_plural: "euros", symbol: "€", symbol_native: "€", decimal_digits: 2}

iex> BeamLabCountries.Currencies.get("INVALID")
nil

@spec get!(String.t()) :: BeamLabCountries.Currency.t()

Returns a Currency struct for the given ISO 4217 currency code.

Raises ArgumentError if the currency code is not found.

Examples

iex> BeamLabCountries.Currencies.get!("USD").name
"US Dollar"

iex> BeamLabCountries.Currencies.get!("INVALID")
** (ArgumentError) Unknown currency code: INVALID

@spec name(String.t()) :: String.t() | nil

Returns the currency name for the given code.

Examples

iex> BeamLabCountries.Currencies.name("USD")
"US Dollar"

iex> BeamLabCountries.Currencies.name("EUR")
"Euro"

iex> BeamLabCountries.Currencies.name("INVALID")
nil

@spec symbol(String.t()) :: String.t() | nil

Returns the currency symbol for the given code.

Examples

iex> BeamLabCountries.Currencies.symbol("USD")
"$"

iex> BeamLabCountries.Currencies.symbol("EUR")
"€"

iex> BeamLabCountries.Currencies.symbol("GBP")
"£"

iex> BeamLabCountries.Currencies.symbol("INVALID")
nil

@spec symbol_native(String.t()) :: String.t() | nil

Returns the native currency symbol for the given code.

The native symbol is the symbol used in the currency's home country, which may differ from the international symbol.

Examples

iex> BeamLabCountries.Currencies.symbol_native("JPY")
"￥"

iex> BeamLabCountries.Currencies.symbol_native("RUB")
"₽"

iex> BeamLabCountries.Currencies.symbol_native("INVALID")
nil

@spec valid?(String.t()) :: boolean()

Checks if a currency code is valid.

Examples

iex> BeamLabCountries.Currencies.valid?("USD")
true

iex> BeamLabCountries.Currencies.valid?("usd")
true

iex> BeamLabCountries.Currencies.valid?("INVALID")
false