[](https://github.com/yegor256/micromap/actions/workflows/cargo.yml)
[](https://crates.io/crates/micromap)
[](https://codecov.io/gh/yegor256/micromap)
[](https://hitsofcode.com/view/github/yegor256/micromap)
[](https://github.com/yegor256/micromap/blob/master/LICENSE.txt)
[](https://docs.rs/micromap/latest/micromap/)
A much faster alternative of [`HashMap`](https://doc.rust-lang.org/std/collections/struct.HashMap.html),
for very small maps.
It is also faster than
[FxHashMap](https://github.com/rust-lang/rustc-hash),
[hashbrown](https://github.com/rust-lang/hashbrown),
[ArrayMap](https://github.com/robjtede/tinymap),
[IndexMap](https://crates.io/crates/indexmap),
and _all_ others.
The smaller the map, the higher the performance.
It was observed that when a map contains more than 20 keys, it may be better to use the standard
[`HashMap`](https://doc.rust-lang.org/std/collections/struct.HashMap.html), since
the performance of `micromap::Map` _may_ start to degrade.
See the [benchmarking results](#benchmark) below.
The only important restriction is that both key and value must implement
the [`Copy`](https://doc.rust-lang.org/std/marker/trait.Copy.html) trait.
**WELCOME**:
Not all functions that you might expect to have in a map are implemented.
I will appreciate if you contribute by implementing these
[missing functions](https://github.com/yegor256/micromap/issues).
First, add this to `Cargo.toml`:
```toml
[dependencies]
micromap = "0.0.7"
```
Then, use it like a standard hash map... well, almost:
```rust
use micromap::Map;
let mut m : Map<u64, &str, 10> = Map::new(); // allocation on stack
m.insert(1, "foo");
m.insert(2, "bar");
assert_eq!(2, m.len());
```
Pay attention, here the map is created with an extra generic argument `10`. This is
the total size of the map, which is allocated on stack when `::new()` is called.
Unlike `HashMap`, the `Map` doesn't use heap at all. If more than ten keys will be
added to the map, it will panic.
Read [the API documentation](https://docs.rs/micromap/latest/micromap/). The struct
[`micromap::Map`](https://docs.rs/micromap/latest/micromap/struct.Map.html) is designed as closely similar to
[`std::collections::HashMap`](https://doc.rust-lang.org/std/collections/struct.HashMap.html) as possible.
## Benchmark
There is a summary of a simple benchmark, where we compared `micromap::Map` with
a few other Rust maps, changing the total capacity of the map (horizontal axis).
We applied the same interactions
([`benchmark.rs`](https://github.com/yegor256/micromap/blob/master/tests/benchmark.rs))
to them and measured how fast they performed. In the following table,
the numbers over 1.0 indicate performance gain,
while the numbers below 1.0 demonstrate performance loss.
| `hashbrown::HashMap` | 16.03 | 3.35 | 2.35 | 1.16 | 0.49 | 0.26 | 0.13 |
| `indexmap::IndexMap` | 14.75 | 6.03 | 4.16 | 2.20 | 1.14 | 0.58 | 0.27 |
| `linear_map::LinearMap` | 2.15 | 0.70 | 0.60 | 0.55 | 0.46 | 0.59 | 0.48 |
| `linked_hash_map::LinkedHashMap` | 26.87 | 7.52 | 5.16 | 3.20 | 1.44 | 0.73 | 0.33 |
| `litemap::LiteMap` | 5.00 | 1.43 | 1.18 | 0.84 | 0.46 | 0.29 | 0.18 |
| `micromap::Map` 👍 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 |
| `nohash_hasher::BuildNoHashHasher` | 11.90 | 3.60 | 2.72 | 0.94 | 0.46 | 0.25 | 0.12 |
| `rustc_hash::FxHashMap` | 12.01 | 3.30 | 2.29 | 1.31 | 0.48 | 0.26 | 0.12 |
| `std::collections::BTreeMap` | 22.11 | 4.78 | 3.40 | 2.40 | 1.24 | 0.60 | 0.36 |
| `std::collections::HashMap` | 18.11 | 5.53 | 4.17 | 2.10 | 1.09 | 0.56 | 0.27 |
| `tinymap::array_map::ArrayMap` | 2.07 | 2.27 | 2.12 | 2.24 | 2.30 | 2.28 | 2.07 |
The experiment was performed on 25-04-2023.
There were 1000000 repetition cycles.
The entire benchmark took 345s.
As you see, the highest performance gain was achieved for the maps that were smaller than ten keys.
For the maps of just a few keys, the gain was enormous.
## How to Contribute
First, install [Rust](https://www.rust-lang.org/tools/install) and then:
```bash
$ cargo test -vv
```
If everything goes well, fork repository, make changes, send us a [pull request](https://www.yegor256.com/2014/04/15/github-guidelines.html).
We will review your changes and apply them to the `master` branch shortly,
provided they don't violate our quality standards. To avoid frustration,
before sending us your pull request please run `cargo test` again. Also,
run `cargo fmt` and `cargo clippy`.