gen_map 0.3.0

A generational map with configurable key size, key layout and storage.
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
74
75
76

use crate::config::{DefaultKeyConfig, KeyConfig};
use crate::parity::Odd;
use core::cmp::Ordering;
use core::fmt;

/// A key to a value in a [`GenMap`](crate::GenMap), returned by `insert`.
/// The key config `K` decides how the key stores its index and generation.
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct Key<K: KeyConfig = DefaultKeyConfig> {
    repr: K,
}

impl<K: KeyConfig> Key<K> {
    /// The index of the slot this key refers to.
    #[inline]
    pub fn idx(&self) -> K::Idx {
        self.repr.idx()
    }

    /// The generation the key's slot had when the key was handed out. The
    /// key matches the slot only while the slot still has this generation.
    #[inline]
    pub fn generation(&self) -> Odd<K::Gen> {
        self.repr.generation()
    }

    /// Returns `true` if the key's generation is the largest one its key config
    /// can hold. The slot's generation cannot go up past that one, so removing
    /// the key's value either wraps the slot's generation back to zero or
    /// retires the slot, depending on
    /// [`WRAP_ON_OVERFLOW`](crate::GenMapConfig::WRAP_ON_OVERFLOW).
    #[inline]
    pub fn is_max_generation(&self) -> bool {
        self.generation() == K::max_generation()
    }

    /// Builds a key from a value of its key config, which
    /// [`KeyConfig::pack`] makes from an index and a generation.
    #[inline]
    pub fn from_repr(repr: K) -> Self {
        Self { repr }
    }

    /// The value of the key config that holds this key's index and
    /// generation.
    #[inline]
    pub fn repr(&self) -> K {
        self.repr
    }
}

impl<K: KeyConfig> PartialOrd for Key<K> {
    #[inline]
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

/// Keys are ordered by index, then by generation, whatever the key config.
impl<K: KeyConfig> Ord for Key<K> {
    #[inline]
    fn cmp(&self, other: &Self) -> Ordering {
        self.idx()
            .cmp(&other.idx())
            .then(self.generation().cmp(&other.generation()))
    }
}

impl<K: KeyConfig> fmt::Debug for Key<K> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Key")
            .field("idx", &self.idx())
            .field("generation", &self.generation().get())
            .finish()
    }
}