Skip to content

Commit 878cf51

Browse files
committed
Document byte-wise hashing.
Fixes #97.
1 parent ee5bd04 commit 878cf51

File tree

1 file changed

+29
-5
lines changed

1 file changed

+29
-5
lines changed

src/hashing.md

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
# Hashing
22

3-
`HashSet` and `HashMap` are two widely-used types. The default hashing
4-
algorithm is not specified, but at the time of writing the default is an
5-
algorithm called [SipHash 1-3]. This algorithm is high quality—it provides high
6-
protection against collisions—but is relatively slow, particularly for short keys
7-
such as integers.
3+
`HashSet` and `HashMap` are two widely-used types and there are ways to make
4+
them faster.
5+
6+
## Alternative Hashers
7+
8+
The default hashing algorithm is not specified, but at the time of writing the
9+
default is an algorithm called [SipHash 1-3]. This algorithm is high quality—it
10+
provides high protection against collisions—but is relatively slow,
11+
particularly for short keys such as integers.
812

913
[SipHash 1-3]: https://en.wikipedia.org/wiki/SipHash
1014

@@ -58,3 +62,23 @@ Hash function design is a complex topic and is beyond the scope of this book.
5862
The [`ahash` documentation] has a good discussion.
5963

6064
[`ahash` documentation]: https://github.com/tkaitchuck/aHash/blob/master/compare/readme.md
65+
66+
## Byte-wise Hashing
67+
68+
When you annotate a type with `#[derive(Hash)]` the generated `hash` method
69+
will hash each field separately. For some hash functions it may be faster to
70+
convert the type to raw bytes and hash the bytes as a stream. This is possible
71+
for types that satisfy certain properties such as having no padding bytes.
72+
73+
The [`zerocopy`] and [`bytemuck`] crates both provide a `#[derive(ByteHash)]`
74+
macro that generates a `hash` method that does this kind of byte-wise hashing.
75+
The README for the [`derive_hash_fast`] crate provides more detail for this
76+
technique.
77+
78+
[`zerocopy`]: https://crates.io/crates/zerocopy
79+
[`bytemuck`]: https://crates.io/crates/bytemuck
80+
[`derive_hash_fast`]: https://crates.io/crates/derive_hash_fast
81+
82+
This is an advanced technique, and the performance effects are highly dependent
83+
on the hash function and the exact structure of the types being hashed. Measure
84+
carefully.

0 commit comments

Comments
 (0)