From a4863823fdd46d64a56402fe1046f1d83f225183 Mon Sep 17 00:00:00 2001 From: tehforsch Date: Sun, 25 Feb 2024 10:16:55 +0100 Subject: [PATCH] update readme --- README.md | 50 +++++++++++++++++++++++++++-------------------- src/lib.rs | 57 ++++++++++++++++++++++++++++++++---------------------- 2 files changed, 63 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 0f055a4..db1ca0c 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,36 @@ If you cannot use unstable Rust for your project or require a stable library, co * Quantities implement the `Equivalence` trait so that they can be sent via MPI using [`mpi`](https://crates.io/crates/mpi) (behind the `mpi` feature gate). * Random quantities can be generated via [`rand`](https://crates.io/crates/rand) (behind the `rand` feature gate, see the official documentation for more info). +# The `Quantity` type +Physical quantities are represented by the `Quantity` struct, where `S` is the underlying storage type (`f32`, `f64`, ...) and `D` is the dimension of the quantity. +`Quantity` should behave like its underlying storage type whenever allowed by the dimensions. +For example: +* Addition and subtraction of two quantities with the same storage type is allowed if the dimensions match. +* Multiplication and division of two quantities with the same storage type produces a new quantity: +```rust +let l: Length = 5.0 * meters; +let t: Time = 2.0 * seconds; +let v: Velocity = l / t; +``` +* Addition of `Quantity` and `Float` is possible if and only if `D` is dimensionless. +* `Quantity` implements the dimensionless methods of `S`, such as `abs` for dimensionless quantities. +* It implements `Deref` to `S` if and only if `D` is dimensionless. +* `Debug` is implemented and will print the quantity in its representation of the "closest" unit. For example `Length::meters(100.0)` would be debug printed as `0.1 km`. If printing in a specific unit is required, conversion methods are available for each unit (such as `Length::in_meters`). +* `.value()` provides access to the underlying storage type of a dimensionless quantity. +* `.value_unchecked()` provides access to the underlying storage type for all quantities if absolutely required. This is not unit-safe since the value will depend on the unit system! +* Similarly, new quantities can be constructed from storage types using `Quantity::new_unchecked`. This is also not unit-safe. + +Some other, more complex operations are also allowed: +```rust +let x = 3.0f64 * meters; +let vol = x.cubed(); +assert_eq!(vol, 27.0 * cubic_meters) +``` +This includes `squared`, `cubed`, `sqrt`, `cbrt` as well as `powi`. + + # Design -Diman aims to make it as easy as possible to add compile-time unit safety to Rust code. Physical quantities are represented by the `Quantity` struct, where `S` is the underlying storage type (`f32`, `f64`, ...) and `D` is the dimension of the quantity. For example, in order to represent the [SI system of units](https://www.nist.gov/pml/owm/metric-si/si-units), the quantity type would be defined using the `unit_system!` macro as follows: + For example, in order to represent the [SI system of units](https://www.nist.gov/pml/owm/metric-si/si-units), the quantity type would be defined using the `unit_system!` macro as follows: ```rust diman::unit_system!( quantity_type Quantity; @@ -116,26 +144,6 @@ Other than this, there are no differences between base dimensions and dimensions The macro also accepts more complex expressions such as `dimension Energy = Mass (Length / Time)^2`. The definitions do not have to be in any specific order. -# The Quantity type -The macro will automatically implement numerical traits such as `Add`, `Sub`, `Mul`, and various other methods of the underlying storage type for `Quantity`. -`Quantity` should behave just like its underlying storage type whenever possible and allowed by the dimensions. -For example: -* Addition of `Quantity` and `Float` is possible if and only if `D` is dimensionless. -* `Quantity` implements the dimensionless methods of `S`, such as `abs` for dimensionless quantities. -* It implements `Deref` to `S` if and only if `D` is dimensionless. -* `Debug` is implemented and will print the quantity in its representation of the "closest" unit. For example `Length::meters(100.0)` would be debug printed as `0.1 km`. If printing in a specific unit is required, conversion methods are available for each unit (such as `Length::in_meters`). -* `.value()` provides access to the underlying storage type of a dimensionless quantity. -* `.value_unchecked()` provides access to the underlying storage type for all quantities if absolutely required. This is not unit-safe since the value will depend on the unit system! -* Similarly, new quantities can be constructed from storage types using `Quantity::new_unchecked`. This is also not unit-safe. - -Some other, more complex operations are also allowed: -```rust -let x = 3.0f64 * meters; -let vol = x.cubed(); -assert_eq!(vol, 27.0 * cubic_meters) -``` -This includes `squared`, `cubed`, `sqrt`, `cbrt` as well as `powi`. - # Prefixes Unit prefixes can automatically be generated with the `#[prefix(...)]` attribute for unit statements. For example diff --git a/src/lib.rs b/src/lib.rs index c3dbe14..83ffc02 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -52,8 +52,41 @@ //! * Quantities implement the `Equivalence` trait so that they can be sent via MPI using [`mpi`](https://crates.io/crates/mpi) (behind the `mpi` feature gate). //! * Random quantities can be generated via [`rand`](https://crates.io/crates/rand) (behind the `rand` feature gate, see the official documentation for more info). //! +//! # The `Quantity` type +//! Physical quantities are represented by the `Quantity` struct, where `S` is the underlying storage type (`f32`, `f64`, ...) and `D` is the dimension of the quantity. +//! `Quantity` should behave like its underlying storage type whenever allowed by the dimensions. +//! For example: +//! * Addition and subtraction of two quantities with the same storage type is allowed if the dimensions match. +//! * Multiplication and division of two quantities with the same storage type produces a new quantity: +//! ``` +//! # #![feature(generic_const_exprs)] +//! # use diman::si::dimensions::{Length, Time, Velocity}; +//! # use diman::si::units::{meters, seconds}; +//! let l: Length = 5.0 * meters; +//! let t: Time = 2.0 * seconds; +//! let v: Velocity = l / t; +//! ``` +//! * Addition of `Quantity` and `Float` is possible if and only if `D` is dimensionless. +//! * `Quantity` implements the dimensionless methods of `S`, such as `abs` for dimensionless quantities. +//! * It implements `Deref` to `S` if and only if `D` is dimensionless. +//! * `Debug` is implemented and will print the quantity in its representation of the "closest" unit. For example `Length::meters(100.0)` would be debug printed as `0.1 km`. If printing in a specific unit is required, conversion methods are available for each unit (such as `Length::in_meters`). +//! * `.value()` provides access to the underlying storage type of a dimensionless quantity. +//! * `.value_unchecked()` provides access to the underlying storage type for all quantities if absolutely required. This is not unit-safe since the value will depend on the unit system! +//! * Similarly, new quantities can be constructed from storage types using `Quantity::new_unchecked`. This is also not unit-safe. +//! +//! Some other, more complex operations are also allowed: +//! ``` +//! # use diman::si::dimensions::{Length, Volume}; +//! # use diman::si::units::{meters,cubic_meters}; +//! let x = 3.0f64 * meters; +//! let vol = x.cubed(); +//! assert_eq!(vol, 27.0 * cubic_meters) +//! ``` +//! This includes `squared`, `cubed`, `sqrt`, `cbrt` as well as `powi`. +//! +//! //! # Design -//! Diman aims to make it as easy as possible to add compile-time unit safety to Rust code. Physical quantities are represented by the `Quantity` struct, where `S` is the underlying storage type (`f32`, `f64`, ...) and `D` is the dimension of the quantity. For example, in order to represent the [SI system of units](https://www.nist.gov/pml/owm/metric-si/si-units), the quantity type would be defined using the `unit_system!` macro as follows: +//! For example, in order to represent the [SI system of units](https://www.nist.gov/pml/owm/metric-si/si-units), the quantity type would be defined using the `unit_system!` macro as follows: //! ``` //! # #![allow(incomplete_features)] //! # #![feature(generic_const_exprs, adt_const_params)] @@ -127,28 +160,6 @@ //! The macro also accepts more complex expressions such as `dimension Energy = Mass (Length / Time)^2`. //! The definitions do not have to be in any specific order. //! -//! # The Quantity type -//! The macro will automatically implement numerical traits such as `Add`, `Sub`, `Mul`, and various other methods of the underlying storage type for `Quantity`. -//! `Quantity` should behave just like its underlying storage type whenever possible and allowed by the dimensions. -//! For example: -//! * Addition of `Quantity` and `Float` is possible if and only if `D` is dimensionless. -//! * `Quantity` implements the dimensionless methods of `S`, such as `abs` for dimensionless quantities. -//! * It implements `Deref` to `S` if and only if `D` is dimensionless. -//! * `Debug` is implemented and will print the quantity in its representation of the "closest" unit. For example `Length::meters(100.0)` would be debug printed as `0.1 km`. If printing in a specific unit is required, conversion methods are available for each unit (such as `Length::in_meters`). -//! * `.value()` provides access to the underlying storage type of a dimensionless quantity. -//! * `.value_unchecked()` provides access to the underlying storage type for all quantities if absolutely required. This is not unit-safe since the value will depend on the unit system! -//! * Similarly, new quantities can be constructed from storage types using `Quantity::new_unchecked`. This is also not unit-safe. -//! -//! Some other, more complex operations are also allowed: -//! ``` -//! # use diman::si::dimensions::{Length, Volume}; -//! # use diman::si::units::{meters,cubic_meters}; -//! let x = 3.0f64 * meters; -//! let vol = x.cubed(); -//! assert_eq!(vol, 27.0 * cubic_meters) -//! ``` -//! This includes `squared`, `cubed`, `sqrt`, `cbrt` as well as `powi`. -//! //! # Prefixes //! Unit prefixes can automatically be generated with the `#[prefix(...)]` attribute for unit statements. //! For example