Home / Docs / Language guide / Kinds and types

Units of measure

What it does

A unit is part of an integer type. Int of Meter and Int of Second are distinct, so the checker rejects mixing them before the program runs. Units exist only during checking: they are erased from runtime values and outputs. Use measure declarations for base units and derived scales, then write of on an integer type.

una
-- edition 0.3
module shop

pub measure Meter

pub measure Kilometer = 1000 * Meter

pub measure Second

pub kind Speed = Int of Meter / Second in 0..300

pub distance(km: Int of Kilometer) -> Int of Meter = km.convert()

Forms

ebnf
measure_decl = [ "pub" ] "measure" upper_ident [ "=" unit_expr ] NEWLINE ;
type         = [ label ] type_core [ "of" unit_expr ] [ "in" range ] ;
unit_expr    = unit_term { ( "*" | "/" ) unit_term } ;
unit_term    = upper_ident | "(" unit_expr ")" | integer_literal ;

Examples

Conversions use the expected return type. The unit remains part of the result type:

una
-- edition 0.3
module shop

pub measure Meter

pub measure Kilometer = 1000 * Meter

pub kilometers_to_meters(km: Int of Kilometer) -> Int of Meter = km.convert()

pub meters_from_raw(value: Int) -> Int of Meter = value.measured()

pub display_magnitude(distance: Int of Meter) -> Int = distance.magnitude()

Adding matching units is accepted, while a unitless literal takes the other operand's unit:

una
-- edition 0.3
module shop

pub measure Meter

pub add(distance: Int of Meter) -> Int of Meter = distance + 5

Edge cases

Different dimensions do not mix. Convert only between units of the same dimension. magnitude() removes the dimensional guarantee and should be used only when the raw count is intended:

una
-- edition 0.3
-- fails with U2028
module shop

pub measure Meter

pub measure Second

pub add(distance: Int of Meter, elapsed: Int of Second) -> Int of Meter = distance + elapsed

Conversions need a target type. Without an expected unit, the checker cannot choose the converted scale. A conversion from meters to kilometers also is not exact; make any division explicit through magnitude() and measured() where appropriate:

una
-- edition 0.3
-- fails with U2030
module shop

pub measure Meter

pub measure Kilometer = 1000 * Meter

pub convert_without_target(distance: Int of Kilometer) -> Bool
=
  let value = distance.convert()
  true

Units are compile-time only. Interpolation and JSON expose the magnitude, without a unit name. magnitude() has the same effect in the type system: it returns an ordinary integer.

Diagnostics

Edition

Edition 0.3, a preview. In editions 0.1 and 0.2, a measure declaration and of after a type are syntax errors (U0101). Edition 0.4 has every construct of edition 0.3 (spec/13 §7).

Normative source