README.md
1# TwoX-Hash
2
3A Rust implementation of the [XXHash] algorithm.
4
5[](https://travis-ci.org/shepmaster/twox-hash) [](https://crates.io/crates/twox-hash)
6
7[Documentation](https://docs.rs/twox-hash/)
8
9[XXHash]: https://github.com/Cyan4973/xxHash
10
11## Examples
12
13### With a fixed seed
14
15```rust
16use std::hash::BuildHasherDefault;
17use std::collections::HashMap;
18use twox_hash::XxHash64;
19
20let mut hash: HashMap<_, _, BuildHasherDefault<XxHash64>> = Default::default();
21hash.insert(42, "the answer");
22assert_eq!(hash.get(&42), Some(&"the answer"));
23```
24
25### With a random seed
26
27```rust
28use std::collections::HashMap;
29use twox_hash::RandomXxHashBuilder64;
30
31let mut hash: HashMap<_, _, RandomXxHashBuilder64> = Default::default();
32hash.insert(42, "the answer");
33assert_eq!(hash.get(&42), Some(&"the answer"));
34```
35
36## Benchmarks
37
38### 64-bit
39
40| Bytes | SipHasher (MB/s) | XXHash (MB/s) | Ratio |
41|---------|------------------|---------------|-------|
42| 1 | 52 | 38 | 73% |
43| 4 | 210 | 148 | 70% |
44| 16 | 615 | 615 | 100% |
45| 32 | 914 | 1391 | 152% |
46| 128 | 1347 | 3657 | 271% |
47| 256 | 1414 | 5019 | 355% |
48| 512 | 1546 | 6168 | 399% |
49| 1024 | 1565 | 6206 | 397% |
50| 1048576 | 1592 | 7564 | 475% |
51
52| Bytes | [FnvHasher][fnv] (MB/s) | XXHash (MB/s) | Ratio |
53|---------|-------------------------|---------------|-------|
54| 1 | 1000 | 38 | 4% |
55| 4 | 800 | 148 | 19% |
56| 16 | 761 | 615 | 81% |
57| 32 | 761 | 1391 | 183% |
58| 128 | 727 | 3657 | 503% |
59| 256 | 759 | 5019 | 661% |
60| 512 | 745 | 6168 | 828% |
61| 1024 | 741 | 6206 | 838% |
62| 1048576 | 745 | 7564 | 1015% |
63
64### 32-bit
65
66| Bytes | SipHasher (MB/s) | XXHash32 (MB/s) | Ratio |
67|---------|------------------|-----------------|-------|
68| 1 | 52 | 55 | 106% |
69| 4 | 210 | 210 | 100% |
70| 16 | 615 | 1230 | 200% |
71| 32 | 914 | 1882 | 206% |
72| 128 | 1347 | 3282 | 244% |
73| 256 | 1414 | 3459 | 245% |
74| 512 | 1546 | 3792 | 245% |
75| 1024 | 1565 | 3938 | 252% |
76| 1048576 | 1592 | 4127 | 259% |
77
78| Bytes | [FnvHasher][fnv] (MB/s) | XXHash32 (MB/s) | Ratio |
79|---------|-------------------------|-----------------|-------|
80| 1 | 1000 | 55 | 6% |
81| 4 | 800 | 210 | 26% |
82| 16 | 761 | 1230 | 162% |
83| 32 | 761 | 1882 | 247% |
84| 128 | 727 | 3282 | 451% |
85| 256 | 759 | 3459 | 456% |
86| 512 | 745 | 3792 | 509% |
87| 1024 | 741 | 3938 | 531% |
88| 1048576 | 745 | 4127 | 554% |
89
90
91[fnv]: https://github.com/servo/rust-fnv
92
93## Contributing
94
951. Fork it ( https://github.com/shepmaster/twox-hash/fork )
962. Create your feature branch (`git checkout -b my-new-feature`)
973. Add a failing test.
984. Add code to pass the test.
995. Commit your changes (`git commit -am 'Add some feature'`)
1006. Ensure tests pass.
1017. Push to the branch (`git push origin my-new-feature`)
1028. Create a new Pull Request
103
){kind=link}
){kind=link}