[−][src]Crate uom
Units of measurement is a crate that does automatic typesafe zerocost dimensional analysis. You can create your own systems or use the prebuilt 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.37.0 or later. Add this to your Cargo.toml
:
[dependencies]
uom = "0.30.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 } 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 prebuilt 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 cherrypicked by using the
nodefaultfeatures
and features "..."
flags when compiling uom
or specifying
features in Cargo.toml:
[dependencies]
uom = {
version = "0.30.0",
defaultfeatures = 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.
"f32", "f64", # Floating point storage types.
"si", "std", # Builtin SI system and std library support.
"tryfrom", # `TryFrom` support between `Time` and `Duration`. Requires `rustc` 1.34.0.
"use_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 zerocost code is not generated for nonfloating point underlying storage types.usize
,u8
,u16
,u32
,u64
,u128
,isize
,i8
,i16
,i32
,i64
,i128
,bigint
,biguint
,rational
,rational32
,rational64
,bigrational
,f32
,f64
 Features to enable underlying storage types. At least one of these features must be enabled.f32
andf64
are enabled by default. See the Design section for implications of choosing different underlying storage types.si
 Feature to include the prebuilt International System of Units (SI). Enabled by default.std
 Feature to compile with standard library support. Disabling this feature compilesuom
withno_std
. Enabled by default.tryfrom
 Feature to enableTryFrom
support betweenTime
andDuration
. Requiresrustc
1.34.0.use_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
, 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 nonSI 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 Apache2.0 license, shall be dual licensed as below, without any additional terms or conditions.
License
Licensed under either of
 Apache License, Version 2.0, (LICENSEAPACHE or http://www.apache.org/licenses/LICENSE2.0)
 MIT license (LICENSEMIT or http://opensource.org/licenses/MIT)
at your option.
Modules
fmt  Utilities for formatting and printing quantities. 
marker  Primitive traits and types representing basic properties of types. 
si  International System of Units (SI) and International System of Quantities (ISQ) implementations. 
str  Unicode string slice manipulation for quantities. 
Macros
ISQ  Macro to implement 
impl_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

storage_types  Macro to duplicate code on a perstorage type basis. The given code is duplicated in new
modules named for each storage type. A type alias, 
system  Macro to implement a system of quantities. 
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
Conversion  Trait to identify units which have a conversion factor. 
ConversionFactor  Trait representing a conversion factor. 
Kind  Default kind of quantities to allow addition, subtraction, multiplication, division, remainder, negation, and saturating addition/subtraction. 