bumpish 0.4.1

A set of collections using bump allocations
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

# `BumpMap`

[`BumpMap`] is a hash map implementation that uses a bump allocation to hold its
keys and values. [`BumpMap`]'s API is a bit different to the standard [`HashMap`], but
is not the same. So, read the documentation carefully.

[`BumpMap`]: crate::map::BumpMap
[`HashMap`]: https://doc.rust-lang.org/std/collections/hash_map/struct.HashMap.html

## Populating

In order to populate a new map, use different [`From`] trait implementations.
They repeat the same pattern as [`HashMap`]:

```rust
use bumpish::BumpMap;

let map = BumpMap::from([("a", 1), ("b", 2), ("c", 3)]);
```

Also, as expected, [`BumpMap`] allows to add new elements by inserting them to
the map with `insert`-methods. But pay attention to the fact that behavior of
these methods is different from [`HashMap`]'s methods:

```rust
use bumpish::BumpMap;

let mut map = BumpMap::new();

assert_eq!(map.insert("a", 1), Some(&1)); // insert and return a ref to the new value
assert_eq!(map.insert("a", 2), None);     // or `None` if the key is already in

assert_eq!(map.replace("a", 2), Some(1)); // replace and return the old value
assert_eq!(map.replace("b", 3), None);    // insert if the key is not present
```

Note, that, in contrast to [`HashMap`], we insert new elements using shared
`self` reference (more about that read in the [Allocation](#allocation) part).

[`From`]: https://doc.rust-lang.org/std/convert/trait.From.html

## Removing elements

Removing element is not supported yet.

## Iteration

Pushing new elements by immutable reference allows to do that during iteration.
To avoid infinite loop, iteration runs over elements that have already existed
at the moment of creating the iterator.

```rust
use bumpish::BumpMap;

let map = BumpMap::from([(1, 2), (3, 4)]);

for (k, v) in &map {
    assert_ne!(map.insert(*k * 2,  v * 3), None);
}
assert_eq!(map.len(), 4);
assert_eq!(map.keys().copied().collect::<Vec<_>>(), [1, 3, 2, 6]);
assert_eq!(map.values().copied().collect::<Vec<_>>(), [2, 4, 6, 12]);
```

# Inner structure

[`BumpMap`] uses [`BumpVec`] under the hood to store key-value pairs. Read more
about [`BumpVec`] allocation in its documentation. Also it uses [`HashTable`]
from [hashbrown] crate to store hashes.

[`BumpVec`]: crate::vec::BumpVec
[`HashTable`]: https://docs.rs/hashbrown/latest/hashbrown/struct.HashTable.html
[hashbrown]: https://crates.io/crates/hashbrown