Specs

parse(String.t(), Keyword.t()) :: t() | {:error, {module(), String.t()}}

Parse a string and return a Money.t or an error.

The string to be parsed is required to have a currency code and an amount. The currency code may be placed before the amount or after, but not both.

Parsing is strict. Additional text surrounding the currency code and amount will cause the parse to fail.

Arguments

• string is a string to be parsed

• options is a keyword list of options that is passed to Money.new/3 with the exception of the options listed below

Options

• :backend is any module() that includes use Cldr and therefore is a Cldr backend module(). The default is Money.default_backend()

• :locale is any valid locale returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2 The default is <backend>.get_locale()

• :only is an atom or list of atoms representing the currencies or currency types to be considered for a match. The equates to a list of acceptable currencies for parsing. See the notes below for currency types.

• :except is an atom or list of atoms representing the currencies or currency types to be not considered for a match. This equates to a list of unacceptable currencies for parsing. See the notes below for currency types.

• :fuzzy is a float greater than 0.0 and less than or equal to 1.0 which is used as input to the String.jaro_distance/2 to determine is the provided currency string is close enough to a known currency string for it to identify definitively a currency code. It is recommended to use numbers greater than 0.8 in order to reduce false positives.

• :default_currency is any valid currency code or false that will used if no currency code, symbol or description is indentified in the parsed string. The default is nil which means that the default currency associated with the :locale option will be used. If false then the currency assocated with the :locale option will not be used and an error will be returned if there is no currency in the string being parsed.

Returns

• a Money.t if parsing is successful or

• {:error, {exception, reason}} if an error is detected.

Notes

The :only and :except options accept a list of currency codes and/or currency types. The following types are recognised.

If both :only and :except are specified, the :except entries take priority - that means any entries in :except are removed from the :only entries.

• :all, the default, considers all currencies

• :current considers those currencies that have a :to date of nil and which also is a known ISO4217 currency

• :historic is the opposite of :current

• :tender considers currencies that are legal tender

• :unannotated considers currencies that don't have "(some string)" in their names. These are usually financial instruments.

Examples

iex> Money.parse("USD 100")
#Money<:USD, 100>

iex> Money.parse "USD 100,00", locale: "de"
#Money<:USD, 100.00>

iex> Money.parse("100 USD")
#Money<:USD, 100>

iex> Money.parse("100 eurosports", fuzzy: 0.8)
#Money<:EUR, 100>

iex> Money.parse("100", default_currency: :EUR)
#Money<:EUR, 100>

iex> Money.parse("100 eurosports", fuzzy: 0.9)
{:error, {Money.UnknownCurrencyError, "The currency \"eurosports\" is unknown or not supported"}}

iex> Money.parse("100 afghan afghanis")
#Money<:AFN, 100>

iex> Money.parse("100", default_currency: false)
{:error, {Money.Invalid,
  "A currency code, symbol or description must be specified but was not found in \"100\""}}

iex> Money.parse("USD 100 with trailing text")
{:error, {Money.ParseError, "Could not parse \"USD 100 with trailing text\"."}}