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.20.0 or later. Add this to your Cargo.toml
:
[dependencies]
uom = "0.16.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 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), 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.16.0",
default-features = false,
features = [
"usize", "u8", "u16", "u32", "u64", # Unsigned integer storage types.
"isize", "i8", "i16", "i32", "i64", # Signed interger 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", # Built-in SI system and std library support.
]
}
usize
,u8
,u16
,u32
,u64
,isize
,i8
,i16
,i32
,i64
,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.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 compilesuom
withno_std
. Enabled 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 cost1 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
, isize
,
i8
, i16
, i32
, i64
, bigint
, biguint
, rational
, rational32
, rational64
,
bigrational
, 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 |
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
|
storage_types |
Macro to duplicate code a per-storage 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. |
Traits
Conversion |
Trait to identify units which have a conversion factor. |
ConversionFactor |
Trait representing a conversion factor. |