1# TwoX-Hash
2
3A Rust implementation of the [XXHash] algorithm.
4
5[![Build Status](https://travis-ci.org/shepmaster/twox-hash.svg)](https://travis-ci.org/shepmaster/twox-hash) [![Current Version](https://img.shields.io/crates/v/twox-hash.svg)](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