README.md
1hashbrown
2=========
3
4[](https://github.com/rust-lang/hashbrown/actions)
5[](https://crates.io/crates/hashbrown)
6[](https://docs.rs/hashbrown)
7[](https://github.com/rust-lang/hashbrown)
8
9This crate is a Rust port of Google's high-performance [SwissTable] hash
10map, adapted to make it a drop-in replacement for Rust's standard `HashMap`
11and `HashSet` types.
12
13The original C++ version of SwissTable can be found [here], and this
14[CppCon talk] gives an overview of how the algorithm works.
15
16Since Rust 1.36, this is now the `HashMap` implementation for the Rust standard
17library. However you may still want to use this crate instead since it works
18in environments without `std`, such as embedded systems and kernels.
19
20[SwissTable]: https://abseil.io/blog/20180927-swisstables
21[here]: https://github.com/abseil/abseil-cpp/blob/master/absl/container/internal/raw_hash_set.h
22[CppCon talk]: https://www.youtube.com/watch?v=ncHmEUmJZf4
23
24## [Change log](CHANGELOG.md)
25
26## Features
27
28- Drop-in replacement for the standard library `HashMap` and `HashSet` types.
29- Uses [foldhash](https://github.com/orlp/foldhash) as the default hasher, which is much faster than SipHash.
30 However, foldhash does *not provide the same level of HashDoS resistance* as SipHash, so if that is important to you, you might want to consider using a different hasher.
31- Around 2x faster than the previous standard library `HashMap`.
32- Lower memory usage: only 1 byte of overhead per entry instead of 8.
33- Compatible with `#[no_std]` (but requires a global allocator with the `alloc` crate).
34- Empty hash maps do not allocate any memory.
35- SIMD lookups to scan multiple hash entries in parallel.
36
37## Usage
38
39Add this to your `Cargo.toml`:
40
41```toml
42[dependencies]
43hashbrown = "0.14"
44```
45
46Then:
47
48```rust
49use hashbrown::HashMap;
50
51let mut map = HashMap::new();
52map.insert(1, "one");
53```
54## Flags
55This crate has the following Cargo features:
56
57- `nightly`: Enables nightly-only features including: `#[may_dangle]`.
58- `serde`: Enables serde serialization support.
59- `borsh`: Enables borsh serialization support.
60- `rayon`: Enables rayon parallel iterator support.
61- `equivalent`: Allows comparisons to be customized with the `Equivalent` trait. (enabled by default)
62- `raw-entry`: Enables access to the deprecated `RawEntry` API.
63- `inline-more`: Adds inline hints to most functions, improving run-time performance at the cost
64 of compilation time. (enabled by default)
65- `default-hasher`: Compiles with foldhash as default hasher. (enabled by default)
66- `allocator-api2`: Enables support for allocators that support `allocator-api2`. (enabled by default)
67
68## License
69
70Licensed under either of:
71
72 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
73 * MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
74
75at your option.
76
77### Contribution
78
79Unless you explicitly state otherwise, any contribution intentionally submitted
80for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
81additional terms or conditions.
82
){kind=link}
){kind=link}
){kind=link}
){kind=link}