BB.Unit (bb v0.17.1)

Helpers for working with units in BB DSLs.

Wraps Localize.Unit and provides a sigil for compact unit literals. Unit identifiers can be passed as either atoms (:newton_meter) or strings ("newton-meter"); the helpers in this module convert atoms with underscores into the CLDR canonical dash form before passing them through.

Summary

Functions

compare(a, b)

Delegates to Localize.Unit.compare/2.

compatible?(a, b)

Check whether two units belong to the same dimensional category.

sigil_u(input, list)

Parse a string input as a unit.

to_string!(unit, options \\ [])

Delegates to Localize.Unit.to_string!/2.

unit_name(name)

Convert an atom or underscored string unit identifier to the CLDR canonical dash form that Localize.Unit expects.

validate_unit(name)

Validate that an identifier resolves to a known unit.

Functions

compare(a, b)

@spec compare(Localize.Unit.t(), Localize.Unit.t()) ::
  :lt | :eq | :gt | {:error, Exception.t()}

Delegates to Localize.Unit.compare/2.

compatible?(a, b)

@spec compatible?(
  Localize.Unit.t() | atom() | binary(),
  Localize.Unit.t() | atom() | binary()
) ::
  boolean()

Check whether two units belong to the same dimensional category.

Accepts atoms or strings as the second argument and translates them to the CLDR canonical form. Either argument may also be a Localize.Unit struct.

sigil_u(input, list)

@spec sigil_u(
  binary(),
  charlist()
) :: Localize.Unit.t() | no_return()

Parse a string input as a unit.

The input should be a magnitude (integer or float) followed by a unit name. Whitespace between the magnitude and unit is optional.

Units are generally referred to in the singular, even if it doesn't read as nicely, for example meter_per_second rather than meters_per_second. For a full list of supported units, see the Localize documentation.

Examples

Integer magnitudes:

iex> import BB.Unit
iex> u = ~u(5 meter)
iex> {u.name, u.value}
{"meter", 5}

Float magnitudes:

iex> import BB.Unit
iex> u = ~u(0.1 meter)
iex> {u.name, u.value}
{"meter", 0.1}

Negative values:

iex> import BB.Unit
iex> u = ~u(-90 degree)
iex> {u.name, u.value}
{"degree", -90}

Whitespace is optional:

iex> import BB.Unit
iex> u = ~u(100centimeter)
iex> {u.name, u.value}
{"centimeter", 100}

Compound units use underscores, which are translated to the CLDR dash form:

iex> import BB.Unit
iex> u = ~u(10 meter_per_second)
iex> {u.name, u.value}
{"meter-per-second", 10}