1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
uom
===
[](https://github.com/iliekturtles/uom/actions)
[](https://codecov.io/gh/iliekturtles/uom)
[](https://rustup.rs/)
[](https://crates.io/crates/uom)
[](https://crates.io/crates/uom)
[](https://docs.rs/uom)
Units of measurement is a crate that does automatic type-safe zero-cost
[dimensional analysis][analysis]. You can create your own systems or use the pre-built
[International System of Units][si] (SI) which is based on the
[International System of Quantities][isq] (ISQ) and includes numerous [quantities][quantity]
(length, mass, time, ...) with conversion factors for even more numerous
[measurement units][measurement] (meter, kilometer, foot, mile, ...). No more crashing your
[climate orbiter][orbiter]!
[analysis]: https://en.wikipedia.org/wiki/Dimensional_analysis
[si]: https://jcgm.bipm.org/vim/en/1.16.html
[isq]: https://jcgm.bipm.org/vim/en/1.6.html
[quantity]: https://jcgm.bipm.org/vim/en/1.1.html
[measurement]: https://jcgm.bipm.org/vim/en/1.9.html
[orbiter]: https://en.wikipedia.org/wiki/Mars_Climate_Orbiter
## Usage
`uom` requires `rustc` 1.65.0 or later. Add this to your `Cargo.toml`:
```toml
[dependencies]
uom = "0.37.0"
```
and this to your crate root:
```rust
extern crate uom;
```
The simple example below shows how to use quantities and units as well as how `uom` stops invalid
operations:
```rust
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](examples) directory for more advanced usage:
* [si.rs](examples/si.rs) -- Shows how to use the pre-built SI system.
* [base.rs](examples/base.rs) -- Shows how to create a set of `Quantity` type aliases for a
different set of base units. See the [Design](#design) section for implications of choosing
different base units.
* [mks.rs](examples/mks.rs) -- Shows how to create a custom system of quantities.
* [unit.rs](examples/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] (SI), support for [Serde][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:
```toml
[dependencies]
uom = {
version = "0.37.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](#design) section for
implications of choosing different underlying storage types.
* `si` -- Feature to include the pre-built [International System of Units][si] (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][serde] crate. Disabled by default. Replaces the deprecated `use_serde` feature, which will
be removed in a future `uom` release (v0.37.0 or later).
[si]: https://jcgm.bipm.org/vim/en/1.16.html
[serde]: https://serde.rs/
## Design
Rather than working with [measurement units](https://jcgm.bipm.org/vim/en/1.9.html) (meter,
kilometer, foot, mile, ...) `uom` works with [quantities](https://jcgm.bipm.org/vim/en/1.1.html)
(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](https://jcgm.bipm.org/vim/en/1.10.html) 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][BIPM] is an international
standards organization that publishes the [SI Brochure][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][nist811].
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](LICENSE-APACHE) or
<https://www.apache.org/licenses/LICENSE-2.0>)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
at your option.
[BIPM]: https://www.bipm.org/en/about-us/
[brochure]: https://www.bipm.org/en/publications/si-brochure/
[si]: https://jcgm.bipm.org/vim/en/1.16.html
[nist811]: https://www.nist.gov/pml/special-publication-811/nist-guide-si-appendix-b-conversion-factors/nist-guide-si-appendix-b9
|
