Cldr.Unit.Parser (Cldr Units v3.5.2) View Source

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.

Link to this section Summary

Functions

Returns the canonical unit name for a unit

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

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

Link to this section Functions

Link to this function

canonical_unit_name(unit_string)

View Source

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\""}}
Link to this function

canonical_unit_name!(unit_string)

View Source

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"

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

Specs

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: Ratio.new(144115188075855875, 144115188075855872),
       offset: 0
     }}
  ],
  [
    {:light_year,
     %Cldr.Unit.Conversion{
       base_unit: [:meter],
       factor: 9460730000000000,
       offset: 0
     }}
  ]}}
Link to this function

parse_unit!(unit_string)

View Source