Rust通用工具库erg_common的使用指南

简介

erg_common是Rust生态中的一个高效通用工具库，提供了一系列基础组件和常用功能扩展，旨在简化Rust开发中的常见任务，提高开发效率。

主要功能

1. 高效的基础数据结构
2. 常用算法实现
3. 字符串处理工具
4. 文件操作辅助
5. 并发编程工具
6. 错误处理增强

安装方法

在Cargo.toml中添加依赖：

[dependencies]
erg_common = "0.3"  # 请使用最新版本

使用示例

1. 字符串处理

use erg_common::str_util;

fn main() {
    // 快速字符串连接
    let parts = vec!["Hello", " ", "world", "!"];
    let combined = str_util::fast_join(&parts);
    println!("{}", combined);  // 输出: Hello world!
    
    // 安全截取字符串
    let s = "你好，世界！";
    let sub = str_util::safe_substr(s, 3, 6).unwrap();
    println!("{}", sub);  // 输出: 世界
}

2. 高效集合操作

use erg_common::collections::{FastHashMap, FastHashSet};

fn main() {
    // 快速HashMap
    let mut map = FastHashMap::new();
    map.insert("key1", 42);
    map.insert("key2", 100);
    
    // 快速HashSet
    let mut set = FastHashSet::new();
    set.insert(1);
    set.insert(2);
    set.insert(3);
    
    println!("Map: {:?}, Set: {:?}", map, set);
}

3. 文件操作辅助

use erg_common::file_util;
use std::path::Path;

fn main() -> std::io::Result<()> {
    // 递归创建目录
    file_util::ensure_dir_exists(Path::new("./data/logs"))?;
    
    // 安全写入文件
    file_util::atomic_write(Path::new("config.toml"), b"key = \"value\"")?;
    
    Ok(())
}

4. 错误处理增强

use erg_common::error::{ErrorExt, ResultExt};

fn parse_number(s: &str) -> Result<i32, String> {
    s.parse().map_err(|e| format!("Failed to parse '{}': {}", s, e))
}

fn main() {
    let result = parse_number("42a")
        .add_context("Parsing user input")
        .log_error();  // 自动记录错误日志
        
    if let Err(e) = result {
        println!("Error occurred: {}", e.full_message());
    }
}

5. 并发工具

use erg_common::sync::{AsyncQueue, ParallelMap};
use std::time::Duration;

#[tokio::main]
async fn main() {
    // 异步队列
    let queue = AsyncQueue::new();
    queue.push(1).await;
    queue.push(2).await;
    
    while let Some(item) = queue.pop().await {
        println!("Got: {}", item);
    }
    
    // 并行处理
    let data = vec![1, 2, 3, 4, 5];
    let results = data.parallel_map(|x| x * 2, 4);  // 4个线程
    println!("{:?}", results);  // [2, 4, 6, 8, 10]
}

完整示例

// 完整示例展示erg_common多个功能的综合使用
use erg_common::{
    collections::{FastHashMap, FastHashSet},
    error::{ErrorExt, ResultExt},
    file_util,
    str_util,
    sync::{AsyncQueue, ParallelMap},
};
use std::path::Path;
use tokio::runtime::Runtime;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. 字符串处理示例
    let parts = vec!["Rust", " ", "erg_common", " ", "demo"];
    let combined = str_util::fast_join(&parts);
    println!("字符串连接结果: {}", combined);

    // 2. 集合操作示例
    let mut word_counts = FastHashMap::new();
    word_counts.insert("hello", 3);
    word_counts.insert("world", 5);
    
    let mut unique_numbers = FastHashSet::new();
    for i in 1..=5 {
        unique_numbers.insert(i);
    }
    println!("单词计数: {:?}", word_counts);
    println!("唯一数字: {:?}", unique_numbers);

    // 3. 文件操作示例
    file_util::ensure_dir_exists(Path::new("./tmp/erg_demo"))?;
    file_util::atomic_write(Path::new("./tmp/erg_demo/config.txt"), b"demo config")?;

    // 4. 错误处理示例
    let parse_result = "123x".parse::<i32>()
        .map_err(|e| format!("解析错误: {}", e))
        .add_context("处理用户输入数字")
        .log_error();
    
    if let Err(e) = parse_result {
        println!("错误详情: {}", e.full_message());
    }

    // 5. 并发工具示例 (需要运行时)
    let rt = Runtime::new()?;
    rt.block_on(async {
        let queue = AsyncQueue::new();
        queue.push("任务1".to_string()).await;
        queue.push("任务2".to_string()).await;
        
        while let Some(task) = queue.pop().await {
            println!("处理任务: {}", task);
        }
        
        // 并行映射
        let nums = vec![10, 20, 30, 40];
        let doubled = nums.parallel_map(|x| x * 2, 2);
        println!("并行处理结果: {:?}", doubled);
    });

    Ok(())
}

性能建议

1. 对于高频操作，优先使用Fast前缀的数据结构
2. 大量字符串操作使用str_util模块
3. 文件操作使用atomic_前缀的方法保证安全性
4. 并发场景使用提供的同步原语

总结

erg_common为Rust开发者提供了一系列经过优化的常用工具，可以显著减少样板代码，提高开发效率和运行性能。根据项目需求选择适当的功能模块，可以快速构建高质量的Rust应用。