Rust物理量单位计算库dimensioned使用指南

dimensioned是一个Rust库，提供类型安全的物理量单位转换和计算功能，能够在编译期检查单位一致性，避免单位不匹配的错误。

基本特性

• 类型安全的单位系统
• 编译期单位检查
• 支持自定义单位系统
• 支持基本数学运算
• 自动单位简化

安装

在Cargo.toml中添加依赖：

[dependencies]
dimensioned = "0.8.0"

基本用法

1. 使用预定义单位系统

dimensioned提供了几种预定义的单位系统，如si(国际单位制)和fps(英尺磅秒制)。

use dimensioned as dim;
use dim::si;

fn main() {
    // 创建带有单位的量
    let length1 = 3.0 * si::M;
    let length2 = 2.0 * si::M;
    
    // 类型安全的运算
    let total_length = length1 + length2;
    println!("总长度: {}", total_length);
    
    // 尝试错误的运算(编译时会报错)
    // let time = 5.0 * si::S;
    // let invalid = length1 + time; // 错误!不能把长度和时间相加
}

2. 单位转换

use dimensioned as dim;
use dim::si;
use dim::fps;

fn main() {
    let speed_si = 10.0 * si::M / si::S;
    let speed_fps = speed_si.into::<fps::FtPerS>();
    println!("{} = {}", speed_si, speed_fps);
}

3. 自定义单位

#[macro_use]
extern crate dimensioned as dim;

use dim::si;

// 定义自定义单位
make_units! {
    MyUnits {
        // 定义新单位FOO = 3.2米
        FOO: 3.2 * si::M,
        // 定义新单位BAR = 5.7秒
        BAR: 5.7 * si::S,
    }
}

fn main() {
    let x = 2.0 * MyUnits::FOO;
    let y = x.into::<si::M>();
    println!("{} FOO = {} m", x, y);
}

4. 复合单位运算

use dimensioned as dim;
use dim::si;

fn main() {
    let speed = 60.0 * si::KM / si::H;
    let time = 30.0 * si::M;
    let distance = speed * time;
    
    println!("行驶距离: {}", distance);
    
    // 转换为千米
    println!("行驶距离: {}", distance.into::<si::KM>());
}

5. 单位简化

use dimensioned as dim;
use dim::si;

fn main() {
    let force = 5.0 * si::KG * si::M / (si::S * si::S);
    // 自动简化为牛顿
    println!("力: {}", force); // 显示 5 N
}

高级用法

自定义单位系统

#[macro_use]
extern crate dimensioned as dim;

make_units! {
    Pub CookingUnits {
        Teaspoon: 0.00492892 * dim::si::M3,  // 茶匙
        Tablespoon: 3.0 * Teaspoon,           // 汤匙 = 3茶匙
        Cup: 16.0 * Tablespoon,              // 杯 = 16汤匙
    }
}

fn main() {
    let tsp = 3.0 * CookingUnits::Teaspoon;
    let tbsp = tsp.into::<CookingUnits::Tablespoon>();
    println!("{} = {}", tsp, tbsp);
}

与无单位数值转换

use dimensioned as dim;
use dim::si;

fn main() {
    let length = 5.0 * si::M;
    let value: f64 = length.value_unsafe(); // 获取无单位数值(不安全)
    println!("数值部分: {}", value);
    
    // 更安全的方式
    let value = length.value();
    println!("数值部分: {:?}", value);
}

完整示例

下面是一个完整的示例，展示了dimensioned库的多种用法：

#[macro_use]
extern crate dimensioned as dim;

use dim::si;
use dim::fps;

// 定义自定义单位系统
make_units! {
    MyCustomUnits {
        Furlong: 201.168 * si::M,  // 浪 = 201.168米
        Fortnight: 1209600.0 * si::S,  // 两周 = 1209600秒
    }
}

fn main() {
    // 1. 使用预定义单位系统
    let distance = 5.0 * si::KM;
    let time = 2.0 * si::H;
    let speed = distance / time;
    println!("速度: {}", speed);
    
    // 2. 单位转换
    let speed_fps = speed.into::<fps::FtPerS>();
    println!("转换后的速度: {}", speed_fps);
    
    // 3. 使用自定义单位
    let race_length = 8.0 * MyCustomUnits::Furlong;
    let race_time = 1.0 * MyCustomUnits::Fortnight;
    let funny_speed = race_length / race_time;
    println!("奇特速度: {}", funny_speed);
    
    // 4. 复合单位运算
    let acceleration = speed / time;
    println!("加速度: {}", acceleration);
    
    // 5. 单位简化
    let energy = 2.0 * si::KG * si::M * si::M / (si::S * si::S);
    println!("能量: {}", energy);  // 自动显示为焦耳
    
    // 6. 安全获取数值
    match distance.value() {
        Some(val) => println!("距离数值: {}", val),
        None => println!("获取数值失败"),
    }
}

注意事项

1. dimensioned在编译期检查单位一致性，这意味着错误的单位操作会在编译时报错而不是运行时
2. 单位转换可能会导致精度损失
3. 对于复杂计算，类型推断可能会变得复杂，可能需要显式类型注解

dimensioned库非常适合需要严格单位控制的科学计算、工程应用和物理模拟等场景，能有效防止因单位错误导致的bug。