thunderdome/lib.rs
1/*!
2[](https://github.com/LPGhatguy/thunderdome/actions)
3[](https://crates.io/crates/thunderdome)
4[](https://docs.rs/thunderdome)
5
6Thunderdome is a ~~gladitorial~~ generational arena inspired by
7[generational-arena](https://crates.io/crates/generational-arena),
8[slotmap](https://crates.io/crates/slotmap), and
9[slab](https://crates.io/crates/slab). It provides constant time insertion,
10lookup, and removal via small (8 byte) keys returned from [`Arena`].
11
12Thunderdome's key type, [`Index`], is still 8 bytes when put inside of an
13`Option<T>` thanks to Rust's `NonZero*` types.
14
15# Basic Examples
16
17```rust
18# use thunderdome::{Arena, Index};
19let mut arena = Arena::new();
20
21let foo = arena.insert("Foo");
22let bar = arena.insert("Bar");
23
24assert_eq!(arena[foo], "Foo");
25assert_eq!(arena[bar], "Bar");
26
27arena[bar] = "Replaced";
28assert_eq!(arena[bar], "Replaced");
29
30let foo_value = arena.remove(foo);
31assert_eq!(foo_value, Some("Foo"));
32
33// The slot previously used by foo will be reused for baz
34let baz = arena.insert("Baz");
35assert_eq!(arena[baz], "Baz");
36
37// foo is no longer a valid key
38assert_eq!(arena.get(foo), None);
39```
40
41# Comparison With Similar Crates
42
43| Feature | Thunderdome | generational-arena | slotmap | slab |
44|------------------------------|-------------|--------------------|---------|------|
45| Generational Indices¹ | Yes | Yes | Yes | No |
46| `size_of::<Index>()` | 8 | 16 | 8 | 8 |
47| `size_of::<Option<Index>>()` | 8 | 24 | 8 | 16 |
48| Max Elements | 2³² | 2⁶⁴ | 2³² | 2⁶⁴ |
49| Non-`Copy` Values | Yes | Yes | Yes | Yes |
50| `no_std` Support | Yes | Yes | Yes | No |
51| Serde Support | No | Yes | Yes | No |
52
53* Sizes calculated on rustc `1.44.0-x86_64-pc-windows-msvc`
54* See [the Thunderdome comparison
55 Cargo.toml](https://github.com/LPGhatguy/thunderdome/blob/main/comparison/Cargo.toml)
56 for versions of each library tested.
57
581. Generational indices help solve the [ABA
59 Problem](https://en.wikipedia.org/wiki/ABA_problem), which can cause dangling
60 keys to mistakenly access newly-inserted data.
61
62# Minimum Supported Rust Version (MSRV)
63
64Thunderdome supports Rust 1.47.0 and newer. Until Thunderdome reaches 1.0,
65changes to the MSRV will require major version bumps. After 1.0, MSRV changes
66will only require minor version bumps, but will need significant justification.
67
68# Crate Features
69* `std` (default): Use the standard library. Disable to make this crate `no-std` compatible.
70*/
71
72#![forbid(missing_docs)]
73// This crate is sensitive to integer overflow and wrapping behavior. As such,
74// we should usually use methods like `checked_add` and `checked_sub` instead
75// of the `Add` or `Sub` operators.
76#![deny(clippy::integer_arithmetic)]
77// TODO: Deny clippy::std_instead_of_core, clippy::std_instead_of_alloc and
78// clippy::alloc_instead_of_core when released.
79#![cfg_attr(not(feature = "std"), no_std)]
80
81#[cfg(not(feature = "std"))]
82extern crate alloc;
83
84mod arena;
85mod free_pointer;
86mod generation;
87pub mod iter;
88
89pub use crate::arena::{Arena, Index};