Quantity API cleanup

src/quantity/mod.rs

@@ -1,6 +1,17 @@
+use core::f64;
 use std::marker::PhantomData;
 
-use uom::si;
+use serde::ser::SerializeStruct;
+use serde::Serializer;
+use uom::{si, Conversion};
+
+pub use uom::si::information::{byte, kibibyte};
+pub use uom::si::ratio::ratio;
+pub use uom::si::time::{hour, microsecond, millisecond, minute, nanosecond, second};
+
+pub use si::f64::Ratio;
+pub use si::f64::Time;
+pub use si::u64::Information;
 
 pub use si::f64::{Information, Ratio, Time};
 pub use si::information::{byte, gibibyte, kibibyte, mebibyte, tebibyte};
@@ -10,52 +21,67 @@ pub use uom::num_traits::Zero;
 
 pub use units::{InformationUnit, IsUnit, TimeUnit};
 
-pub mod statistics;
 mod units;
 
-pub trait FormatQuantity {
-    type Unit;
-
-    fn suitable_unit(&self) -> Self::Unit;
-
-    fn format_with_precision(&self, unit: Self::Unit, precision: usize) -> String;
-    fn format(&self, unit: Self::Unit) -> String;
-    fn format_auto(&self) -> String;
-    fn format_value(&self, unit: Self::Unit) -> String;
-}
-
-impl FormatQuantity for Time {
-    type Unit = TimeUnit;
-
-    fn suitable_unit(&self) -> TimeUnit {
-        if *self < Time::new::<millisecond>(1.0) {
-            TimeUnit::MicroSecond
-        } else if *self < Time::new::<second>(1.0) {
-            TimeUnit::MilliSecond
-        } else {
-            TimeUnit::Second
-        }
+pub trait TimeQuantity {
+    fn zero() -> Time {
+        Time::new::<second>(0.0)
     }
 
-    /// Format the time duration in the given unit with the given precision.
-    fn format_with_precision(&self, u: TimeUnit, precision: usize) -> String {
+    fn value_in<U>(&self, u: U) -> f64
+    where
+        U: si::time::Unit + Conversion<f64, T = f64>;
+
+    fn format_value_in(&self, time_unit: TimeUnit, precision: usize) -> String;
+    fn format_auto(&self, time_unit: Option<TimeUnit>) -> String;
+    fn format_auto_with_unit(&self, time_unit: Option<TimeUnit>) -> (String, TimeUnit);
+    fn format_value_auto(&self, time_unit: Option<TimeUnit>) -> (String, TimeUnit);
+}
+
+impl TimeQuantity for Time {
+    fn value_in<U>(&self, _u: U) -> f64
+    where
+        U: si::time::Unit + Conversion<f64, T = f64>,
+    {
+        self.get::<U>()
+    }
+
+    fn format_value_in(&self, u: TimeUnit, precision: usize) -> String {
         u.format(*self, precision)
     }
 
-    /// Format the time duration in the given unit.
-    fn format(&self, unit: TimeUnit) -> String {
-        let value = self.format_with_precision(unit, unit.preferred_precision());
-        format!("{} {}", value, unit.short_name())
+    /// Format the given duration as a string. The output-unit can be enforced by setting `unit` to
+    /// `Some(target_unit)`. If `unit` is `None`, it will be determined automatically.
+    fn format_auto(&self, time_unit: Option<TimeUnit>) -> String {
+        self.format_auto_with_unit(time_unit).0
     }
 
-    /// Format the given time duration. The unit will be determined automatically.
-    fn format_auto(&self) -> String {
-        self.format(self.suitable_unit())
+    /// Like `format_duration`, but returns the target unit as well.
+    fn format_auto_with_unit(&self, time_unit: Option<TimeUnit>) -> (String, TimeUnit) {
+        let (out_str, out_unit) = self.format_value_auto(time_unit);
+
+        (format!("{} {}", out_str, out_unit.short_name()), out_unit)
     }
 
-    /// Like `format`, but without displaying the unit.
-    fn format_value(&self, unit: TimeUnit) -> String {
-        self.format_with_precision(unit, unit.preferred_precision())
+    /// Like `format_duration`, but returns the target unit as well.
+    fn format_value_auto(&self, time_unit: Option<TimeUnit>) -> (String, TimeUnit) {
+        let (time_unit, precision) = if (*self < Time::new::<millisecond>(1.0)
+            && time_unit.is_none())
+            || time_unit == Some(TimeUnit::MicroSecond)
+        {
+            (TimeUnit::MicroSecond, 1)
+        } else if (*self < Time::new::<second>(1.0) && time_unit.is_none())
+            || time_unit == Some(TimeUnit::MilliSecond)
+        {
+            (TimeUnit::MilliSecond, 1)
+        } else {
+            let time_unit = time_unit.unwrap_or(TimeUnit::Second);
+            let precision = if time_unit == TimeUnit::Second { 3 } else { 1 };
+
+            (time_unit, precision)
+        };
+
+        (self.format_value_in(time_unit, precision), time_unit)
     }
 }
 
@@ -68,91 +94,126 @@ pub const fn const_time_from_seconds(value: f64) -> Time {
     }
 }
 
-impl FormatQuantity for Information {
-    type Unit = InformationUnit;
-
-    fn suitable_unit(&self) -> InformationUnit {
-        if *self < Information::new::<kibibyte>(1.0) {
-            InformationUnit::Byte
-        } else if *self < Information::new::<mebibyte>(1.0) {
-            InformationUnit::KibiByte
-        } else if *self < Information::new::<gibibyte>(1.0) {
-            InformationUnit::MebiByte
-        } else {
-            InformationUnit::GibiByte
-        }
+pub trait InformationQuantity {
+    fn zero() -> Information {
+        Information::new::<byte>(0)
     }
 
-    /// Format the information in the given unit with the given precision.
-    fn format_with_precision(&self, u: InformationUnit, precision: usize) -> String {
-        u.format(*self, precision)
+    fn value_in<U>(&self, u: U) -> u64
+    where
+        U: si::information::Unit + Conversion<u64, T = uom::num_rational::Ratio<u64>>;
+
+    fn to_string<U>(&self, u: U) -> String
+    where
+        U: si::information::Unit + Conversion<u64, T = uom::num_rational::Ratio<u64>>;
+}
+
+impl InformationQuantity for Information {
+    fn value_in<U>(&self, _u: U) -> u64
+    where
+        U: si::information::Unit + Conversion<u64, T = uom::num_rational::Ratio<u64>>,
+    {
+        self.get::<U>()
     }
 
-    /// Format the information in the given unit.
-    fn format(&self, unit: InformationUnit) -> String {
-        let value = self.format_with_precision(unit, unit.preferred_precision());
-        format!("{} {}", value, unit.short_name())
-    }
-
-    /// Format the given information. The unit will be determined automatically.
-    fn format_auto(&self) -> String {
-        self.format(self.suitable_unit())
-    }
-
-    /// Like `format`, but without displaying the unit.
-    fn format_value(&self, unit: InformationUnit) -> String {
-        self.format_with_precision(unit, unit.preferred_precision())
+    fn to_string<U>(&self, u: U) -> String
+    where
+        U: si::information::Unit + Conversion<u64, T = uom::num_rational::Ratio<u64>>,
+    {
+        format!(
+            "{}",
+            self.into_format_args(u, uom::fmt::DisplayStyle::Abbreviation)
+        )
     }
 }
 
+pub fn serialize_time<S>(t: &Time, s: S) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+{
+    let mut state = s.serialize_struct("Time", 3)?;
+    state.serialize_field("value", &t.value)?;
+    state.serialize_field("unit", "second")?;
+    state.end()
+}
+
+pub fn serialize_information<S>(i: &Information, s: S) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+{
+    let mut state = s.serialize_struct("Information", 3)?;
+    state.serialize_field("value", &i.value)?;
+    state.serialize_field("unit", "byte")?;
+    state.end()
+}
+
+macro_rules! quantity_fn {
+    ($name:ident, $unwrapped_values:ident, $body:expr) => {
+        pub fn $name(values: &[Time]) -> Time {
+            let $unwrapped_values: Vec<_> = values.iter().map(|q| q.value_in(second)).collect();
+            let result_value = $body;
+
+            Time::new::<second>(result_value)
+        }
+    };
+}
+
+quantity_fn!(mean, values, statistical::mean(&values));
+quantity_fn!(median, values, statistical::median(&values));
+quantity_fn!(min, values, crate::util::min_max::min(&values));
+quantity_fn!(max, values, crate::util::min_max::max(&values));
+quantity_fn!(standard_deviation, values, {
+    let mean_value = statistical::mean(&values);
+    statistical::standard_deviation(&values, Some(mean_value))
+});
+
 #[test]
 fn test_time() {
     let time = Time::new::<millisecond>(123.4);
-    assert_eq!(time.get::<millisecond>(), 123.4);
+    assert_eq!(time.value_in(millisecond), 123.4);
 
-    let time_s = time.get::<second>();
+    let time_s = time.value_in(second);
     approx::assert_relative_eq!(time_s, 0.1234);
 
-    let time_us = time.get::<microsecond>();
+    let time_us = time.value_in(microsecond);
     approx::assert_relative_eq!(time_us, 123400.0);
 }
 
 #[test]
 fn test_information() {
-    use uom::si::information::pebibyte;
+    let information = Information::new::<kibibyte>(8);
+    assert_eq!(information.value_in(byte), 8192);
 
-    let information = Information::new::<kibibyte>(8.);
-    assert_eq!(information.get::<byte>(), 8192.);
-
-    let information_kib = information.get::<kibibyte>();
-    assert_eq!(information_kib, 8.);
-
-    let largest_exactly_representable = Information::new::<byte>(9_007_199_254_740_992.);
-    assert_eq!(largest_exactly_representable.get::<pebibyte>(), 8.);
+    let information_kib = information.value_in(kibibyte);
+    assert_eq!(information_kib, 8);
 }
 
 #[test]
-fn test_suiteable_unit_time() {
-    assert_eq!(Time::new::<second>(1.3).suitable_unit(), TimeUnit::Second);
-    assert_eq!(Time::new::<second>(1.0).suitable_unit(), TimeUnit::Second);
-    assert_eq!(
-        Time::new::<second>(0.999).suitable_unit(),
-        TimeUnit::MilliSecond
-    );
-    assert_eq!(
-        Time::new::<second>(0.0005).suitable_unit(),
-        TimeUnit::MicroSecond
-    );
-    assert_eq!(
-        Time::new::<second>(0.).suitable_unit(),
-        TimeUnit::MicroSecond
-    );
-    assert_eq!(
-        Time::new::<second>(1000.0).suitable_unit(),
-        TimeUnit::Second
-    );
+fn test_format() {
+    let time = Time::new::<millisecond>(123.4);
+    assert_eq!(time.format_auto(Some(TimeUnit::Second)), "0.123 s");
+    assert_eq!(time.format_auto(Some(TimeUnit::MilliSecond)), "123.4 ms");
+    assert_eq!(time.format_auto(Some(TimeUnit::MicroSecond)), "123400.0 µs");
+
+    let peak_memory_usage = Information::new::<kibibyte>(8);
+    assert_eq!(peak_memory_usage.to_string(byte), "8192 B");
+    assert_eq!(peak_memory_usage.to_string(kibibyte), "8 KiB");
 }
 
+#[test]
+fn test_mean() {
+    let values = vec![
+        Time::new::<millisecond>(123.4),
+        Time::new::<millisecond>(234.5),
+    ];
+    let result = mean(&values);
+    assert_eq!(result.format_auto(Some(TimeUnit::MilliSecond)), "178.9 ms");
+}
+
+#[test]
+fn test_format_duration() {
+    let (out_str, out_unit) = Time::new::<second>(1.3).format_auto_with_unit(None);
+
 #[test]
 fn test_suitable_unit_information() {
     assert_eq!(
@@ -173,31 +234,49 @@ fn test_suitable_unit_information() {
     );
 }
 
-#[test]
-fn test_format() {
-    let time = Time::new::<millisecond>(123.4);
-    assert_eq!(time.format(TimeUnit::Second), "0.123 s");
-    assert_eq!(time.format(TimeUnit::MilliSecond), "123.4 ms");
-    assert_eq!(time.format_auto(), "123.4 ms");
-    assert_eq!(time.format(TimeUnit::MicroSecond), "123400.0 µs");
+    let (out_str, out_unit) = Time::new::<second>(1.0).format_auto_with_unit(None);
 
-    let peak_memory_usage = Information::new::<kibibyte>(8.);
-    assert_eq!(peak_memory_usage.format_auto(), "8.0 KiB");
-    assert_eq!(peak_memory_usage.format(InformationUnit::Byte), "8192 B");
-    assert_eq!(
-        peak_memory_usage.format(InformationUnit::KibiByte),
-        "8.0 KiB"
-    );
+    assert_eq!("1.000 s", out_str);
+    assert_eq!(TimeUnit::Second, out_unit);
+
+    let (out_str, out_unit) = Time::new::<second>(0.999).format_auto_with_unit(None);
+
+    assert_eq!("999.0 ms", out_str);
+    assert_eq!(TimeUnit::MilliSecond, out_unit);
+
+    let (out_str, out_unit) = Time::new::<second>(0.0005).format_auto_with_unit(None);
+
+    assert_eq!("500.0 µs", out_str);
+    assert_eq!(TimeUnit::MicroSecond, out_unit);
+
+    let (out_str, out_unit) = Time::new::<second>(0.).format_auto_with_unit(None);
+
+    assert_eq!("0.0 µs", out_str);
+    assert_eq!(TimeUnit::MicroSecond, out_unit);
+
+    let (out_str, out_unit) = Time::new::<second>(1000.0).format_auto_with_unit(None);
+
+    assert_eq!("1000.000 s", out_str);
+    assert_eq!(TimeUnit::Second, out_unit);
 }
 
 #[test]
 fn test_format_duration_unit_with_unit() {
-    let out = Time::new::<second>(1.3).format(TimeUnit::Second);
-    assert_eq!("1.300 s", out);
+    let (out_str, out_unit) =
+        Time::new::<second>(1.3).format_auto_with_unit(Some(TimeUnit::Second));
 
     let out = Time::new::<second>(1.3).format(TimeUnit::MilliSecond);
     assert_eq!("1300.0 ms", out);
 
-    let out = Time::new::<second>(1.3).format(TimeUnit::MicroSecond);
-    assert_eq!("1300000.0 µs", out);
+    let (out_str, out_unit) =
+        Time::new::<second>(1.3).format_auto_with_unit(Some(TimeUnit::MilliSecond));
+
+    assert_eq!("1300.0 ms", out_str);
+    assert_eq!(TimeUnit::MilliSecond, out_unit);
+
+    let (out_str, out_unit) =
+        Time::new::<second>(1.3).format_auto_with_unit(Some(TimeUnit::MicroSecond));
+
+    assert_eq!("1300000.0 µs", out_str);
+    assert_eq!(TimeUnit::MicroSecond, out_unit);
 }

src/quantity/units.rs

@@ -23,6 +23,10 @@ pub trait IsUnit {
     }
 }
 
+use std::marker::PhantomData;
+
+use crate::quantity::{hour, microsecond, millisecond, minute, second, Time};
+
 /// Supported time units
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TimeUnit {
@@ -33,24 +37,50 @@ pub enum TimeUnit {
     Hour,
 }
 
-impl IsUnit for TimeUnit {
-    type Quantity = Time;
+struct Dispatcher<U: uom::si::time::Unit + uom::Conversion<f64, T = f64>> {
+    u: PhantomData<U>,
+}
 
-    fn dispatch(&self) -> Box<dyn UnitImpl<Quantity = Time>> {
+impl<U: uom::si::time::Unit + uom::Conversion<f64, T = f64>> Dispatcher<U> {
+    fn new() -> Self {
+        Dispatcher { u: PhantomData }
+    }
+}
+
+trait UnitImpl {
+    fn short_name(&self) -> &'static str;
+    fn format_value(&self, value: Time, precision: usize) -> String;
+}
+
+impl<U: uom::si::time::Unit + uom::Conversion<f64, T = f64>> UnitImpl for Dispatcher<U> {
+    fn short_name(&self) -> &'static str {
+        U::abbreviation()
+    }
+
+    fn format_value(&self, value: Time, precision: usize) -> String {
+        format!("{value:.precision$}", value = value.get::<U>())
+    }
+}
+
+impl TimeUnit {
+    fn dispatch(self) -> Box<dyn UnitImpl> {
         match self {
-            TimeUnit::MicroSecond => Box::new(TimeUnitDispatcher::<microsecond>::new()),
-            TimeUnit::MilliSecond => Box::new(TimeUnitDispatcher::<millisecond>::new()),
-            TimeUnit::Second => Box::new(TimeUnitDispatcher::<second>::new()),
-            TimeUnit::Minute => Box::new(TimeUnitDispatcher::<minute>::new()),
-            TimeUnit::Hour => Box::new(TimeUnitDispatcher::<hour>::new()),
+            TimeUnit::MicroSecond => Box::new(Dispatcher::<microsecond>::new()),
+            TimeUnit::MilliSecond => Box::new(Dispatcher::<millisecond>::new()),
+            TimeUnit::Second => Box::new(Dispatcher::<second>::new()),
+            TimeUnit::Minute => Box::new(Dispatcher::<minute>::new()),
+            TimeUnit::Hour => Box::new(Dispatcher::<hour>::new()),
         }
     }
 
-    fn preferred_precision(&self) -> usize {
-        match self {
-            TimeUnit::Second => 3,
-            _ => 1,
-        }
+    /// A short abbreviation like `s`, `ms`, or `µs`.
+    pub fn short_name(self) -> &'static str {
+        self.dispatch().short_name()
+    }
+
+    /// Formats the quantity as a string in the given Unit.
+    pub fn format(self, value: Time, precision: usize) -> String {
+        self.dispatch().format_value(value, precision)
     }
 }
 
@@ -147,20 +177,3 @@ fn test_time_unit_short_name() {
     assert_eq!("min", TimeUnit::Minute.short_name());
     assert_eq!("h", TimeUnit::Hour.short_name());
 }
-
-// Note - the values are rounded when formatted.
-#[test]
-fn test_unit_format() {
-    use crate::quantity::FormatQuantity;
-
-    let value = Time::new::<second>(123.456789);
-    assert_eq!("123.457", value.format_value(TimeUnit::Second));
-    assert_eq!("123456.8", value.format_value(TimeUnit::MilliSecond));
-
-    assert_eq!(
-        "1234.6",
-        Time::new::<second>(0.00123456).format_value(TimeUnit::MicroSecond)
-    );
-    assert_eq!("2.1", value.format_value(TimeUnit::Minute));
-    assert_eq!("0.0", value.format_value(TimeUnit::Hour));
-}