measures/
lib.rs

1//! Set of declarative macros to define types to handle quantities provided of units of measurement, and optional uncertainty.
2//! The only macro to be used in application code is `define_measure_types`, which must be called at most once per module.
3//! It is recommended to be called only once per application.
4//! It is suggested to called it in a module named `units`.
5//!
6//! Here is an extensive [**tutorial**](https://github.com/carlomilanesi/measures-rs/blob/main/docs/Tutorial.md) for the last version of the library.
7//!
8//! # Example of usage
9//!
10//! ```
11//! mod units {
12//!     measures::define_measure_types! {
13//!         exact with_approx,
14//!         scalar_properties [
15//!             Time [
16//!                 Second {
17//!                     suffix: " s",
18//!                 }
19//!                 Hour {
20//!                     suffix: " h",
21//!                     ratio: 3600.,
22//!                 }
23//!             ]
24//!         ]
25//!         vector_properties [
26//!             Length [
27//!                 Metre {
28//!                     suffix: " m",
29//!                 }
30//!                 Foot {
31//!                     suffix: " ft",
32//!                     ratio: 0.3048,
33//!                 }
34//!             ]
35//!             Velocity [
36//!                 MetrePerSecond {
37//!                     suffix: " m/s",
38//!                 }
39//!             ]
40//!         ]
41//!         relationships [
42//!             Metre 1 == MetrePerSecond 1 * Second 1,
43//!         ]
44//!     }
45//! }
46//!
47//! let l = units::Measure::<units::Metre, f32>::new(10000.);
48//! assert_eq!(
49//!     format!("{} = {}", l, l.convert::<units::Foot>()),
50//!     "10000 m = 32808.4 ft",
51//! );
52//!
53//! let t = units::ApproxMeasure::<units::Second>::with_variance(5400., 0.81);
54//! assert_eq!(
55//!     format!("{} = {}", t, t.convert::<units::Hour>()),
56//!     "5400 ± 0.9 s = 1.5 ± 0.00025 h",
57//! );
58//! let v = l.lossless_into::<f64>() / units::Measure::from(t);
59//! assert_eq!(
60//!     format!("{v}"),
61//!     "1.8518518518518519 m/s",
62//! );
63//! ```
64//!
65//! Syntax of the macro `define_measure_types!`, in a kind of regular expression, where `[]` means "optional", `\[` and `\]` mean actual brackets, `()*` means "repeat zero or more times", `|` means "or", and items included in the angle brackets `<` and `>` are identifiers, literals or expressions:
66//!
67//! ```custom
68//! measures::define_measure_types! {
69//!     [with_points]
70//!     [with_directions]
71//!     [with_2d]
72//!     [with_3d]
73//!     [with_transformations]
74//!     [exact]
75//!     [with_approx],
76//!     [
77//!     scalar_properties \[
78//!         (
79//!         <Name of a property> \[
80//!             (
81//!             <Name of a unit of measurement> {
82//!                 suffix: <string literal>,
83//!                 [
84//!                 ratio: <f64 const expression>,
85//!                 [offset: <f64 const expression>,]
86//!                 ]
87//!             }
88//!             )*
89//!             \]
90//!         )*
91//!         \]
92//!     ]
93//!     [
94//!     vector_properties \[
95//!         (
96//!         <Name of a property> \[
97//!             (
98//!             <Name of a unit of measurement> {
99//!                 suffix: <string literal>,
100//!                 [
101//!                 ratio: <f64 const expression>,
102//!                 ]
103//!             }
104//!             )*
105//!             \]
106//!         )*
107//!         \]
108//!     ]
109//!     [
110//!     vector_properties \[
111//!         (
112//!         <Name of a property> \[
113//!             (
114//!             <Name of a unit of measurement> {
115//!                 suffix: <string literal>,
116//!                 [
117//!                 ratio: <f64 const expression>,
118//!                 ]
119//!             }
120//!             )*
121//!             \]
122//!         )*
123//!         \]
124//!     ]
125//!     [
126//!     angle_measurement_units \[
127//!         (
128//!         <Name of a unit of measurement> {
129//!             suffix: <string literal>,
130//!             cycle_fraction: <f64 const expression>,
131//!         }
132//!         )*
133//!     \]
134//!     ]
135//!     [
136//!     relationships \[
137//!         (
138//!         <unit> 1 == <unit> 1 * __ 1,
139//!         | <unit> 1 == <unit> 1 * <unit> 1,
140//!         | <unit> 2 == <unit> 1 * <unit> 2,
141//!         | <unit> 2 == <unit> 2 * <unit> 1,
142//!         | <unit> 3 == <unit> 1 * <unit> 3,
143//!         | <unit> 3 == <unit> 3 * <unit> 1,
144//!         | <unit> 1 == <unit> 2 * __ 2,
145//!         | <unit> 1 == <unit> 2 * <unit> 2,
146//!         | <unit> 1 == <unit> 3 * __ 3,
147//!         | <unit> 1 == <unit> 3 * <unit> 3,
148//!         | <unit> 1 == <unit> 2 X __ 2,
149//!         | <unit> 1 == <unit> 2 X <unit> 2,
150//!         | <unit> 3 == <unit> 3 X __ 3,
151//!         | <unit> 3 == <unit> 3 X <unit> 3,
152//!         )*
153//!     \]
154//!     ]
155//! }
156//! ```
157pub mod angle;
158pub mod define_measure_types;
159pub mod define_units_relationship;
160pub mod dimensionless;
161pub mod inner;
162pub mod matrix_utils;
163pub mod test_utils;
164pub mod traits;
measures/lib.rs

measures/
lib.rs
