Crate uom [−] [src]

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.15.0 or later. Add this to your Cargo.toml:

[dependencies]
uom = "0.15.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 = length / time;
    //let error = length + time; // error[E0308]: mismatched types
}

See examples provided with the crate 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.

Features

uom has four Cargo features: f32, f64, si, and std. The features are described below and 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.15.0", default-features = false, features = ["f32", "f64", "si", "std"] }

f32, f64 -- Features to enable underlying storage types. At least one of these features must be enabled.
si -- Feature to include the pre-built International System of Units (SI).
std -- Feature to compile with standard library support. Disabling this feature compiles uom with no_std. Note that some functions such as sqrt require std to be enabled.

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 both f32 and f64 as the underlying storage type.

Once codegen bug #38269 is resolved.

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

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 above, without any additional terms or conditions.

Modules

si	International System of Units (SI) and International System of Quantities (ISQ) implementations.

Macros

ISQ	Macro to implement `quantity` type aliases for a specific system of units and value storage type.
prefix	Macro to implement the SI prefixes for multiples of units and submultiples 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.
system	Macro to implement a system of quantities.