smallmap 1.4.1

Small byte-sized generic key-value map type
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

# smallmap
A small table map using single byte key indecies. Designed for maps with tiny keys.

Pages are stored as 256 entry key-value arrays which are indexed by the byte key index. The key is compared for collision check and on collision the next page is checked or inserted if needed.
`smallmap` does not ever need to allocate more than 1 page for types which all invariants can be represented as unique bytes.

## Usage
The API is a similar subset to `HashMap`, containing the same `insert`, `get`, and `entry` functions:

``` rust
fn max_char(chars: &str) -> (char, usize)
{
    let mut map = Map::new();
    for x in chars.chars() {
		*map.entry(x).or_insert(0usize) += 1;	
    }

	map.into_iter().max_by_key(|&(_, v)| v).unwrap_or_default()
}
```

## Use cases
Designed for instances where you want a small map with relatively trivial keys (e.g. primitive type).
Performance can greately outpace hash-based by an order of magnitude or more in these cases.

### Maybe use if

* You have small keys
* Your map is not at risk of Denial of Service attacks.
* Your keys are not expected to have a lot of collisions when represented as `u8`.

### Don't use if

* You have complex keys
* Denial of service is a concern
* Your map will contain a large volume of entries
* Your keys may have a large number of collisions when represented as `u8`.


# Benchmarks
Some crude and basic benchmarks

## char

| Which           | ns/iter |
|-----------------|---------|
| `HashMap`       | 16      |
| `smallmap::Map` | 7       |


## Iterating a string's chars and counting each

| Which           | ns/iter (entry) | ns/iter (get/insert) |
|-----------------|-----------------|----------------------|
| `HashMap`       | 8,418           | 8,367                |
| `BTreeMap`      | 9,742           | 6,329                |
| `smallmap::Map` | 4,416           | 1,739                |

## u8
| Which           | ns/iter |
|-----------------|---------|
| `HashMap`       | 15      |
| `smallmap::Map` | 2       |

# License
MIT licensed