制作API

simple-si-units 是专门为帮助人们创建用于执行科学计算的库和函数的更安全的API而设计的。

对于大多数应用程序，您只需为每个变量指定SI单位类型和数据类型即可，如下所示

use simple_si_units::base::Distance;
use simple_si_units::geometry::Volume;
use std::f64::consts::PI;

pub fn sphere_volume(radius: Distance<f64>) -> Volume<f64> {
   &radius * &radius * &radius *  4. / 3. * PI
}

但是，如果您想支持多个数据类型，那么您应该使用泛型模板函数。 simple-si-units 库提供 NumLike 类型，以帮助简化泛型API，例如

use simple_si_units::base::Distance;
use simple_si_units::geometry::Volume;
use std::f64::consts::PI;
use simple_si_units::NumLike;

pub fn sphere_volume<T>(radius: Distance<T>) -> Volume<T>
where T: NumLike + From<f64>
{
    &radius * &radius * &radius * T::from(4. / 3. * PI)
}

上述通用函数适用于任何实现了From<f64>的数字类型，例如Complex64或BigFloat（分别来自num-complex和num-bigfloat包）。

为什么不使用uom呢？

您不必选择，两者都可以使用！所有simple-si-units类型都实现了Into和From特质，以将它们转换为它们的uom等效类型。

uom和simple-si-units包都被设计用来提供科学单位的编译时类型检查，以帮助开发人员捕捉数学错误并编写更干净的计算API。区别在于uom还执行维度分析，但不能处理自定义数据类型，而simple-si-units处理任何类似数字的数据类型，但不会尝试实现完整的编译时维度分析。simple-si-units还优先考虑开发人员的易用性，遵循一致的Struct::from_...()和Struct.to_...()语法，以实现简单直观的数字转换。您选择使用uom或simple-si-units取决于您的需求。

以下表格比较了simple-si-units v1.0和uom v0.34，以帮助您决定使用哪一个

** simple-si-units中不全面支持整数类型和基于int的数字类型

为了进一步展示simple-si-units和uom之间的相似之处和不同之处，以下是同一重力计算函数的两个不同版本，一个使用simple-si-units，另一个使用uom

// simple-si-units version
mod simple_si_version {
  use simple_si_units::base::{Distance, Mass};
  use simple_si_units::mechanical::{Acceleration};

  pub fn calc_gravity(mass: Mass<f64>, dist: Distance<f64>) -> Acceleration<f64> {
    const G: f64 = 6.67408e-11; // m3 kg-1 s-2
    let d_squared = dist * dist;
    return Acceleration::from_mps2(G * mass.to_kg() / d_squared.to_m2())
  }

  fn test_gravity1() {
    let radius = Distance::from_km(6378.1);
    let mass = Mass::from_earth_mass(1.0);
    println!("simple-si-units: Earth gravity at sea-level is {}", calc_gravity(mass, radius));
  }
}

// uom version
mod uom_version {
  use uom::si::f64::{Length, Mass, Acceleration};
  use uom::si::length::*;
  use uom::si::mass::*;
  use uom::si::acceleration::*;
  use uom::fmt::DisplayStyle::Abbreviation;

  pub fn calc_gravity(mass: Mass, dist: Length) -> Acceleration {
    const G: f64 = 6.67408e-11; // m3 kg-1 s-2
    let d_squared = dist * dist;
    return Acceleration::new::<meter_per_second_squared>(G * mass.value / d_squared.value)
  }

  fn test_gravity2() {
    let radius = Length::new::<kilometer>(6378.1);
    let mass = Mass::new::<kilogram>(5.972e24);
    println!("uom: Earth gravity at sea-level is {}",
             calc_gravity(mass, radius).into_format_args(meter_per_second_squared, Abbreviation));
  }
}

工作原理

对于每种单位类型（例如距离），Simple SI Units提供了一个泛型结构体来表示该单位，并实现了常见的类型转换。例如，将距离除以时间会得到速度。

use simple_si_units::base::{Distance, Mass};
use simple_si_units::mechanical::{Acceleration};
pub fn calc_gravity(mass: Mass<f64>, dist: Distance<f64>) -> Acceleration<f64>{
	const G: f64 = 6.67408e-11; // m3 kg-1 s-2
	let d_squared = dist * dist;
	return Acceleration::from_mps2(G * mass.to_kg() / d_squared.to_m2())
}

