-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Fork
indexmap into ringmap, based on VecDeque
- Loading branch information
Showing
37 changed files
with
2,984 additions
and
2,372 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,59 +1,41 @@ | ||
| # indexmap | ||
| # ringmap | ||
|
|
||
| [](https://github.com/indexmap-rs/indexmap/actions) | ||
| [](https://crates.io/crates/indexmap) | ||
| [](https://docs.rs/indexmap) | ||
| [](https://img.shields.io/badge/rust-1.63%2B-orange.svg) | ||
| [](https://github.com/indexmap-rs/ringmap/actions) | ||
| [](https://crates.io/crates/ringmap) | ||
| [](https://docs.rs/ringmap) | ||
| [](https://img.shields.io/badge/rust-1.68%2B-orange.svg) | ||
|
|
||
| A pure-Rust hash table which preserves (in a limited sense) insertion order. | ||
| A pure-Rust hash table which preserves (in a limited sense) insertion order, | ||
| with efficient deque-like manipulation of both the front and back ends. | ||
|
|
||
| This crate implements compact map and set data-structures, | ||
| where the iteration order of the keys is independent from their hash or | ||
| value. It preserves insertion order (except after removals), and it | ||
| value. It preserves insertion order in most mutating operations, and it | ||
| allows lookup of entries by either hash table key or numerical index. | ||
|
|
||
| Note: this crate was originally released under the name `ordermap`, | ||
| but it was renamed to `indexmap` to better reflect its features. | ||
| The [`ordermap`](https://crates.io/crates/ordermap) crate now exists | ||
| as a wrapper over `indexmap` with stronger ordering properties. | ||
|
|
||
| # Background | ||
|
|
||
| This was inspired by Python 3.6's new dict implementation (which remembers | ||
| the insertion order and is fast to iterate, and is compact in memory). | ||
|
|
||
| Some of those features were translated to Rust, and some were not. The result | ||
| was indexmap, a hash table that has following properties: | ||
| This crate was forked from [`indexmap`](https://crates.io/crates/indexmap), | ||
| with the primary difference being a change from `Vec` to `VecDeque` for the | ||
| primary item storage. As a result, it has many of the same properties, as | ||
| well as a few new ones: | ||
|
|
||
| - Order is **independent of hash function** and hash values of keys. | ||
| - Fast to iterate. | ||
| - Indexed in compact space. | ||
| - Preserves insertion order **as long** as you don't call `.remove()`, | ||
| `.swap_remove()`, or other methods that explicitly change order. | ||
| The alternate `.shift_remove()` does preserve relative order. | ||
| - Efficient pushing and popping from both the front and back. | ||
| - Preserves insertion order **as long** as you don't call `.swap_remove_back()` | ||
| or other methods that explicitly change order. | ||
| - In `ringmap`, the regular `.remove()` **does** preserve insertion order, | ||
| equivalent to what `indexmap` calls `.shift_remove()`. | ||
| - Uses hashbrown for the inner table, just like Rust's libstd `HashMap` does. | ||
|
|
||
| ## Performance | ||
|
|
||
| `IndexMap` derives a couple of performance facts directly from how it is constructed, | ||
| which is roughly: | ||
|
|
||
| > A raw hash table of key-value indices, and a vector of key-value pairs. | ||
| - Iteration is very fast since it is on the dense key-values. | ||
| - Removal is fast since it moves memory areas only in the table, | ||
| and uses a single swap in the vector. | ||
| - Lookup is fast-ish because the initial 7-bit hash lookup uses SIMD, and indices are | ||
| densely stored. Lookup also is slow-ish since the actual key-value pairs are stored | ||
| separately. (Visible when cpu caches size is limiting.) | ||
|
|
||
| - In practice, `IndexMap` has been tested out as the hashmap in rustc in [PR45282] and | ||
| the performance was roughly on par across the whole workload. | ||
| - If you want the properties of `IndexMap`, or its strongest performance points | ||
| fits your workload, it might be the best hash table implementation. | ||
|
|
||
| [PR45282]: https://github.com/rust-lang/rust/pull/45282 | ||
| `ringmap` also follows [`ordermap`](https://crates.io/crates/ordermap) in using | ||
| its entry order for `PartialEq` and `Eq`, whereas `indexmap` considers the same | ||
| entries in *any* order to be equal for drop-in compatibility with `HashMap` | ||
| semantics. Using the order is faster, and also allows `ringmap` to implement | ||
| `PartialOrd`, `Ord`, and `Hash`. | ||
|
|
||
| # Recent Changes | ||
|
|
||
| See [RELEASES.md](https://github.com/indexmap-rs/indexmap/blob/master/RELEASES.md). | ||
| See [RELEASES.md](https://github.com/indexmap-rs/ringmap/blob/main/RELEASES.md). |
Oops, something went wrong.