Skip to main content

unit

Macro unit 

Source
macro_rules! unit {
    (
        system: $system:path;
        quantity: $quantity:path;

        $($(#[$unit_attr:meta])* @$unit:ident: $coefficient:expr $(, $constant:expr)?;
            $abbreviation:expr, $singular:expr, $plural:expr;)+
    ) => { ... };
}
Expand description

Macro to implement a set of measurement units. Note that units manually defined using this macro will not be included in the quantity unit enum or associated functions, or in the FromStr implementation. Using this macro will create submodules for the underlying storage types that are enabled (e.g. mod f32).

When using the pre-built SI system included with uom this macro allows for new units to quickly be defined without requiring a release. Pull requests to add new units upstream area always greatly appreciated.

  • $system: Path to the module where the system! macro was run (e.g. uom::si).
  • quantity: Path to the module where the quantity! macro was run (e.g. uom::si::length).
  • $unit: Unit name (e.g. meter, foot).
  • $coefficient: Conversion coefficient from the unit to the base unit of the quantity (e.g. 3.048_E-1 to convert foot to meter, 1.0_E0 to convert celsius to kelvin).
  • $constant: Optional conversion constant factor from the unit to the base unit of the quantity (e.g. 273.15_E0 to convert celsius to kelvin). Note that using a unit with a non-zero constant factor is not currently supported as a base unit.
  • $abbreviation: Unit abbreviation (e.g. "m").
  • $singular: Singular unit description (e.g. "meter").
  • $plural: Plural unit description (e.g. "meters").

An example invocation is given below to add kilometers to length in a meter-kilogram-second system. The #[macro_use] attribute must be used when including the uom crate to make the unit! macro available.

#[macro_use]
extern crate uom;

unit! {
    system: crate::mks;
    quantity: crate::mks::length;

    @kilometer: 1.0E-03; "km", "kilometer", "kilometers";
}