Macro uom::unit

source ·
macro_rules! unit {
    (
        system: $system:path;
        quantity: $quantity:path;

        $($(#[$unit_attr:meta])* @$unit:ident: $($conversion:expr),+;
            $abbreviation:expr, $singular:expr, $plural:expr;)+
    ) => { ... };
    (
        @units $($(#[$unit_attr:meta])* @$unit:ident: $($conversion:expr),+;
            $abbreviation:expr, $singular:expr, $plural:expr;)+
    ) => { ... };
    (@unit $(#[$unit_attr:meta])+ @$unit:ident $plural:expr) => { ... };
    (@unit @$unit:ident $plural:expr) => { ... };
    (@coefficient $factor:expr, $const:expr) => { ... };
    (@coefficient $factor:expr) => { ... };
    (@constant $op:ident $factor:expr, $const:expr) => { ... };
    (@constant $op:ident $factor: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). @... match arms are considered private.

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).
  • $conversion: Conversion (coefficient and constant factor) from the unit to the base unit of the quantity (e.g. 3.048_E-1 to convert foot to meter. 1.0_E0, 273.15_E0 to convert celsius to kelvin.). The coefficient is required and the constant factor is optional. 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";
}