Money.parse
parse
, go back to Money module for more information.
Specs
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 parsedoptions
is a keyword list of options that is passed toMoney.new/3
with the exception of the options listed below
Options
:backend
is any module() that includesuse Cldr
and therefore is aCldr
backend module(). The default isMoney.default_backend()
:locale
is any valid locale returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
The default is<backend>.get_locale()
:only
is anatom
or list ofatoms
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 anatom
or list ofatoms
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 than0.0
and less than or equal to1.0
which is used as input to theString.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 than0.8
in order to reduce false positives.:default_currency
is any valid currency code orfalse
that will used if no currency code, symbol or description is indentified in the parsed string. The default isnil
which means that the default currency associated with the:locale
option will be used. Iffalse
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\"."}}