Search documentation of bb

# BB.Unit (bb v0.17.0)

Copy Markdown View Source

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}

# to_string!(unit, options \\ [])

    @spec to_string!(
      Localize.Unit.t() | [Localize.Unit.t()],
      keyword()
    ) :: String.t()

Delegates to `Localize.Unit.to_string!/2`.

# unit_name(name)

    @spec unit_name(atom() | binary()) :: binary()

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

    iex> BB.Unit.unit_name(:newton_meter)
    "newton-meter"

    iex> BB.Unit.unit_name("meter_per_second")
    "meter-per-second"

    iex> BB.Unit.unit_name("meter")
    "meter"

# validate_unit(name)

    @spec validate_unit(atom() | binary()) ::
      {:ok, Localize.Unit.t()} | {:error, Exception.t()}

Validate that an identifier resolves to a known unit.

Returns `{:ok, unit}` for a known unit, `{:error, exception}` otherwise.