fn main(){
	let a = calc_gravity(Mass::from_solar_mass(1.0), Distance::from_au(1.0));
	println!("Solar gravity at Earth orbital distance: {}", a);
}

由于这些结构体使用内部数据类型的泛型模板，因此您可以使用任何类似数字的数据类型与这些结构体一起使用，包括num_complex::Complex和num_bigfloat::BigFloat（有关不实现From<f64>的类型，请参见下面的限制部分）。

例如，可以将上述函数重写如下，以允许几乎任何类似数字的数据类型

use simple_si_units::base::{Distance, Mass};
use simple_si_units::mechanical::{Acceleration};
use simple_si_units::NumLike;

pub fn calc_gravity_generic<T>(mass: Mass<T>, dist: Distance<T>) -> Acceleration<T> 
  where T: NumLike+From<f64> 
{
  const G: f64 = 6.67408e-11; // m3 kg-1 s-2
  let d_squared = &dist * &dist;
  return Acceleration::from_mps2(T::from(G) * mass.to_kg() / d_squared.to_m2())
}

添加您自己的单位

简单的国际单位制（SI Units）并未提供可能的测量单位的全列表。要创建自己的单位，请使用 UnitStruct 程序宏和 NumLike 特性包（NumLike 只是 core::ops::*<Output=Self>+Clone+Debug+Display 的简写，如果你更喜欢，也可以使用来自 num-traits crate 的 Num 特性）。

use simple_si_units::{UnitStruct, NumLike};

#[derive(UnitStruct, Debug, Clone)]
struct HyperVelocity<T: NumLike>{
  square_meters_per_second: T
}

fn weighted_hypervel_sum<T: NumLike>(a: HyperVelocity<T>, b: HyperVelocity<T>, weight: f64) -> HyperVelocity<T>
  where T:NumLike + From<f64>
{
  return weight*a + (1.-weight)*b;
}

请注意，UnitStruct 继承宏仅在包含单个成员变量的结构体上工作。否则，它将生成编译器错误。

局限性

由于 Rust 编译器在稳定 Rust 中缺乏 类型专用化，一些单位构造函数（例如 Mass::from_g(...)）仅适用于实现了 From<f64> 的数字类型。这意味着这些函数将无法用于 Rust 的内置 f32 或整数类型。您仍然可以使用任何数字类型（例如 Mass::from_kg(1f32) 将正常工作）来构造单位结构体。

use std::ops::*;
use std::fmt::{Display, Formatter, Result};
use simple_si_units::base::Mass;
use simple_si_units::geometry::Volume;
use simple_si_units::mechanical::Density;

#[derive(Debug, Copy, Clone)]
struct MyNumber(f32);

impl Display for MyNumber {
  fn fmt(&self, f: &mut Formatter<'_>) -> Result {std::fmt::Display::fmt(&self.0, f)}
}
impl Add for MyNumber {
  type Output = MyNumber;
  fn add(self, rhs: Self) -> Self::Output {MyNumber(self.0 + rhs.0)}
}
impl AddAssign for MyNumber {
  fn add_assign(&mut self, rhs: Self) {self.0 += rhs.0;}
}
impl Sub for MyNumber {
  type Output = MyNumber;
  fn sub(self, rhs: Self) -> Self::Output {MyNumber(self.0 - rhs.0)}
}
impl SubAssign for MyNumber {
  fn sub_assign(&mut self, rhs: Self) {self.0 -= rhs.0;}
}
impl Mul for MyNumber {
  type Output = MyNumber;
  fn mul(self, rhs: Self) -> Self::Output {MyNumber(self.0 * rhs.0)}
}
impl MulAssign for MyNumber {
  fn mul_assign(&mut self, rhs: Self) {self.0 *= rhs.0;}
}
impl Div for MyNumber {
  type Output = MyNumber;
  fn div(self, rhs: Self) -> Self::Output {MyNumber(self.0 / rhs.0)}
}
impl DivAssign for MyNumber {
  fn div_assign(&mut self, rhs: Self) {self.0 /= rhs.0;}
}
impl Neg for MyNumber {
  type Output = MyNumber;
  fn neg(self) -> Self::Output {MyNumber(-self.0)}
}
impl From<f64> for MyNumber{
  fn from(value: f64) -> Self {MyNumber(value as f32)}
}

fn my_fn() -> Density<MyNumber>{
  let m = Mass::from_g(MyNumber(1222.5_f32));
  let v = Volume::from_L(MyNumber(11.3_f32));
  return m / v;
}