|
1 | 1 | # hash_hasher |
2 | 2 |
|
3 | | -A [`std::hash::Hasher`](https://doc.rust-lang.org/std/hash/trait.Hasher.html) which is designed to |
4 | | -work with already-hashed or hash-like data. |
| 3 | +A [`std::hash::Hasher`](https://doc.rust-lang.org/std/hash/trait.Hasher.html) |
| 4 | +which is designed to work with already-hashed or hash-like data. |
5 | 5 |
|
6 | 6 | [](https://docs.rs/hash_hasher) |
7 | | -[](https://crates.io/crates/hash_hasher) |
8 | | -[](https://ci.appveyor.com/project/Fraser999/hash-hasher/branch/master) |
9 | | -[](https://travis-ci.org/Fraser999/Hash-Hasher) |
| 7 | +[](https://crates.io/crates/hash_hasher) |
| 8 | +[](https://github.com/Fraser999/Hash-Hasher/actions/workflows/ci.yml) |
10 | 9 |
|
11 | 10 | ## Details |
12 | 11 |
|
13 | | -The provided hasher does minimal work under the assumption that the input data is already suitable |
14 | | -for use as a key in a `HashSet` or `HashMap`. |
| 12 | +The provided hasher does minimal work under the assumption that the input data |
| 13 | +is already suitable for use as a key in a `HashSet` or `HashMap`. |
15 | 14 |
|
16 | | -As well as the performance benefit, it also causes `HashSet`s or `HashMap`s to become somewhat |
17 | | -deterministic. Given two equal `HashSet`s or `HashMap`s containing more than a single element, |
18 | | -iterating them will yield the elements in differing orders. By using a |
19 | | -[`hash_hasher::HashedSet`](https://docs.rs/hash_hasher/*/hash_hasher/type.HashedSet.html) or |
20 | | -[`hash_hasher::HashedMap`](https://docs.rs/hash_hasher/*/hash_hasher/type.HashedMap.html), then if |
21 | | -the same data is inserted and/or removed *in the same order*, iterating the collection will yield a |
22 | | -consistent order. |
| 15 | +As well as the performance benefit, it also causes `HashSet`s or `HashMap`s to |
| 16 | +become somewhat deterministic. Given two equal `HashSet`s or `HashMap`s |
| 17 | +containing more than a single element, iterating them will likely yield the |
| 18 | +elements in differing orders. By using a |
| 19 | +[`hash_hasher::HashedSet`](https://docs.rs/hash_hasher/*/hash_hasher/type.HashedSet.html) |
| 20 | +or |
| 21 | +[`hash_hasher::HashedMap`](https://docs.rs/hash_hasher/*/hash_hasher/type.HashedMap.html), |
| 22 | +then if the same data is inserted and/or removed *in the same order*, iterating |
| 23 | +the collection will yield a consistent order. |
23 | 24 |
|
24 | 25 | ## Example |
25 | 26 |
|
26 | | -Since `new()` and `with_capacity()` aren't available for `HashSet`s or `HashMap`s using custom |
27 | | -hashers, the available constructors are `default()`, `with_hasher()` and |
28 | | -`with_capacity_and_hasher()`. |
| 27 | +Since `new()` and `with_capacity()` aren't available for `HashSet`s or |
| 28 | +`HashMap`s using custom hashers, the available constructors are `default()`, |
| 29 | +`with_hasher()` and `with_capacity_and_hasher()`. |
29 | 30 |
|
30 | 31 | ```rust |
31 | | -extern crate hash_hasher; |
32 | | - |
33 | 32 | use hash_hasher::{HashBuildHasher, HashedMap, HashedSet}; |
34 | 33 |
|
35 | | -let mut map = HashedMap::default(); |
| 34 | +let mut map = HashedMap::default (); |
36 | 35 | assert!(map.insert(0, "zero").is_none()); |
37 | 36 |
|
38 | | -let mut set = HashedSet::with_capacity_and_hasher(100, HashBuildHasher::default()); |
| 37 | +let mut set = HashedSet::with_capacity_and_hasher(100, HashBuildHasher::default ()); |
39 | 38 | assert!(set.insert(0)); |
40 | 39 | ``` |
41 | 40 |
|
42 | 41 | ## Benchmarks |
43 | 42 |
|
44 | | -A benchmark suite is included and sample figures can be found at the end of the nightly jobs of the |
45 | | -[AppVeyor results](https://ci.appveyor.com/project/Fraser999/hash-hasher/branch/master) and the |
46 | | -[Travis results](https://travis-ci.org/Fraser999/Hash-Hasher). |
| 43 | +A benchmark suite is included and sample figures can be found in the |
| 44 | +[CI results](https://github.com/Fraser999/Hash-Hasher/actions/workflows/ci.yml) |
| 45 | +in the `benchmarks-and-checks` job under the `Run benchmarks` step. |
47 | 46 |
|
48 | 47 | For example: |
49 | 48 |
|
50 | 49 | ``` |
51 | | -insert_sha1s_into_set_using_default_hasher ... bench: 1,171 ns/iter (+/- 30) |
52 | | -insert_sha1s_into_set_using_hash_hasher ... bench: 533 ns/iter (+/- 9) |
53 | | -
|
54 | | -insert_sha256s_into_set_using_default_hasher ... bench: 1,340 ns/iter (+/- 57) |
55 | | -insert_sha256s_into_set_using_hash_hasher ... bench: 546 ns/iter (+/- 11) |
56 | | -
|
57 | | -insert_sha512s_into_set_using_default_hasher ... bench: 1,804 ns/iter (+/- 2,597) |
58 | | -insert_sha512s_into_set_using_hash_hasher ... bench: 704 ns/iter (+/- 22) |
59 | | -
|
60 | | -insert_sip_hashes_into_set_using_default_hasher ... bench: 781 ns/iter (+/- 33) |
61 | | -insert_sip_hashes_into_set_using_hash_hasher ... bench: 256 ns/iter (+/- 50) |
| 50 | +test hash_sha1s_using_default_hasher ... bench: 191.12 ns/iter (+/- 17.41) |
| 51 | +test hash_sha1s_using_fnv_hasher ... bench: 196.12 ns/iter (+/- 3.09) |
| 52 | +test hash_sha1s_using_hash_hasher ... bench: 0.18 ns/iter (+/- 0.00) |
| 53 | +test hash_sha256s_using_default_hasher ... bench: 248.04 ns/iter (+/- 4.94) |
| 54 | +test hash_sha256s_using_fnv_hasher ... bench: 369.20 ns/iter (+/- 3.10) |
| 55 | +test hash_sha256s_using_hash_hasher ... bench: 0.18 ns/iter (+/- 0.00) |
| 56 | +test hash_sha512s_using_default_hasher ... bench: 263.13 ns/iter (+/- 0.30) |
| 57 | +test hash_sha512s_using_fnv_hasher ... bench: 1,058.13 ns/iter (+/- 3.17) |
| 58 | +test hash_sha512s_using_hash_hasher ... bench: 0.18 ns/iter (+/- 0.01) |
| 59 | +test hash_sip_hashes_using_default_hasher ... bench: 0.18 ns/iter (+/- 0.01) |
| 60 | +test hash_sip_hashes_using_fnv_hasher ... bench: 0.18 ns/iter (+/- 0.01) |
| 61 | +test hash_sip_hashes_using_hash_hasher ... bench: 0.18 ns/iter (+/- 0.01) |
| 62 | +test insert_sha1s_into_fnv_set ... bench: 281.13 ns/iter (+/- 5.70) |
| 63 | +test insert_sha1s_into_set_using_default_hasher ... bench: 381.28 ns/iter (+/- 9.83) |
| 64 | +test insert_sha1s_into_set_using_hash_hasher ... bench: 97.50 ns/iter (+/- 0.69) |
| 65 | +test insert_sha256s_into_set_using_default_hasher ... bench: 407.91 ns/iter (+/- 20.46) |
| 66 | +test insert_sha256s_into_set_using_fnv_hasher ... bench: 823.43 ns/iter (+/- 41.30) |
| 67 | +test insert_sha256s_into_set_using_hash_hasher ... bench: 90.92 ns/iter (+/- 0.89) |
| 68 | +test insert_sha512s_into_set_using_default_hasher ... bench: 541.99 ns/iter (+/- 18.94) |
| 69 | +test insert_sha512s_into_set_using_fnv_hasher ... bench: 1,338.65 ns/iter (+/- 47.01) |
| 70 | +test insert_sha512s_into_set_using_hash_hasher ... bench: 190.27 ns/iter (+/- 1.28) |
| 71 | +test insert_sip_hashes_into_set_using_default_hasher ... bench: 265.87 ns/iter (+/- 3.10) |
| 72 | +test insert_sip_hashes_into_set_using_fnv_hasher ... bench: 113.35 ns/iter (+/- 4.27) |
| 73 | +test insert_sip_hashes_into_set_using_hash_hasher ... bench: 55.40 ns/iter (+/- 0.16) |
62 | 74 | ``` |
63 | 75 |
|
64 | 76 | ## License |
65 | 77 |
|
66 | 78 | Licensed under either of |
67 | 79 |
|
68 | | -* [Apache License, Version 2.0](https://opensource.org/licenses/Apache-2.0) (see also [LICENSE-APACHE](LICENSE-APACHE)) |
69 | | -* [MIT License](https://opensource.org/licenses/MIT) (see also [LICENSE-MIT](LICENSE-MIT)) |
| 80 | +* [Apache License, Version 2.0](https://opensource.org/licenses/Apache-2.0) (see |
| 81 | + also [LICENSE-APACHE](LICENSE-APACHE)) |
| 82 | +* [MIT License](https://opensource.org/licenses/MIT) (see |
| 83 | + also [LICENSE-MIT](LICENSE-MIT)) |
70 | 84 |
|
71 | 85 | at your option. |
72 | 86 |
|
73 | 87 | ## Contribution |
74 | 88 |
|
75 | | -Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the |
76 | | -work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any |
77 | | -additional terms or conditions. |
| 89 | +Unless you explicitly state otherwise, any contribution intentionally submitted |
| 90 | +for inclusion in the work by you, as defined in the Apache-2.0 license, shall |
| 91 | +be dual licensed as above, without any additional terms or conditions. |
0 commit comments