Elex.Unit (Elex v0.4.2)

View Source

A unit of measure as a canonical monomial and a denominator coefficient.

Evaluate returns a unit with a monomial and a denominator coefficient (per, default 1). Zero exponents are dropped. Names are not split on trailing digits (m2 stays %{"m2" => 1}). Inspect always formats the monomial with | and ^ (m^2, m | s, m | s^2). A single exponent-1 symbol prints as that symbol (N, mm). A coefficient greater than 1 prints after | (L | 100 km, 1 | 100 s).

same?/2 compares monomials and per. convertible?/3 takes a catalog and is true when both units have the same dimension vector (m and km of :length), ignoring per. compatible?/3 maps a unit monomial to a category formula and compares it to a category (cm | s vs :speed), also ignoring per.

Fields

  • :monomial - A map of symbols to integer exponents
  • :per - A positive integer denominator coefficient, default 1

Examples

%Elex.Unit{monomial: %{"m" => 1}}
%Elex.Unit{monomial: %{"m" => 1, "s" => -1}}
%Elex.Unit{monomial: %{"L" => 1, "km" => -1}, per: 100}

Summary

Types

A monomial of unit symbols to integer exponents.

t()

A unit as a canonical monomial.

Functions

Returns true when unit's category formula matches category in catalog.

Returns true when both units have the same dimension vector in catalog.

Builds a unit from a monomial.

Builds a unit from a formula string or monomial map.

Same as new/1, but returns the unit or raises ArgumentError.

Types

monomial()

@type monomial() :: %{optional(String.t()) => integer()}

A monomial of unit symbols to integer exponents.

t()

@type t() :: %Elex.Unit{monomial: monomial(), per: pos_integer()}

A unit as a canonical monomial.

Functions

compatible?(unit, category, catalog)

@spec compatible?(t(), atom(), Elex.Units.Catalog.t()) :: boolean()

Returns true when unit's category formula matches category in catalog.

Each symbol in the unit monomial is mapped to its category and exponents are combined. The result is compared to the category's formula (or dim). A pure power of a derived category matches that category's stored dimension scaled by the same exponent. cm | s is compatible with :speed even if cm/s is not a registered unit.

convertible?(left, right, catalog)

@spec convertible?(t(), t(), Elex.Units.Catalog.t()) :: boolean()

Returns true when both units have the same dimension vector in catalog.

A pure power of a derived category (%{volume => n}) matches that category's stored dimension scaled by n. A mixed vector is compared as stored. Unknown symbols are not convertible.

from_monomial(monomial)

@spec from_monomial(monomial()) :: t() | nil

Builds a unit from a monomial.

An empty monomial is invalid (nil).

new(source)

@spec new(String.t() | monomial()) :: {:ok, t()} | {:error, String.t()}

Builds a unit from a formula string or monomial map.

An empty monomial (%{} or only zero exponents) is an error.

Returns

  • {:ok, unit} - A parsed unit
  • {:error, String.t()} - The formula could not be parsed

new!(source)

@spec new!(String.t() | monomial()) :: t()

Same as new/1, but returns the unit or raises ArgumentError.

same?(left, right)

@spec same?(t(), t()) :: boolean()