Crate uom

source ·
Expand description

Units of measurement is a crate that does automatic type-safe zero-cost dimensional analysis. You can create your own systems or use the pre-built International System of Units (SI) which is based on the International System of Quantities (ISQ) and includes numerous quantities (length, mass, time, …) with conversion factors for even more numerous measurement units (meter, kilometer, foot, mile, …). No more crashing your climate orbiter!

§Usage

uom requires rustc 1.65.0 or later. Add this to your Cargo.toml:

[dependencies]
uom = "0.36.0"

and this to your crate root:

extern crate uom;

The simple example below shows how to use quantities and units as well as how uom stops invalid operations:

ⓘ
extern crate uom;

use uom::si::f32::*;
use uom::si::length::kilometer;
use uom::si::time::second;

fn main() {
   let length = Length::new::<kilometer>(5.0);
   let time = Time::new::<second>(15.0);
   let velocity/*: Velocity*/ = length / time;
   let _acceleration = calc_acceleration(velocity, time);
   //let error = length + time; // error[E0308]: mismatched types

   // Get a quantity value in a specific unit.
   let time_in_nano_seconds = time.get::<uom::si::time::nanosecond>();
}

fn calc_acceleration(velocity: Velocity, time: Time) -> Acceleration {
   velocity / time
}

See examples provided with the source for more advanced usage including how to create Quantity type aliases for a different set of base units and how to create an entirely new system of quantities.

§Features

uom has multiple Cargo features for controlling available underlying storage types, the inclusion of the pre-built International System of Units (SI), support for Serde, and no_std functionality. The features are described below. f32, f64, std, and si are enabled by default. Features can be cherry-picked by using the --no-default-features and --features "..." flags when compiling uom or specifying features in Cargo.toml:

[dependencies]
uom = {
    version = "0.36.0",
    default-features = false,
    features = [
        "autoconvert", # automatic base unit conversion.
        "usize", "u8", "u16", "u32", "u64", "u128", # Unsigned integer storage types.
        "isize", "i8", "i16", "i32", "i64", "i128", # Signed integer storage types.
        "bigint", "biguint", # Arbitrary width integer storage types.
        "rational", "rational32", "rational64", "bigrational", # Integer ratio storage types.
        "complex32", "complex64", # Complex floating point storage types.
        "f32", "f64", # Floating point storage types.
        "si", "std", # Built-in SI system and std library support.
        "serde", # Serde support.
    ]
}
  • autoconvert – Feature to enable automatic conversion between base units in binary operators. Disabling the feature only allows for quantities with the same base units to directly interact. The feature exists to account for compiler limitations where zero-cost code is not generated for non-floating point underlying storage types.
  • usize, u8, u16, u32, u64, u128, isize, i8, i16, i32, i64, i128, bigint, biguint, rational, rational32, rational64, bigrational, complex32, complex64, f32, f64 – Features to enable underlying storage types. At least one of these features must be enabled. f32 and f64 are enabled by default. See the Design section for implications of choosing different underlying storage types.
  • si – Feature to include the pre-built International System of Units (SI). Enabled by default.
  • std – Feature to compile with standard library support. Disabling this feature compiles uom with no_std. Enabled by default.
  • serde – Feature to enable support for serialization and deserialization of quantities with the Serde crate. Disabled by default.

§Design

Rather than working with measurement units (meter, kilometer, foot, mile, …) uom works with quantities (length, mass, time, …). This simplifies usage because units are only involved at interface boundaries: the rest of your code only needs to be concerned about the quantities involved. This also makes operations on quantities (+, -, *, /, …) have zero runtime cost over using the raw storage type (e.g. f32).

uom normalizes values to the base unit for the quantity. Alternative base units can be used by executing the macro defined for the system of quantities (ISQ! for the SI). uom supports usize, u8, u16, u32, u64, u128, isize, i8, i16, i32, i64, i128, bigint, biguint, rational, rational32, rational64, bigrational, complex32, complex64, f32, and f64 as the underlying storage type.

A consequence of normalizing values to the base unit is that some values may not be able to be represented or can’t be precisely represented for floating point and rational underlying storage types. For example if the base unit of length is meter and the underlying storage type is i32 then values like 1 centimeter or 1.1 meter cannot be represented. 1 centimeter is normalized to 0.01 meter which can’t be stored in an i32. uom only allows units to be used safely. Users of this library will still need to be aware of implementation details of the underlying storage type including limits and precision.

§Contributing

Contributions are welcome from everyone. Submit a pull request, an issue, or just add comments to an existing item. The International Bureau of Weights and Measures is an international standards organization that publishes the SI Brochure. This document defines the SI and can be used as a comprehensive reference for changes to uom. Conversion factors for non-SI units can be found in NIST Special Publication 811.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as below, without any additional terms or conditions.

§License

Licensed under either of

at your option.

Modules§

Macros§

  • ISQ
    Macro to implement quantity type aliases for a specific system of units and value storage type.
  • impl_from
    impl_from generates generic inter-Kind implementations of From.
  • prefix
    Macro to implement the SI prefixes for multiples of units, submultiples of units and binary multiples of units.
  • quantity
    Macro to implement a quantity and associated measurement units. Note that this macro must be executed in direct submodules of the module where the system! macro was executed. @... match arms are considered private.
  • storage_types
    Macro to duplicate code on a per-storage type basis. The given code is duplicated in new modules named for each storage type. A type alias, V, is generated that code can use for the type. @... match arms are considered private.
  • system
    Macro to implement a system of quantities. @... match arms are considered private.
  • unit
    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.

Enums§

  • ConstantOp
    Operations performed on the constant portion of the conversion factor. Used to help guide optimizations when floating point underlying storage types are used.

Traits§