#no-std #units #dimensions #quantities

no-std dimensioned

Compile-time dimensional analysis for various unit systems using Rust’s type system. Dimensioned aims to build on Rust’s safety features by adding unit safety with no runtime cost. In addition, it aims to be as easy to use as possible, hopefully making things easier for you not just by avoiding bugs but also by making it clear what units things are. Never again should you need to specify units in a comment!

26 releases

Uses old Rust 2015

0.7.0 Aug 13, 2018
0.6.0 Mar 3, 2017
0.5.0 Dec 3, 2015
0.4.0 Oct 12, 2015
0.0.1 Nov 21, 2014

#123 in Science

Download history 98/week @ 2021-09-28 68/week @ 2021-10-05 90/week @ 2021-10-12 75/week @ 2021-10-19 88/week @ 2021-10-26 108/week @ 2021-11-02 67/week @ 2021-11-09 156/week @ 2021-11-16 47/week @ 2021-11-23 95/week @ 2021-11-30 85/week @ 2021-12-07 52/week @ 2021-12-14 8/week @ 2021-12-21 23/week @ 2021-12-28 74/week @ 2022-01-04 88/week @ 2022-01-11

195 downloads per month
Used in 17 crates (15 directly)

MIT/Apache

135KB
2.5K SLoC

crates.io Build Status

Documentation

Dimensioned

A Rust library for compile-time dimensional analysis.

Its goal is to provide zero cost unit safety while requiring minimal effort from the programmer.

Use

Dimensioned requires at least Rust version 1.15. It does not depend on std.

If you are using Rust nightly, then you may enable the "oibit" feature of dimensioned. This will make it work a bit better for wrapping non-primitives in units. The recommended way to use dimensioned is by wrapping only primitives in units, in which case this feature is not helpful.

Contributing

Contributions are welcome! There aren't super strict contributing guidelines, but I have a few requests.

  • Note changes that you make in CHANGELOG.md.
  • Add documentation and tests for anything that you add.
  • Try to keep lists alphabetized in files not addressed by rustfmt.
  • Don't hesitate to prod me if I haven't responded to you in a timely manner. I get busy and forgetful, but I would like to repond to issues and PRs promptly.
  • Feel free to ask questions!

Examples

The Simulation Example provides a simple physics simulation and covers how one can use dimensioned with it in a couple different ways, and what the trade-offs are. If you're curious about what might be involved in adding dimensioned to one of your projects, or what it might look like in semi-real code, then that is the place for you.

The Conversion Example covers how one might implement conversions between unit systems.

Finally, just to get the juices flowing, here's a simple example illustrating some of what dimensioned can do:

extern crate dimensioned as dim;

use dim::{si, cgs};

// Calculates speed given a distance and time. Only works for SI units.
fn speed(dist: si::Meter<f64>, time: si::Second<f64>) -> si::MeterPerSecond<f64> {
    dist / time
}

use std::ops::Div;
use dim::dimensions::{Length, Time};
use dim::typenum::Quot;

// Calculates speed as before, but now we can use *any* unit system.
fn generic_speed<L, T>(dist: L, time: T) -> Quot<L, T>
    where L: Length + Div<T>, T: Time,
{
    dist / time
}

fn main() {
    let x = 6.0 * si::M;
    let t = 3.0 * si::S;
    let v = 2.0 * si::M/si::S;
    let v2 = speed(x, t);
    assert_eq!(v, v2);

    let v3 = generic_speed(6.0 * cgs::M, 3.0 * cgs::S);
    let v4 = v.into();
    assert_eq!(v3, v4);
}

This example is also included as examples/readme-example.rs.

Unit Systems

Dimensioned aims to include unit systems for a large variety of uses. It also includes a make_units! macro to allow you to create any unit system you desire.

Error Messages

Probably the biggest weakness of dimensioned are the error messages generated. The type signatures coming from dimensioned tend to just look like a bunch of gobbly-guck. Someday, we may have a better way to display them.

For now, my advice is that when you get an error message involving dimensioned, just go to the line number and hopefully the issue will be apparant from the code alone.

Friends of dimensioned

If there are any libraries that work particularly well with dimensioned, such as the vector3d library used in part 3 of the simulation example, please let me know and they will be listed here.

Dependencies

~0.3–1MB
~23K SLoC

=p[