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.23.0 (and is tested on this version), although some features may require a newer version.

It does not depend on std; simple include without the default feature std. Doing so requires a nightly version of rustc.

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 si_x = 6.0 * si::M;
    let si_t = 3.0 * si::S;
    let si_v = 2.0 * si::M / si::S;

    let si_v2 = speed(si_x, si_t);
    assert_eq!(si_v, si_v2);

    let cgs_x = 6.0 * cgs::M;
    let cgs_t = 3.0 * cgs::S;
    let cgs_v = 2.0 * cgs::M / cgs::S;

    let cgs_v2 = generic_speed(cgs_x, cgs_t);
    assert_eq!(cgs_v, cgs_v2);

    let si_v3 = cgs_v2.into();
    assert_eq!(si_v2, si_v3);
}

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.

paholg / dimensioned

readme