# `Localize.Number.Parser`
[🔗](https://github.com/elixir-localize/localize/blob/v0.6.0/lib/localize/number/parser.ex#L1)

Functions for parsing numbers and currencies from strings
in a locale-aware manner.

The parser handles locale-specific digit transliteration,
grouping separators, and decimal separators to convert
localized number strings back into Elixir numeric values.

# `per`

```elixir
@type per() :: :percent | :permille
```

# `find_and_replace`

```elixir
@spec find_and_replace(map(), String.t(), float() | nil) ::
  {:ok, list()} | {:error, Exception.t()}
```

Finds and replaces substrings from a map at the beginning
and/or end of a string.

### Arguments

* `string_map` is a map of `%{search_string => replacement}`.

* `string` is the string to search.

* `fuzzy` is an optional float for fuzzy matching.

### Returns

* `{:ok, list}` with replacements applied.

* `{:error, exception}` if no match found.

# `parse`

```elixir
@spec parse(String.t(), Keyword.t()) ::
  {:ok, integer() | float() | Decimal.t()} | {:error, Exception.t()}
```

Parses a string in a locale-aware manner and returns a number.

### Arguments

* `string` is any string.

* `options` is a keyword list of options.

### Options

* `:number` is one of `:integer`, `:float`, `:decimal`, or
  `nil`. The default is `nil` (auto-detect).

* `:locale` is a locale identifier. The default is `:en`.

* `:number_system` is a number system name or type.

### Returns

* `{:ok, number}` on success.

* `{:error, exception}` if parsing fails.

### Examples

    iex> Localize.Number.Parser.parse("-1_000_000.34")
    {:ok, -1000000.34}

# `resolve`

```elixir
@spec resolve(list(), (String.t(), Keyword.t() -> term()), Keyword.t()) :: list()
```

Maps a list applying a resolver function to each binary element.

### Arguments

* `list` is a list of terms.

* `resolver` is a function that takes a string and options.

* `options` is a keyword list passed to the resolver.

### Returns

* The list with binary elements resolved.

# `resolve_currencies`

```elixir
@spec resolve_currencies([String.t() | number()], Keyword.t()) :: [
  atom() | String.t() | number()
]
```

Resolves currencies from strings within a list.

### Arguments

* `list` is a list of strings and numbers.

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is `:en`.

* `:only` is a filter for currencies to include.

* `:except` is a filter for currencies to exclude.

* `:fuzzy` is a float for fuzzy matching via `String.jaro_distance/2`.

### Returns

* A list with currency strings replaced by currency code atoms.

# `resolve_currency`

```elixir
@spec resolve_currency(String.t(), Keyword.t()) ::
  [atom() | String.t()] | {:error, Exception.t()}
```

Resolves a currency from the beginning and/or end of a string.

### Arguments

* `string` is a string potentially containing a currency name or symbol.

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is `:en`.

* `:only` is a filter for currencies to include.

* `:except` is a filter for currencies to exclude.

* `:fuzzy` is a float for fuzzy matching.

### Returns

* A list with the currency code and remainder, or
  `{:error, exception}`.

# `resolve_per`

```elixir
@spec resolve_per(String.t(), Keyword.t()) ::
  [per() | String.t()] | {:error, Exception.t()}
```

Resolves percent or permille from a string.

### Arguments

* `string` is a string potentially containing percent
  or permille symbols.

* `options` is a keyword list of options.

### Returns

* A list with the symbol replaced by `:percent` or `:permille`.

* `{:error, exception}` if no symbol found.

### Examples

    iex> Localize.Number.Parser.resolve_per("11%")
    ["11", :percent]

# `resolve_pers`

```elixir
@spec resolve_pers([String.t() | number()], Keyword.t()) :: [
  per() | String.t() | number()
]
```

Resolves percent and permille symbols from strings within a list.

### Arguments

* `list` is a list of strings and numbers.

* `options` is a keyword list of options.

### Returns

* A list with percent/permille strings replaced by `:percent`
  or `:permille` atoms.

# `scan`

```elixir
@spec scan(String.t(), Keyword.t()) ::
  [String.t() | integer() | float() | Decimal.t()] | {:error, Exception.t()}
```

Scans a string in a locale-aware manner and returns a list
of strings and numbers.

### Arguments

* `string` is any string.

* `options` is a keyword list of options.

### Options

* `:number` is one of `:integer`, `:float`, `:decimal`, or
  `nil`. The default is `nil` (auto-detect).

* `:locale` is a locale identifier. The default is `:en`.

* `:number_system` is a number system name or type.

### Returns

* A list of strings and numbers.

### Examples

    iex> Localize.Number.Parser.scan("The prize is 23")
    ["The prize is ", 23]

    iex> Localize.Number.Parser.scan("1kg")
    [1, "kg"]

---

*Consult [api-reference.md](api-reference.md) for complete listing*