This Rust library provides compiler-checked types for the standard set of SI units, as specified by the US National Institute of Standards and Technology (this project is not officially endorsed by NIST).
f32 or f64 or other number-like type as your concrete number type.This crate provides types for the following units. Other kinds of quantities not listed below (eg jolt) are beyond the scope of this crate.
(import with use simple_si_units::base::*;)
* Distance, aka Length (meters)
* Mass (kilogram)
* Time (seconds)
* Temperature (kelvin)
* Amount, aka Quantity (moles)
* Current (amperes)
* Luminosity (candela)
| chemical | electromagnetic | geometry | mechanical | nuclear | |---------------------------------|---------------------------------------|------------------|---------------------------------|--------------------------------| | Catalytic Activity (mol/s) | Capacitance (C/V, aka F) | Angle (rad) | Acceleration (m/s^2) | Absorbed Dose (J/kg, aka Gy) | | Concentration (mol/m^3, aka mM) | Charge, aka Coulomb (A.s, aka C) | Area (m^2) | Angular Acceleration (rad/s^2) | Dose Equivalent (J/kg, aka Sv) | | | Conductance (1/ohm, aka S) | Solid Angle (sr) | Angular Momentum (kg.m^2.rad/s) | Radioactivity (1/s, aka Bq) | | | Illuminance (lm/m^2, aka lux) | Volume (m^3) | Angular Velocity (rad/s) | | | Inductance (Wb/A, aka H) | | Area Density (kg.m^2) | | | Luminous Flux (cd.sr, aka lm) | | Density (kg/L) | | | Magnetic Flux (V.s, aka Wb) | | Energy (kg.m^2/s^2, aka J) | | | Magnetic Flux Density (Wb/m^2, aka T) | | Force (kg.m/s^2, aka N) | | | Resistance (V/A, aka Ohm) | | Frequency (1/s, aka Hz) | | | Voltage (W/A, aka V) | | Moment of Inertia (kg.m^2) | | | | | Momentum (kg.m/s) | | | | | Power, aka Watt (J/s, aka W) | | | | | Pressure (N/m^2, aka Pa) | | | | | Torque (kg.m^2/s^2, aka N.m) | | | | | Velocity (m/s) |
The simple-si-units crate has the following optional features which can be
enabled to provide additional compatibility:
* serde - Adds serde serialization/deserialization compatibility
* uom - If enabled, then unit structs will implement the Into and From traits
to convert between simple-si-units and uom types
* num-bigfloat - Adds std::ops::Mul and std::ops::Div implementations
for multiplying and dividing unit structs by num-bigfloat scalar values
* num-complex - Adds std::ops::Mul and std::ops::Div implementations
for multiplying and dividing unit structs by num-complex scalar values
To use simple-si-units, just add simple-si-units = "1.0" to the [dependencies]
section of your Cargo.toml file, then import the units you need like this:
```rust
use simplesiunits::base::;
use simple_si_units::geometry::;
use simplesiunits::mechanical::*;
fn main() {
let boxwidth = Distance::fromcm(33.5);
let boxlength = Distance::fromcm(45.0);
let boxheight = Distance::fromcm(23.5);
let carboarddensity = AreaDensity::fromgramspersquaremeter(300.);
let boxvolume = &boxwidth * &boxheight * &boxlength;
println!("Your box holds a total volume of {:.2} liters", boxvolume.toL());
let boxweight = (2. * &boxwidth * &boxlength
+ 2. * &boxwidth * &boxheight
+ 2. * &boxlength * &boxheight) * &carboarddensity;
println!("Your box has a weight of {}", boxweight);
}
``
Note that **simple-si-units** structs all implementstd::ops::{Add,Sub,Mul,Div}
for both values and references, which is useful for number type which do not
implement theCopy` trait.
simple-si-units was designed specifically to help people create safer APIs for libraries and functions that perform scientific calculations.
For most applications, you can simply specify both the SI unit type and data type for each variable, like this: ```rust use simplesiunits::base::Distance; use simplesiunits::geometry::Volume; use std::f64::consts::PI;
pub fn sphere_volume(radius: Distance
However, if you want to support more than one data type, then you should use
a generic templated function. The simple-si-units crate provides the
NumLike type to help simplify generic APIs, for example:
```rust
use simplesiunits::base::Distance; use simplesiunits::geometry::Volume; use std::f64::consts::PI; use simplesiunits::NumLike;
pub fn sphere_volume
The above generic function will work for any number type which implements
From, such asComplex64orBigFloat` (from the
num-complex and
num-bigfloat crates respectively).
You don't have to choose, you can use both! All simple-si-units types implement the
Into and From traits to convert to and from their
uom equivalent.
The uom and simple-si-units crates were
both designed to provide compile-time type checking for scientific units of
measure to help developers catch math errors and write cleaner calculation
APIs. The difference is that uom also performs
dimensional analysis but cannot handle custom data types, while
simple-si-units handles any number-like data type but does not attempt to
implement full compile-time dimensional analysis. simple-si-units also
prioritizes developer ergonomics, adhering to a consistent Struct::from_...()
and Struct.to_...() syntax for simple and intuitive number conversions.
Whether uom or simple-si-units better
suits your application depends on your needs.
Here's a table comparing simple-si-units v1.0 and uom v0.34 to help you decide which to use:
| Feature | simple-si-units | uom | |-------------------------------------------------------------------|-------------------------------------------------------------|------------------------------------| | Zero-cost measurement unit type safety | ✅ | ✅ | | All primary and secondary SI units as defined by NIST | ✅ | ✅ | | Angular units (angular velocity, momentum, and intertia) | ✅ | ❌ | | Support for standard decimal types (eg f64) | ✅ | ✅ | | Support for standard integer types (eg i32) | partial* | partial* | | Support for num-bigfloat | ✅ | ❌ | | Support for num-complex | ✅ | ✅ | | Support for num-rational | partial** | ✅ | | Support for user-defined and other number types | ✅ | ❌ | | Compile-time dimensional analysis | ❌ | ✅ |
* *integer types and int-based number types are not fully supported in simple-si-units
To further demonstrate the similarities and differences between simple-si-units and uom, here's two different versions of the same gravity calculation function, one using simple-si-units and the other using uom: ```rust // simple-si-units version mod simplesiversion { use simplesiunits::base::{Distance, Mass}; use simplesiunits::mechanical::{Acceleration};
pub fn calcgravity(mass: Mass
fn testgravity1() { let radius = Distance::fromkm(6378.1); let mass = Mass::fromearthmass(1.0); println!("simple-si-units: Earth gravity at sea-level is {}", calc_gravity(mass, radius)); } }
// uom version mod uom_version { use uom::si::f64::{Length, Mass, Acceleration}; use uom::si::length::; use uom::si::mass::; use uom::si::acceleration::*; use uom::fmt::DisplayStyle::Abbreviation;
pub fn calcgravity(mass: Mass, dist: Length) -> Acceleration {
const G: f64 = 6.67408e-11; // m3 kg-1 s-2
let dsquared = dist * dist;
return Acceleration::new::
fn testgravity2() {
let radius = Length::new::
The version of this library will be incremented to reflect progress through the various milestones. The goal is to reach version 1.0 (API stable) as quickly as practical.
Into and From conversion to/from uom typesFor each type of unit (eg Distance), Simple SI Units provides a generic struct
to represent the unit and which implements common type conversion. For example,
dividing a Distance by a Time results in a Velocity:
```rust
use simplesiunits::base::{Distance, Mass};
use simplesiunits::mechanical::{Acceleration};
pub fn calcgravity(mass: Mass
fn main(){ let a = calcgravity(Mass::fromsolarmass(1.0), Distance::fromau(1.0)); println!("Solar gravity at Earth orbital distance: {}", a); } ```
Since these structs use generic type templates for the internal data type, you
can use any number-like data type with these structs, including
numcomplex::Complex and
numbigfloat::BigFloat (see limitations
section below regarding types that do not implement From<f64>).
For example, the above function could be rewritten as follows to allow almost any number-like data type: ```rust use simplesiunits::base::{Distance, Mass}; use simplesiunits::mechanical::{Acceleration}; use simplesiunits::NumLike;
pub fn calcgravitygeneric
Simple SI Units does not provide an exhaustive list of possible units of
measure. To create your own units, use the UnitStruct procedural macro and
NumLike trait bundle (NumLike is just shorthand for
std::ops::*<Output=Self>+Clone+Debug+Display, you could instead use the Num
trait from the num-traits crate if you
prefer):
```rust use simplesiunits::{UnitStruct, NumLike};
struct HyperVelocity
fn weightedhypervelsum
Note that theUnitStruct` derive macro only works on structs that contain only a
single member variable. Otherwise it will generate a compiler error.
Due to the Rust compiler's lack of
type specialization in stable
Rust, some of the unit constructor functions (eg Mass::from_g(...)) only work
with number types that implement From<f64>. This means that those functions
will not work for Rust's built-in f32 or integer types. You can still
construct unit structs with their SI reference measurement using any number
type (eg Mass::from_kg(1f32) will work).
simple-si-units works with any "number-like" data type, including libraries such as num-bigfloat, num-complex, and even number types you define yourself. A data type is "number-like" if it implements the following traits: Clone, Debug, Display, Add, AddAssign, Sub, SubAssign, Mul, MulAssign, Div, DivAssign, Neg
For example, here's a snippet of code that defines and uses a number type that is
like f32 but also implements From<f64>:
```rust
use std::ops::*;
use std::fmt::{Display, Formatter, Result};
use simplesiunits::base::Mass;
use simplesiunits::geometry::Volume;
use simplesiunits::mechanical::Density;
struct MyNumber(f32);
impl Display for MyNumber {
fn fmt(&self, f: &mut Formatter<'>) -> Result {std::fmt::Display::fmt(&self.0, f)}
}
impl Add for MyNumber {
type Output = MyNumber;
fn add(self, rhs: Self) -> Self::Output {MyNumber(self.0 + rhs.0)}
}
impl AddAssign for MyNumber {
fn addassign(&mut self, rhs: Self) {self.0 += rhs.0;}
}
impl Sub for MyNumber {
type Output = MyNumber;
fn sub(self, rhs: Self) -> Self::Output {MyNumber(self.0 - rhs.0)}
}
impl SubAssign for MyNumber {
fn subassign(&mut self, rhs: Self) {self.0 -= rhs.0;}
}
impl Mul for MyNumber {
type Output = MyNumber;
fn mul(self, rhs: Self) -> Self::Output {MyNumber(self.0 * rhs.0)}
}
impl MulAssign for MyNumber {
fn mulassign(&mut self, rhs: Self) {self.0 *= rhs.0;}
}
impl Div for MyNumber {
type Output = MyNumber;
fn div(self, rhs: Self) -> Self::Output {MyNumber(self.0 / rhs.0)}
}
impl DivAssign for MyNumber {
fn div_assign(&mut self, rhs: Self) {self.0 /= rhs.0;}
}
impl Neg for MyNumber {
type Output = MyNumber;
fn neg(self) -> Self::Output {MyNumber(-self.0)}
}
impl From
fn myfn() -> Density
It's highly recommended that you also implement thestd::ops::*operators for
all combinations of values and reference types (egX + X,X + &X,&X + X, and&X + &X`),
as this will make your number type much easier to use and integrate with simple-si-units.
This library is open source, licensed under the Mozilla Public License version 2.0. In summary, you may include this source code as-is in both open-source and proprietary projects without requesting permission from me, but if you modify the source code from this library then you must make your modified version of this library available under an open-source license.
Note that the unit struct source files (excluding lib.rs), were all generated
by a Python program which performs dimensional analysis and other code generation
activities, found in the code-generator
folder of the GitHub repository.
If you wish to contribute, please start by adding the unit tests for your new feature and then modify the Python project to generate the Rust implementation of the new feature. Thanks!