Rust哈希计算库ch_cityhash102使用指南

概述

ch_cityhash102是一个Rust实现的CityHash算法库，提供了高性能的字符串哈希计算功能。CityHash是Google开发的一系列非加密哈希函数，针对字符串数据进行了优化，特别适合哈希表等数据结构使用。

特性

• 高性能：针对现代CPU架构优化
• 低碰撞率：提供良好的哈希分布
• 支持多种输入类型：字符串、字节切片等
• 无依赖：纯Rust实现

使用方法

添加依赖

在Cargo.toml中添加：

[dependencies]
ch_cityhash102 = "0.1"

基本使用

use ch_cityhash102::city_hash_102_128;

fn main() {
    let data = "hello world";
    let hash = city_hash_102_128(data.as_bytes());
    
    println!("128-bit hash of '{}': {:?}", data, hash);
}

64位哈希

use ch_cityhash102::city_hash_102_64;

let hash = city_hash_102_64(b"example data");
println!("64-bit hash: {}", hash);

128位哈希

use ch_cityhash102::city_hash_102_128;

let hash = city_hash_102_128(b"example data");
println!("128-bit hash: {:?}", hash);  // 输出为(u64, u64)元组

带种子的哈希

use ch_cityhash102::city_hash_102_64_with_seed;

let hash = city_hash_102_64_with_seed(b"example data", 42);
println!("Seeded 64-bit hash: {}", hash);

性能优化建议

1. 对于小字符串(<=16字节)，直接使用64位哈希
2. 对于中等长度字符串(17-240字节)，使用128位哈希
3. 对于大字符串(>240字节)，考虑分块处理

示例：构建简单哈希表

use ch_cityhash102::city_hash_102_64;
use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    
    let key1 = "user1";
    let hash1 = city_hash_102_64(key1.as_bytes());
    map.insert(hash1, "John Doe");
    
    let key2 = "user2";
    let hash2 = city_hash_102_64(key2.as_bytes());
    map.insert(hash2, "Jane Smith");
    
    if let Some(name) = map.get(&hash1) {
        println!("Found user: {}", name);
    }
}

注意事项

1. CityHash不是加密哈希，不适用于安全敏感场景
2. 不同版本的CityHash可能产生不同的哈希值
3. 在32位系统上性能可能不如64位系统

基准测试

可以通过cargo bench运行内置的基准测试来比较不同哈希函数的性能：

#[bench]
fn bench_cityhash_64(b: &mut Bencher) {
    let data = "benchmark string".repeat(100);
    b.iter(|| city_hash_102_64(data.as_bytes()));
}

完整示例代码

下面是一个综合使用ch_cityhash102库的完整示例：

// 导入所需的哈希函数
use ch_cityhash102::{city_hash_102_64, city_hash_102_128, city_hash_102_64_with_seed};
use std::collections::HashMap;

fn main() {
    // 示例1：基本64位哈希
    let small_data = "short string";
    let hash_64 = city_hash_102_64(small_data.as_bytes());
    println!("64-bit hash for '{}': {}", small_data, hash_64);
    
    // 示例2：128位哈希
    let medium_data = "this is a medium length string for testing";
    let hash_128 = city_hash_102_128(medium_data.as_bytes());
    println!("128-bit hash for '{}': {:?}", medium_data, hash_128);
    
    // 示例3：带种子的哈希
    let seed = 12345;
    let seeded_hash = city_hash_102_64_with_seed(b"data with seed", seed);
    println!("Seeded hash: {}", seeded_hash);
    
    // 示例4：构建哈希表
    let mut user_db = HashMap::new();
    
    // 添加用户记录
    let users = vec![
        ("alice", "Alice Johnson"),
        ("bob", "Bob Smith"),
        ("charlie", "Charlie Brown")
    ];
    
    for (username, fullname) in users {
        let hash = city_hash_102_64(username.as_bytes());
        user_db.insert(hash, fullname);
    }
    
    // 查询用户
    let query = "alice";
    let query_hash = city_hash_102_64(query.as_bytes());
    if let Some(name) = user_db.get(&query_hash) {
        println!("Found user {}: {}", query, name);
    } else {
        println!("User {} not found", query);
    }
    
    // 性能测试示例
    let large_data = "a".repeat(500); // 创建500字节的字符串
    let hash_large = city_hash_102_128(large_data.as_bytes());
    println!("Large data hash: {:?}", hash_large);
}

这个完整示例展示了：

1. 对不同长度的字符串使用合适的哈希函数
2. 使用带种子的哈希
3. 实际应用中构建哈希表
4. 处理大字符串的哈希计算

您可以根据实际需求调整代码，例如：

• 对于非常大的数据，可以实现分块处理
• 根据性能测试结果选择最适合的哈希位数
• 在需要时使用不同的种子值