Cldr.Number.Parser (Cldr Numbers v2.17.0-rc.0) View Source
Functions for parsing numbers and currencies from a string.
Link to this section Summary
Functions
Parse a string locale-aware manner and return a number.
Resolve curencies from strings within a list.
Resolve a currency from a string
Scans a string locale-aware manner and returns a list of strings and numbers.
Link to this section Functions
Parse a string locale-aware manner and return a number.
Arguments
string
is anyString.t
options
is a keyword list of options
Options
:number
is one of:integer
,:float
,:decimal
ornil
. The default isnil
meaning that the type auto-detected as either aninteger
or afloat
.:backend
is any module that includesuse Cldr
and is therefore a CLDR backend module. The default isCldr.default_backend/0
.:locale
is any locale returned byCldr.known_locale_names/1
or aCldr.LanguageTag.t
. The default isoptions[:backend].get_locale/1
.
Returns
A number of the requested or default type or
{:error, string}
if no number could be determined
Notes
This function parses a string to return a number but
in a locale-aware manner. It will normalise grouping
characters and decimal separators, different forms of
the +
and -
symbols that appear in Unicode and
strips any _
characters that might be used for
formatting in a string. It then parses the number
using the Elixir standard library functions.
Examples
iex> Cldr.Number.Parser.parse("+1.000,34", locale: "de")
{:ok, 1000.34}
iex> Cldr.Number.Parser.parse("-1_000_000.34")
{:ok, -1000000.34}
iex> Cldr.Number.Parser.parse("1.000", locale: "de", number: :integer)
{:ok, 1000}
iex> Cldr.Number.Parser.parse("+1.000,34", locale: "de", number: :integer)
{:error, "+1.000,34"}
Resolve curencies from strings within a list.
Arguments
list
is any list in which currency names and symbols are expectedoptions
is a keyword list of options
Options
:backend
is any module() that includesuse Cldr
and therefore is aCldr
backend module(). The default isCldr.default_backend/0
:locale
is any valid locale returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
The default isoptions[: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 toString.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.
Returns
An ISO4217 currency code as an atom or
{:error, {exception, message}}
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> Cldr.Number.Parser.scan("100 US dollars")
...> |> Cldr.Number.Parser.resolve_currencies
[100, :USD]
iex> Cldr.Number.Parser.scan("100 eurosports")
...> |> Cldr.Number.Parser.resolve_currencies(fuzzy: 0.8)
[100, :EUR]
iex> Cldr.Number.Parser.scan("100 dollars des États-Unis")
...> |> Cldr.Number.Parser.resolve_currencies(locale: "fr")
[100, :USD]
Resolve a currency from a string
Arguments
list
is any list in which currency names and symbols are expectedoptions
is a keyword list of options
Options
:backend
is any module() that includesuse Cldr
and therefore is aCldr
backend module(). The default isCldr.default_backend/0
:locale
is any valid locale returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
The default isoptions[: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 toString.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.
Returns
An ISO417 currency code as an atom or
{:error, {exception, message}}
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> Cldr.Number.Parser.resolve_currency("US dollars")
:USD
iex> Cldr.Number.Parser.resolve_currency("100 eurosports", fuzzy: 0.75)
:EUR
iex> Cldr.Number.Parser.resolve_currency("dollars des États-Unis", locale: "fr")
:USD
iex> Cldr.Number.Parser.resolve_currency("not a known currency", locale: "fr")
{:error,
{Cldr.UnknownCurrencyError,
"The currency \"not a known currency\" is unknown or not supported"}}
Scans a string locale-aware manner and returns a list of strings and numbers.
Arguments
string
is anyString.t
options
is a keyword list of options
Options
:number
is one of:integer
,:float
,:decimal
ornil
. The default isnil
meaning that the type auto-detected as either aninteger
or afloat
.:backend
is any module that includesuse Cldr
and is therefore a CLDR backend module. The default isCldr.default_backend/0
.:locale
is any locale returned byCldr.known_locale_names/1
or aCldr.LanguageTag.t
. The default isoptions[:backend].get_locale/1
.
Returns
- A list of strings and numbers
Notes
Number parsing is performed by Cldr.Number.Parser.parse/2
and any options provided are passed to that function.
Examples
iex> Cldr.Number.Parser.scan("£1_000_000.34")
["£", 1000000.34]
iex> Cldr.Number.Parser.scan("I want £1_000_000 dollars")
["I want £", 1000000, " dollars"]
iex> Cldr.Number.Parser.scan("The prize is 23")
["The prize is ", 23]
iex> Cldr.Number.Parser.scan("The lottery number is 23 for the next draw")
["The lottery number is ", 23, " for the next draw"]
iex> Cldr.Number.Parser.scan("The loss is -1.000 euros", locale: "de", number: :integer)
["The loss is ", -1000, " euros"]