README.md
1A Rust implementation of the [xxHash] algorithm.
2
3[![Crates.io][crates-badge]][crates-url]
4[![Documentation][docs-badge]][docs-url]
5[![Build Status][actions-badge]][actions-url]
6
7[xxHash]: https://github.com/Cyan4973/xxHash
8
9[crates-badge]: https://img.shields.io/crates/v/twox-hash.svg
10[crates-url]: https://crates.io/crates/twox-hash
11[docs-badge]: https://img.shields.io/docsrs/twox-hash
12[docs-url]: https://docs.rs/twox-hash/
13[actions-badge]: https://github.com/shepmaster/twox-hash/actions/workflows/ci.yml/badge.svg?branch=main
14[actions-url]: https://github.com/shepmaster/twox-hash/actions/workflows/ci.yml?query=branch%3Amain
15
16# Examples
17
18These examples use [`XxHash64`][] but the same ideas can be
19used for [`XxHash32`][] or [`XxHash3_64`][].
20
21## Hashing arbitrary data
22
23### When all the data is available at once
24
25```rust
26use twox_hash::XxHash64;
27
28let seed = 1234;
29let hash = XxHash64::oneshot(seed, b"some bytes");
30assert_eq!(0xeab5_5659_a496_d78b, hash);
31```
32
33### When the data is streaming
34
35```rust
36use std::hash::Hasher as _;
37use twox_hash::XxHash64;
38
39let seed = 1234;
40let mut hasher = XxHash64::with_seed(seed);
41hasher.write(b"some");
42hasher.write(b" ");
43hasher.write(b"bytes");
44let hash = hasher.finish();
45assert_eq!(0xeab5_5659_a496_d78b, hash);
46```
47
48## In a [`HashMap`][]
49
50### With a default seed
51
52```rust
53use std::{collections::HashMap, hash::BuildHasherDefault};
54use twox_hash::XxHash64;
55
56let mut hash = HashMap::<_, _, BuildHasherDefault<XxHash64>>::default();
57hash.insert(42, "the answer");
58assert_eq!(hash.get(&42), Some(&"the answer"));
59```
60
61### With a random seed
62
63```rust
64use std::collections::HashMap;
65use twox_hash::xxhash64;
66
67let mut hash = HashMap::<_, _, xxhash64::RandomState>::default();
68hash.insert(42, "the answer");
69assert_eq!(hash.get(&42), Some(&"the answer"));
70```
71
72### With a fixed seed
73
74```rust
75use std::collections::HashMap;
76use twox_hash::xxhash64;
77
78let mut hash = HashMap::with_hasher(xxhash64::State::with_seed(0xdead_cafe));
79hash.insert(42, "the answer");
80assert_eq!(hash.get(&42), Some(&"the answer"));
81```
82
83# Feature Flags
84
85| name | description |
86|------------|---------------------------------------------------------------------------------------------------------|
87| xxhash32 | Include the [`XxHash32`][] algorithm |
88| xxhash64 | Include the [`XxHash64`][] algorithm |
89| xxhash3_64 | Include the [`XxHash3_64`][] algorithm |
90| random | Create random instances of the hashers |
91| serialize | Serialize and deserialize hasher state with Serde |
92| std | Use the Rust standard library. Enable this if you want SIMD support in [`XxHash3_64`][] |
93| alloc | Use the Rust allocator library. Enable this if you want to create [`XxHash3_64`][] with dynamic secrets |
94
95# Benchmarks
96
97See benchmarks in the [comparison][] README.
98
99[comparison]: https://github.com/shepmaster/twox-hash/tree/main/comparison
100
101# Contributing
102
1031. Fork it (<https://github.com/shepmaster/twox-hash/fork>)
1042. Create your feature branch (`git checkout -b my-new-feature`)
1053. Add a failing test.
1064. Add code to pass the test.
1075. Commit your changes (`git commit -am 'Add some feature'`)
1086. Ensure tests pass.
1097. Push to the branch (`git push origin my-new-feature`)
1108. Create a new Pull Request
111
112
113[`Hashmap`]: std::collections::HashMap
114[`XxHash32`]: crate::XxHash32
115[`XxHash64`]: crate::XxHash64
116[`XxHash3_64`]: crate::XxHash3_64
117