sparsey 0.13.3

Entity Component System based on sparse sets
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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174

use crate::entity::{Entity, Version};
use alloc::vec::Vec;
use core::{fmt, iter, mem};

/// Maps entities to dense indexes.
#[derive(Clone, Default)]
pub struct SparseVec {
    slots: Vec<Option<SparseVecSlot>>,
}

impl SparseVec {
    /// Creates a new sparse vec.
    #[inline]
    #[must_use]
    pub const fn new() -> Self {
        Self { slots: Vec::new() }
    }

    /// Returns the dense index mapped to `entity`, if any.
    #[inline]
    #[must_use]
    pub fn get(&self, entity: Entity) -> Option<u32> {
        self.slots
            .get(entity.sparse())?
            .filter(|slot| slot.version == entity.version)
            .map(|slot| slot.index)
    }

    /// Returns whether the sparse vec contains `entity`.
    #[inline]
    #[must_use]
    pub fn contains(&self, entity: Entity) -> bool {
        self.slots
            .get(entity.sparse())
            .and_then(Option::as_ref)
            .is_some_and(|slot| slot.version == entity.version)
    }

    /// Removes `entity` from the sparse vec.
    ///
    /// Returns the dense index mapped to `entity`, if any.
    #[inline]
    pub fn remove(&mut self, entity: Entity) -> Option<u32> {
        self.slots
            .get_mut(entity.sparse())?
            .take_if(|slot| slot.version == entity.version)
            .map(|slot| slot.index)
    }

    /// Returns the dense index at the given sparse index, if any.
    #[inline]
    #[must_use]
    pub fn get_sparse(&self, sparse: usize) -> Option<u32> {
        self.slots.get(sparse)?.map(|slot| slot.index)
    }

    /// Returns the dense index at the given sparse index without checking if it
    /// valid.
    #[inline]
    #[must_use]
    pub unsafe fn get_sparse_unchecked(&self, sparse: usize) -> usize {
        self.slots.get_unchecked(sparse).unwrap_unchecked().dense()
    }

    /// Returns whether the sparse vec contains the given sparse index.
    #[inline]
    #[must_use]
    pub fn contains_sparse(&self, sparse: usize) -> bool {
        self.slots.get(sparse).and_then(Option::as_ref).is_some()
    }

    /// Removes the dense entity at the given sparse index.
    ///
    /// Returns the removed dense entity, if any.
    #[inline]
    pub fn remove_sparse(&mut self, sparse: usize) -> Option<SparseVecSlot> {
        self.slots.get_mut(sparse)?.take()
    }

    /// Returns the entity slot at the given dense index without checking if it
    /// is valid.
    #[inline]
    pub unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut Option<SparseVecSlot> {
        self.slots.get_unchecked_mut(index)
    }

    /// Returns or allocates the entity slot at the given dense index.
    #[inline]
    pub fn get_mut_or_allocate_at(&mut self, index: usize) -> &mut Option<SparseVecSlot> {
        if index >= self.slots.len() {
            self.extend_to_index(index);
        }

        unsafe { self.slots.get_unchecked_mut(index) }
    }

    /// Swaps the entities at the given dense indexes without checking their
    /// validity.
    #[inline]
    pub unsafe fn swap_nonoverlapping(&mut self, a: usize, b: usize) {
        debug_assert!(a < self.slots.len());
        debug_assert!(b < self.slots.len());
        debug_assert_ne!(a, b);

        let index_a = &mut (*self.slots.as_mut_ptr().add(a))
            .as_mut()
            .unwrap_unchecked()
            .index;

        let index_b = &mut (*self.slots.as_mut_ptr().add(b))
            .as_mut()
            .unwrap_unchecked()
            .index;

        mem::swap(index_a, index_b);
    }

    /// Removes all entities from the storage.
    #[inline]
    pub fn clear(&mut self) {
        self.slots.clear();
    }

    #[cold]
    fn extend_to_index(&mut self, index: usize) {
        let extra_len = index.checked_next_power_of_two().unwrap_or(index) - self.slots.len() + 1;
        self.slots.extend(iter::repeat_n(None, extra_len));
    }
}

impl fmt::Debug for SparseVec {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let entries = self
            .slots
            .iter()
            .enumerate()
            .filter_map(|(i, &dense_entity)| {
                let dense_entity = dense_entity?;
                let entity = Entity::new(i as u32, dense_entity.version);
                Some((entity, dense_entity.index))
            });

        f.debug_map().entries(entries).finish()
    }
}

/// Versioned dense index.
#[derive(Clone, Copy)]
#[cfg_attr(target_pointer_width = "64", repr(align(8)))]
pub struct SparseVecSlot {
    /// The index of the slot.
    pub index: u32,

    /// The version of the slot.
    pub version: Version,
}

impl SparseVecSlot {
    /// Returns the `index` extended to a [`usize`].
    #[inline]
    #[must_use]
    pub fn dense(&self) -> usize {
        self.index as usize
    }
}

impl fmt::Debug for SparseVecSlot {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct(stringify!(SparseVecSlot))
            .field("index", &self.index)
            .field("version", &self.version.0)
            .finish()
    }
}