# `bumpish`
[](https://crates.io/crates/bumpish)
[](https://docs.rs/bumpish/latest/bumpish/)
[](https://crates.io/crates/bumpish)
[](https://opensource.org/licenses/MPL-2.0)
A set of collections that use bump allocations under the hood. For now there are
three collections in this crate:
- [`BumpMap`] — hash map.
- [`BumpSet`] — hash set.
- [`BumpStk`] — stack (growing backward).
[`BumpMap`]: docs/map.md
[`BumpSet`]: docs/set.md
[`BumpStk`]: docs/stk.md
## What is bump allocation?
Bump allocation is another way to allocate memory for data types collecting
elements, like vectors and lists. If vectors contain elements in a single
continuous chunk of memory, and lists allocate a little chunk for every element,
collections, that use bump allocation, are a cross between these two approaches.
They allocate relatively big chunks of memory where put new elements
sequentially.
- Vector collection
```py
╭───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬─────╮
│ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 │ ... │
╰───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴─────╯
```
- List collection
```py
╭───╮ ╭───╮ ╭───╮ ╭───╮ ╭───╮ ╭───╮ ╭───╮ ╭───╮ ╭───╮ ╭───╮ ╭───╮
│ 0 │↔│ 1 │↔│ 2 │↔│ 3 │↔│ 4 │↔│ 5 │↔│ 6 │↔│ 7 │↔│ 8 │↔│ 9 │↔│...│
╰───╯ ╰───╯ ╰───╯ ╰───╯ ╰───╯ ╰───╯ ╰───╯ ╰───╯ ╰───╯ ╰───╯ ╰───╯
```
- Bump collection
```py
╭───┬───╮ ╭───┬───┬───┬───╮ ╭───┬───┬───┬───┬─────╮
│ 0 │ 1 │↔│ 2 │ 3 │ 4 │ 5 │↔│ 6 │ 7 │ 8 │ 9 │ ... │
╰───┴───╯ ╰───┴───┴───┴───╯ ╰───┴───┴───┴───┴─────╯
```
In contrast to vectors, bump collections don't move elements from an old memory
chunk to a new one when the chunk fills up. Instead, leave the old one
untouched, and continue pushing new elements into the new chunk.
## When should I use `bimpish` collections instead of [`bumpalo`]?
If you want elements' [`Drop`] implementations to be invoked during
deallocation.
[`bumpalo`]: https://crates.io/crates/bumpalo
[`Drop`]: https://doc.rust-lang.org/std/ops/trait.Drop.html
## When should I use `bumpish` collections instead of standard collections?
Collections from the standard library can grow only by a mutable reference to
themeselves. The reason is that they need to reallocate memory when the chunk
fills up, which invalidates all existing references. In contrast, bump
collections do not invalidate references, because they just push new elements
onto the end of a new chunk. So adding new elements are done using a shared
reference to bump collections.
So, if you have a structure that only grows, and you have to use a [`RefCell`]
wrapper around it to get a mutable reference to it, `bumpish` collections can
improve ergonomics of your code.
[`RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.html