slotmap for Rust: Stable Keys for Mutable Collections

Why slotmap Exists for Rust Collections

slotmap addresses a specific ownership problem in Rust: a collection may need stable references to movable values even when those values do not belong to a single conventional owner. Inserting a value returns a persistent key, and that key can later identify the value or confirm its removal. This avoids requiring callers to track changing indexes after other entries are deleted.

The project presents three primary containers: `SlotMap`, `HopSlotMap`, and `DenseSlotMap`. It also supplies `SecondaryMap` and `SparseSecondaryMap` for associating additional data with keys created by one of the primary maps. The intended use is a collection of objects without an obvious single owner, such as game entities or graph nodes.

The README states that insertion, deletion, and access take O(1) time with low overhead. That makes the design relevant when an application frequently adds, removes, and looks up related objects. It does not make every operation involving stored data O(1). Iterating a map, copying the values it contains, or performing expensive work on each value can still introduce costs determined by the surrounding application.

slotmap is a container library rather than a framework. It does not prescribe an entity component system, renderer, graph implementation, serialization policy, or ownership model for the values placed inside it. That narrower scope makes it usable in systems programming, game code, compilers, editors, and other Rust applications, provided their access pattern matches the operations described in the documentation.

SlotMap Keys and Reused Storage

The central mechanism visible in the README is the relationship between insertion and keys. A caller creates a `SlotMap`, inserts a value, and receives a generated key. That key remains the access token for the value while it is present. A later insertion returns a separate key, which lets the caller distinguish multiple entries without relying on their current position in iteration order.

The README also demonstrates slot reuse after deletion. In its example, the key returned for `"bar"` is removed. A subsequent insertion reuses the space associated with that entry. The old key does not become valid again, as shown by `contains_key(bar)` returning `false`. This is an important distinction: storage is reused, while the deleted key remains invalid according to the example.

The README does not explain the internal bit layout, generation counters, hashing details, or memory layout of the three primary containers. It also does not document whether retained keys can distinguish reused slots through any public numeric comparison beyond ordinary equality. The safest adoption criterion is therefore the documented public contract: use returned keys for access, check membership when validity matters, and do not treat an invalid key as a handle to a newly inserted value.

The primary containers have separate names but no comparative complexity table in the available documentation. The project points readers to docs.rs for their detailed APIs. For a choice among `SlotMap`, `HopSlotMap`, and `DenseSlotMap`, that external API documentation is the first place to verify the exact differences rather than inferring them from their names.

Secondary and SparseSecondaryMap Associations

`SecondaryMap` adds an association from a slot map key to another value. The caller supplies the existing key explicitly. In the README example, a `SecondaryMap` associates the key for `"foo"` with `"noun"` and the key for `"reuse"` with `"verb"`. Iterating the primary `SlotMap` then pairs each live value with data looked up through its key.

This arrangement separates one kind of record from another without requiring a composite public identifier. The key returned by the primary map acts as the common reference. That can suit code where related metadata has a different lifecycle or belongs to a different module, although the README does not specify automatic cleanup between the two maps.

The missing lifecycle detail matters. The example inserts entries into both maps, but it does not remove the secondary association when `sm.remove(bar)` is called. Since that removed primary key is not the one used for the secondary values, the example does not establish what happens when a secondary entry points directly at a key that is later removed. The documentation should be checked before relying on any automatic consistency behavior.

`SparseSecondaryMap` offers another named variant, but the README supplies no example or explanation of its storage differences. Its selection criteria also need to come from the full API documentation. For straightforward keyed associations covered by the example, `SecondaryMap` is the documented starting point.

Installing slotmap and Running the First Use

The README instructs users to add `slotmap` to `Cargo.toml`. The available repository metadata identifies the package as version `1.1.1`, while the README dependency example uses the broader requirement `slotmap = "1.0"`. There is also a version mismatch to resolve before adoption: the README says the minimum required stable Rust version is 1.58, but `Cargo.toml` declares `rust-version = "1.80.0"`. For current repository builds, the manifest is the more specific instruction to verify.

Add the dependency shown in the README:

[dependencies]
slotmap = "1.0"

