core

README

#Unit Core

core/unit defines Un, the runtime unit value. A unit combines a symbol, a dimension and a linear scale factor relative to that dimension's canonical base.

Offsets and logarithmic semantics are deliberately excluded. Use affine for absolute affine points such as Celsius, and logarithmic for dB/Np levels.

#Main API

Un::base(symbol, dimension) creates a base unit for a dimension.
Un::scaled(symbol, dimension, scale) creates a linear scaled unit.
mul, div and pow build compound units.
is_compatible and conversion_factor compare units by dimension.
format_unit and format_unit_with render ASCII, SI and LaTeX styles.

let meter = @unit.Un::base("m", @dimension.Dimension::length())
let second = @unit.Un::base("s", @dimension.Dimension::time())
let speed = meter / second
let accel = speed / second

Built-in unit packages under units/* provide the usual named units on top of this core type.

#
FormatStyle

source

pub(all) enum FormatStyle {
  Ascii
  Si
  Latex
} derive(Eq)

Display style for [format_unit_with] and quantity formatters.

Ascii: compact ASCII, e.g. m/s^2, factors joined with *.
Si: Unicode/SI notation, e.g. m/s², factors joined with · and exponents printed as superscripts.
Latex: LaTeX math, e.g. \mathrm{m}/\mathrm{s}^{2}, factors joined with \cdot.

#
Un

source

pub struct Un {
  repr : @FrozenLemonTee/LunarUnits/core/algebra.Monomial
Monomial
  dim : @FrozenLemonTee/LunarUnits/core/dimension.Dimension
Dimension
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A unit of measurement: a unit-symbol monomial paired with the physical dimension it measures.

The type is named Un (short for "unit").

The monomial's symbols are unit symbols (e.g. "m", "s") and its coefficient is the scale relative to the coherent base unit of that dimension — one of this unit equals scale base units. Composite units (e.g. m/s) arise from mul / div / pow, which keep the symbol structure, the scale and the dimension in sync.

Example

test {
  let meter = Un::base("m", @dimension.Dimension::length())
  let second = Un::base("s", @dimension.Dimension::time())
  let mps = meter.div(second)
  let expected = @dimension.Dimension::length().div(
    @dimension.Dimension::time(),
  )
  assert_true(mps.dimension().is_same(expected))
}

impl Div for Un

fn div(self : Un, other : Un) -> Un

source

Allows lhs / rhs as shorthand for lhs.div(rhs).

Example

test {
  let m = Un::base("m", @dimension.Dimension::length())
  let s = Un::base("s", @dimension.Dimension::time())
  assert_true((m / s).dimension().is_same(m.div(s).dimension()))
}

impl Mul for Un

fn mul(self : Un, other : Un) -> Un

source

Allows lhs * rhs as shorthand for lhs.mul(rhs).

Example

test {
  let m = Un::base("m", @dimension.Dimension::length())
  let area = m * m
  assert_true(area.dimension().is_same(@dimension.Dimension::length().pow(2)))
}

impl Show for Un

#
Un::base

source

fn Un::base(symbol : String, dim : @FrozenLemonTee/LunarUnits/core/dimension.Dimension
Dimension) -> Un

Defines a coherent base unit (scale 1) with the given symbol and dimension.

Example

test {
  let meter = Un::base("m", @dimension.Dimension::length())
  assert_eq(meter.scale(), 1.0)
  assert_true(meter.dimension().is_same(@dimension.Dimension::length()))
}

#
Un::conversion_factor

source

fn Un::conversion_factor(self : Un, target : Un) -> Double?

Returns the factor that converts a value expressed in self into one expressed in target: value_in_target = value_in_self * factor. Returns None when the units are not dimensionally compatible.

Example

test {
  let m = Un::base("m", @dimension.Dimension::length())
  let km = Un::scaled("km", @dimension.Dimension::length(), 1000.0)
  // 1 km equals 1000 m; 1 m equals 0.001 km.
  assert_true(km.conversion_factor(m) is Some(1000.0))
  assert_true(m.conversion_factor(km) is Some(0.001))
  // Incompatible dimensions cannot be converted.
  let s = Un::base("s", @dimension.Dimension::time())
  assert_true(m.conversion_factor(s) is None)
}

#
Un::dimension

source

fn Un::dimension(self : Un) -> @FrozenLemonTee/LunarUnits/core/dimension.Dimension
Dimension

Returns the physical dimension this unit measures.

Example

test {
  let meter = Un::base("m", @dimension.Dimension::length())
  assert_true(meter.dimension().is_same(@dimension.Dimension::length()))
}

#
Un::div

source

fn Un::div(self : Un, other : Un) -> Un

Divides one unit by another, composing both their symbol structure and their dimensions.

Example

test {
  let m = Un::base("m", @dimension.Dimension::length())
  let s = Un::base("s", @dimension.Dimension::time())
  let velocity = m.div(s)
  let expected = @dimension.Dimension::length().div(
    @dimension.Dimension::time(),
  )
  assert_true(velocity.dimension().is_same(expected))
}

#
Un::is_compatible

source

fn Un::is_compatible(self : Un, other : Un) -> Bool

Returns whether two units measure the same dimension (and can therefore be converted into one another).

Example

test {
  let m = Un::base("m", @dimension.Dimension::length())
  let km = Un::scaled("km", @dimension.Dimension::length(), 1000.0)
  let s = Un::base("s", @dimension.Dimension::time())
  assert_true(m.is_compatible(km))
  assert_false(m.is_compatible(s))
}

#
Un::mul

source

fn Un::mul(self : Un, other : Un) -> Un

Multiplies two units, composing both their symbol structure and their dimensions.

Example

test {
  let m = Un::base("m", @dimension.Dimension::length())
  let area = m.mul(m)
  assert_true(area.dimension().is_same(@dimension.Dimension::length().pow(2)))
}

#
Un::pow

source

fn Un::pow(self : Un, n : Int) -> Un

Raises a unit to an integer power.

Example

test {
  let m = Un::base("m", @dimension.Dimension::length())
  let volume = m.pow(3)
  assert_true(volume.dimension().is_same(@dimension.Dimension::length().pow(3)))
}

#
Un::scale

source

fn Un::scale(self : Un) -> Double

Returns the scale factor to the coherent base unit (one unit equals scale base units).

Example

test {
  let km = Un::scaled("km", @dimension.Dimension::length(), 1000.0)
  assert_eq(km.scale(), 1000.0)
}

#
Un::scaled

source

fn Un::scaled(symbol : String, dim : @FrozenLemonTee/LunarUnits/core/dimension.Dimension
Dimension, scale : Double) -> Un

Defines a scaled unit: one of it equals scale coherent base units (e.g. a kilometre is 1000 metres).

Example

test {
  let km = Un::scaled("km", @dimension.Dimension::length(), 1000.0)
  assert_eq(km.scale(), 1000.0)
}

#
format_unit

source

fn format_unit(unit : Un) -> String

Formats a unit in compact ASCII notation for user-facing display.

Positive exponents are printed in the numerator and negative exponents in the denominator. Unit scale factors are not printed; the symbolic unit name chosen at construction time is used instead. For other notations see [format_unit_with].

Example

test {
  let meter = Un::base("m", @dimension.Dimension::length())
  let second = Un::base("s", @dimension.Dimension::time())
  assert_eq(format_unit(meter / second.pow(2)), "m/s^2")
  assert_eq(format_unit(meter.pow(2)), "m^2")
}

#
format_unit_with

source

fn format_unit_with(unit : Un, style : FormatStyle) -> String

Formats a unit using the given [FormatStyle].

The numerator/denominator split and SI ordering are shared across styles; only symbol, exponent and separator rendering differ.

Example

test {
  let meter = Un::base("m", @dimension.Dimension::length())
  let second = Un::base("s", @dimension.Dimension::time())
  let accel = meter / second.pow(2)
  assert_eq(format_unit_with(accel, FormatStyle::Ascii), "m/s^2")
  assert_eq(format_unit_with(accel, FormatStyle::Si), "m/s²")
  assert_eq(
    format_unit_with(accel, FormatStyle::Latex),
    "\\mathrm{m}/\\mathrm{s}^{2}",
  )
}