axhash 0.1.2

Fast non-cryptographic hash function for Rust with no_std support and strong HashMap performance.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

# axhash

[![Crates.io](https://img.shields.io/crates/v/axhash?style=flat-square&color=orange&logo=rust)](https://crates.io/crates/axhash)
[![Documentation](https://img.shields.io/docsrs/axhash?style=flat-square&logo=docs.rs)](https://docs.rs/axhash)
[![License](https://img.shields.io/crates/l/axhash?style=flat-square&color=blue)](https://crates.io/crates/axhash)
[![Downloads](https://img.shields.io/crates/d/axhash?style=flat-square&color=darkgreen)](https://crates.io/crates/axhash)
[![Support me on Ko-fi](https://img.shields.io/badge/Support%20me-Ko--fi-F16061?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/robby031)

axhash adalah hash function non-cryptographic untuk Rust yang dirancang untuk performa tinggi, distribusi bit yang merata, dan efisiensi pada workload nyata, khususnya pada key kecil hingga menengah dan penggunaan di struktur data seperti HashMap.

## Apa yang Baru di v0.1.2?

- Dokumentasi penggunaan diperbarui dan diperjelas untuk semua API publik
- Contoh penggunaan lebih lengkap untuk berbagai skenario (hash bytes, hash struct, integrasi HashMap, custom seed)
- Perbaikan minor pada dokumentasi dan penjelasan API

## Fitur Utama

- Kompatibel `no_std`, tanpa alokasi memori pada jalur utama
- Deterministik dan seeded, cocok untuk kebutuhan `indexing`, `cache`, dan `struktur data`
- Tidak bergantung pada crate eksternal
- Performa baik pada key kecil, menengah maupun payload besar
- Dirancang agar tahan terhadap collision attack pada workload umum `bukan kriptografi`

## Instalasi

Tambahkan ke Cargo.toml:

```toml
[dependencies]
axhash = "0.1.1"
```

## Benchmark (Apple M4)

Hasil benchmark internal menggunakan `Criterion.rs`:

![Hasil Hotloop](assets/screenshot_hotloop.png)
![Hasil Oneshoot](assets/screenshot_oneshoot.png)
![Hasil Streaming](assets/screenshot_streaming.png)

## API Publik & Contoh Penggunaan

### 1. Hash Bytes

Hash bytes dengan seed default (0):

```rust
use axhash::axhash;
let hash = axhash(b"axhash super power");
println!("Hash: {hash:016x}");
```

Hash bytes dengan custom seed:

```rust
use axhash::axhash_seeded;
let hash = axhash_seeded(b"axhash super power", 0x1234_5678);
println!("Hash: {hash:016x}");
```

### 2. Hash Tipe/Struct Apapun (Trait Hash)

Hash struct/tipe apapun yang mengimplementasikan trait `Hash`:

```rust
use axhash::axhash_of;
#[derive(Hash)]
struct DemoRecord {
	id: u64,
	shard: u32,
	flags: u32,
}
let record = DemoRecord { id: 1, shard: 2, flags: 3 };
let hash = axhash_of(&record);
println!("Hash: {hash:016x}");
```

Hash struct dengan custom seed:

```rust
use axhash::axhash_of_seeded;
let hash = axhash_of_seeded(&record, 0xDEADC0DE);
println!("Hash: {hash:016x}");
```

### 3. Integrasi dengan HashMap

axhash menyediakan `AxBuildHasher` untuk integrasi mudah dengan `HashMap`:

```rust
use axhash::AxBuildHasher;
use std::collections::HashMap;
let mut map = HashMap::with_hasher(AxBuildHasher::with_seed(0xDEADC0DE));
map.insert("key", "performance");
```

Jika ingin seed default:

```rust
let mut map = HashMap::with_hasher(AxBuildHasher::new());
```

### 4. Penggunaan Manual Hasher

Jika ingin kontrol penuh, gunakan `AxHasher` secara manual:

```rust
use axhash::AxHasher;
use core::hash::Hasher;
let mut hasher = AxHasher::new_with_seed(0x4444);
hasher.write_u64(0x0102_0304_0506_0708);
hasher.write_u32(0xaabb_ccdd);
hasher.write_u16(0xeeff);
hasher.write_u8(0x11);
let value = hasher.finish();
println!("Hash: {value:016x}");
```

## Penjelasan API

- `axhash(bytes: &[u8]) -> u64` — Hash bytes dengan seed default (0)
- `axhash_seeded(bytes: &[u8], seed: u64) -> u64` — Hash bytes dengan seed custom
- `axhash_of<T: Hash>(data: &T) -> u64` — Hash tipe/struct apapun yang implementasi trait `Hash` (seed default)
- `axhash_of_seeded<T: Hash>(data: &T, seed: u64) -> u64` — Hash tipe/struct apapun dengan seed custom
- `AxBuildHasher` — Untuk integrasi dengan HashMap, mendukung seed custom
- `AxHasher` — Hasher manual, implementasi trait `Hasher`

## Desain Singkat

axhash menggabungkan folded multiplication, branchless path untuk key kecil, dan teknik permutasi state untuk memastikan difusi bit yang merata dan performa konsisten pada berbagai ukuran data.

## Batasan

axhash bukan hash function kriptografi. `Jangan gunakan untuk password, tanda tangan digital, atau kebutuhan keamanan tingkat tinggi.`

## Lisensi

Proyek ini dirilis di bawah lisensi MIT.