The default feature set includes `std`. An optional `serde` dependency is declared, and an `unstable` feature is also present. The README does not give feature-specific setup commands, so it would be unsafe to invent feature syntax or claim which APIs are exposed by `unstable`.

A first program can follow the documented insertion, lookup, deletion, and reuse sequence:

use slotmap::{SlotMap, SecondaryMap};

let mut sm = SlotMap::new();
let foo = sm.insert("foo");
let bar = sm.insert("bar");
assert_eq!(sm[foo], "foo");
assert_eq!(sm[bar], "bar");

sm.remove(bar);
let reuse = sm.insert("reuse");
assert_eq!(sm.contains_key(bar), false);

let mut sec = SecondaryMap::new();
sec.insert(foo, "noun");
sec.insert(reuse, "verb");

for (key, val) in sm {
    println!("{} is a {}", val, sec[key]);
}

The assertions demonstrate the first invariant: keys returned by insertion access their corresponding live values, while the key for the removed value remains invalid. The final loop is expected to print the two remaining primary values together with their secondary associations, although the README does not provide captured output.

Where SlotMap Is the Wrong Rust Data Structure

slotmap is a poor fit when the caller naturally needs a stable collection-level reference rather than a key lookup. The README describes stable, safe references through returned keys, but it does not document an API for borrowing an entire map or obtaining a container-owned reference that can coexist with later mutation. Code whose central requirement is a long-lived Rust reference across container mutations needs its borrowing design checked against the full API before adopting this library.

It is also a poor fit for small collections whose data naturally belongs in an `Option`, struct field, ordinary vector, or map with a meaningful domain identifier. Those types can express ownership and lookup directly without introducing generated keys. slotmap becomes more relevant when many related values require uniform insertion and removal while callers identify them independently of iteration position.

The constant-time claims should not be stretched into a general performance guarantee. The repository includes `examples/doubly_linked_list.rs` and `examples/rand_meld_heap.rs`, but the README does not explain their APIs or state measured results. Those examples show that the library is used for additional data-structure work, not that it improves every such workload. Storage reuse is explicitly demonstrated, but no memory footprint, cache result, or benchmark is documented.

A real alternative is an application-managed identifier map, such as a normal Rust map keyed by an application-defined ID. That approach gives the caller meaningful IDs and makes serialization or persistence boundaries more explicit. slotmap instead generates its keys and documents slot reuse, O(1) core operations, and direct integration between primary and secondary maps. The practical difference is ownership of identity: the application owns identity in an ordinary ID map, while slotmap manages generated keys as part of the container operation.

Maintenance, Compatibility, and Upgrade Boundaries

The repository is not archived, and its last push was on 2026-09-04. That is recent enough to avoid describing it as abandoned, but it does not by itself establish a release cadence or compatibility process. GitHub has no releases for this repository, so there is no published GitHub release history to use as an upgrade signal.

The project is released under the Zlib license. The README describes it as permissive, OSI and FSF approved, and GPL compatible. License compatibility should still be checked against the complete `LICENSE` file and the consuming application's obligations. This is a technical compatibility point, not legal advice.

There are two concrete upgrade checks. First, the available files disagree about the minimum stable Rust version: the README states 1.58, while `Cargo.toml` declares `rust-version = "1.80.0"`. A build attempting to use Rust older than 1.80 should follow the manifest and compiler behavior rather than relying on the older README sentence. Second, `RELEASES.md` exists in the repository, but its contents are not available here, so the migration notes for a specific upgrade cannot be described.

The edition is 2018, and the default feature is `std`. The optional dependencies and features are declared in `Cargo.toml`, but the README does not document whether serialized representations remain compatible across releases. Projects that persist keys or slot map contents should verify `serde` support and format stability from the docs.rs documentation before treating serialized state as a durable format.

Editorial conclusion

Adopt slotmap when Rust code needs generated, stable keys for frequently inserted and removed values, especially entity or node collections. Do not choose it when application-defined IDs or ordinary ownership structures are a better fit. Verify the container variant, secondary-map cleanup behavior, Rust 1.80.0 requirement, and serialized-key compatibility before migrating existing data.

Frequently asked questions

Official sources

1. Issues
2. License: Zlib
3. orlp/slotmap on GitHub
4. README