32 releases (breaking)
0.36.0 | Mar 21, 2024 |
---|---|
0.35.0 | Jul 10, 2023 |
0.34.0 | Feb 10, 2023 |
0.33.0 | Jun 28, 2022 |
0.11.0 | Feb 26, 2017 |
#1 in Science
84,840 downloads per month
Used in 148 crates
(72 directly)
1MB
15K
SLoC
uom
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 the examples directory for more advanced usage:
- si.rs -- Shows how to use the pre-built SI system.
- base.rs -- Shows how to create a set of
Quantity
type aliases for a different set of base units. See the Design section for implications of choosing different base units. - mks.rs -- Shows how to create a custom system of quantities.
- unit.rs -- Shows how to add new units to existing quantities in the pre-build SI system.
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
andf64
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 compilesuom
withno_std
. Enabled by default.serde
-- Feature to enable support for serialization and deserialization of quantities with the Serde crate. Disabled by default. Replaces the deprecateduse_serde
feature, which will be removed in a futureuom
release (v0.37.0 or later).
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
- Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Dependencies
~215–600KB
~14K SLoC