Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yegor256/micromap

📈 The fastest (for very small maps!) alternative of Rust HashMap, which doesn't use hashing and doesn't use heap (aka "linear map")
https://github.com/yegor256/micromap

data-structures fast-map-matching hashmap linear-maps performance rust

Last synced: 5 days ago
JSON representation

📈 The fastest (for very small maps!) alternative of Rust HashMap, which doesn't use hashing and doesn't use heap (aka "linear map")

Awesome Lists containing this project

README 

        
# The Fastest Linear Map in Rust



[![cargo](https://github.com/yegor256/micromap/actions/workflows/cargo.yml/badge.svg)](https://github.com/yegor256/micromap/actions/workflows/cargo.yml)

[![crates.io](https://img.shields.io/crates/v/micromap.svg)](https://crates.io/crates/micromap)

[![codecov](https://codecov.io/gh/yegor256/micromap/branch/master/graph/badge.svg)](https://codecov.io/gh/yegor256/micromap)

[![Hits-of-Code](https://hitsofcode.com/github/yegor256/micromap)](https://hitsofcode.com/view/github/yegor256/micromap)

[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/micromap/blob/master/LICENSE.txt)

[![docs.rs](https://img.shields.io/docsrs/micromap)](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.



**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.15"

```



Then, use it like a standard hash map... well, almost:



```rust

use micromap::Map;

let mut m : Map = 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`][std] 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`][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.



| | 2 | 4 | 8 | 16 | 32 | 64 | 128 |

| --- | --: | --: | --: | --: | --: | --: | --: |

| `hashbrown::HashMap` | 21.21 | 11.82 | 6.48 | 3.88 | 1.20 | 0.59 | 0.28 |

| `heapless::LinearMap` | 1.19 | 1.51 | 1.22 | 1.40 | 0.83 | 0.98 | 0.87 |

| `indexmap::IndexMap` | 13.03 | 12.09 | 7.49 | 4.82 | 1.68 | 0.89 | 0.45 |

| `linear_map::LinearMap` | 1.69 | 1.56 | 1.15 | 1.11 | 0.75 | 1.18 | 0.83 |

| `linked_hash_map::LinkedHashMap` | 26.05 | 21.61 | 12.48 | 7.85 | 2.69 | 1.41 | 0.76 |

| `litemap::LiteMap` | 1.68 | 2.30 | 6.61 | 4.58 | 1.69 | 0.88 | 0.56 |

| `micromap::Map` 👍 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 |

| `nohash_hasher::BuildNoHashHasher` | 20.78 | 12.19 | 8.44 | 3.38 | 1.18 | 0.65 | 0.32 |

| `rustc_hash::FxHashMap` | 20.95 | 12.19 | 6.60 | 4.10 | 1.03 | 0.54 | 0.28 |

| `std::collections::BTreeMap` | 21.02 | 8.87 | 5.34 | 4.64 | 2.18 | 1.17 | 0.68 |

| `std::collections::HashMap` | 20.86 | 14.55 | 8.84 | 5.37 | 1.91 | 1.10 | 0.51 |

| `tinymap::array_map::ArrayMap` | 1.66 | 4.65 | 4.60 | 5.20 | 3.54 | 4.34 | 4.15 |



The experiment [was performed][action] on 05-11-2024.

There were 1000000 repetition cycles.

The entire benchmark took 197s.

Uname: 'Linux'.



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`.



Also, before you start making changes, run benchmarks:



```bash

rustup run nightly cargo bench

```



Then, after the changes you make, run it again. Compare the results.

If your changes

degrade performance, think twice before submitting a pull request.



[std]: https://doc.rust-lang.org/std/collections/struct.HashMap.html

[rs]: https://github.com/yegor256/micromap/blob/master/tests/benchmark.rs

[action]: https://github.com/yegor256/micromap/actions/workflows/benchmark.yml