# `Cldr.Unit.Parser`
[🔗](https://github.com/elixir-cldr/cldr_units/blob/v3.20.3/lib/cldr/unit/parser.ex#L1)

Parse unit strings into composable
unit structures.  These structures can
then be used to produced localized output,
or to be converted to another unit of the
same unit category.

# `canonical_unit_name`

Returns the canonical unit name
for a unit

## Arguments

* `unit_string` is any string representing
  a unit such as `light_year_per_week`.

## Returns

* `{:ok, canonical_name}` or

* `{:error, {exception, reason}}`

## Examples

    iex> Cldr.Unit.Parser.canonical_unit_name "meter"
    {:ok, :meter}

    iex> Cldr.Unit.Parser.canonical_unit_name "meter meter"
    {:ok, :square_meter}

    iex> Cldr.Unit.Parser.canonical_unit_name "meter per kilogram"
    {:ok, "meter_per_kilogram"}

    iex> Cldr.Unit.Parser.canonical_unit_name "meter kilogram"
    {:ok, "kilogram_meter"}

    iex> Cldr.Unit.Parser.canonical_unit_name "meter kilogram per fluxom"
    {:error, {Cldr.UnknownUnitError, "Unknown unit was detected at \"fluxom\""}}

# `canonical_unit_name!`

Returns the canonical unit name
for a unit or raises on error

## Arguments

* `unit_string` is any string representing
  a unit such as `light_year_per_week`.

## Returns

* `{:ok, canonical_name}` or

* raises an exception

## Examples

    iex> Cldr.Unit.Parser.canonical_unit_name! "meter"
    :meter

    iex> Cldr.Unit.Parser.canonical_unit_name! "meter meter"
    :square_meter

    iex> Cldr.Unit.Parser.canonical_unit_name! "meter per kilogram"
    "meter_per_kilogram"

    iex> Cldr.Unit.Parser.canonical_unit_name! "meter kilogram"
    "kilogram_meter"

    iex> Cldr.Unit.Parser.canonical_unit_name "curr-usd"
    {:ok, "curr_usd"}

    iex> Cldr.Unit.Parser.canonical_unit_name "curr-usd-per-kilogram"
    {:ok, "curr_usd_per_kilogram"}

    => Cldr.Unit.Parser.canonical_unit_name! "meter kilogram per fluxom"
    ** (CaseClauseError) no case clause matching: {:error,
        {Cldr.UnknownUnitError, "Unknown unit was detected at "fluxom""}}

# `parse_unit`

```elixir
@spec parse_unit(String.t()) ::
  {:ok, [Cldr.Unit.base_conversion()]}
  | {:ok, {[Cldr.Unit.base_conversion()], [Cldr.Unit.base_conversion()]}}
  | {:error, {module(), String.t()}}
```

Parses a unit name expressed as a string and returns the parsed
name or an error.

## Arguments

* `unit_string` is a unit name (such as
  "meter") as a `String.t()`

## Returns

* `{:ok, normalized_unit}` or

* `{:error, {exception, reason}}`

## Notes

A normalised unit is a `2-tuple` with
the first element a list of standard units
that are before the first "per" in the
unit name.  The second element is a list
of standard units after the first "per"
(if any).

The structure of the standard unit is
`{standard_unit, conversion_to_base_unit}`.

This function is not normally called by
consumers of this library. It is called by
`Cldr.Unit.validate_unit/1` which is the
main public API.

## Example

    iex> Cldr.Unit.Parser.parse_unit "kilogram per light year"
    {:ok,
     {[
        {:kilogram,
         %Cldr.Unit.Conversion{
           base_unit: [:kilogram],
           factor: 1,
           offset: 0
         }}
      ],
      [
        {:light_year,
         %Cldr.Unit.Conversion{
           base_unit: [:meter],
           factor: 9460730472580800,
           offset: 0
         }}
      ]}}

# `parse_unit!`

# `split_into_units`

---

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