Search documentation of Localize

# Localize.Number.Parser (Localize v0.39.0)

Copy Markdown View Source

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.

## Summary

### Types

per()

### Functions

find_and_replace(string_map, string, fuzzy \\ nil)

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

parse(string, options \\ [])

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

resolve(list, resolver, options)

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

resolve_currencies(list, options \\ [])

Resolves currencies from strings within a list.

resolve_currency(string, options \\ [])

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

resolve_per(string, options \\ [])

Resolves percent or permille from a string.

resolve_pers(list, options \\ [])

Resolves percent and permille symbols from strings within a list.

scan(string, options \\ [])

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

## Types

# per()

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

## Functions

# find_and_replace(string_map, string, fuzzy \\ nil)

    @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(string, options \\ [])

    @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(list, resolver, options)

    @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(list, options \\ [])

    @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(string, options \\ [])

    @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(string, options \\ [])

    @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(list, options \\ [])

    @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(string, options \\ [])

    @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"]