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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
#[cfg(not(feature = "std"))]
extern crate alloc;

#[cfg(feature = "std")]
extern crate core;

use core::{
    borrow::Borrow,
    cell::{
        RefCell,
        RefMut,
    },
    mem,
};

#[cfg(feature = "ahash")]
use ahash::HashMapExt;

use crate::Arena;

#[cfg(feature = "ahash")]
pub type KeyMap<K, V> = ahash::HashMap<K, V>;
#[cfg(all(feature = "std", not(feature = "ahash")))]
pub type KeyMap<K, V> = std::collections::HashMap<K, V>;
#[cfg(all(not(feature = "std"), not(feature = "ahash")))]
pub type KeyMap<K, V> = alloc::collections::BTreeMap<K, V>;

#[cfg(feature = "ahash")]
pub trait Key = core::cmp::Eq + core::hash::Hash;
#[cfg(all(feature = "std", not(feature = "ahash")))]
pub trait Key = core::cmp::Eq + core::hash::Hash;
#[cfg(all(not(feature = "std"), not(feature = "ahash")))]
pub trait Key = core::cmp::Ord;

#[cfg(any(feature = "std", feature = "ahash"))]
pub type KeyMapIter<'a, K, V> = std::collections::hash_map::Iter<'a, K, V>;
#[cfg(all(not(feature = "std"), not(feature = "ahash")))]
pub type KeyMapIter<'a, K, V> = alloc::collections::btree_map::Iter<'a, K, V>;

/// Iterator over mutable elements in a [`KeyedArena`].
pub struct IterMut<'a, K, T> {
    // Store the mutable reference to the entries map, so that we enforce that it is still being
    // used. We extended the lifetime of the iterator so that we could store it here.
    #[allow(dead_code)]
    entries: RefMut<'a, KeyMap<K, *mut T>>,
    iter: KeyMapIter<'a, K, *mut T>,
}

impl<'a, K, T> Iterator for IterMut<'a, K, T> {
    type Item = (&'a K, &'a mut T);

    fn next(&mut self) -> Option<Self::Item> {
        self.iter.next().map(|(k, v)| unsafe { (k, &mut **v) })
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.iter.size_hint()
    }
}

/// The same as [`Arena<T>`], but each inserted value is internally mapped to a custom key for
/// retrieving the value later.
///
/// Similar to [`crate::Registry`], except a [`KeyMap`] is used internally, which requires key
/// hashing or ordering. Hashing is used by default. In `no_std` builds, ordering is used.
pub struct KeyedArena<K, T> {
    arena: Arena<T>,
    entries: RefCell<KeyMap<K, *mut T>>,
}

impl<K, T> KeyedArena<K, T>
where
    K: Key,
{
    /// Creates a new keyed arena.
    pub fn new() -> Self {
        Self {
            arena: Arena::new(),
            entries: RefCell::new(KeyMap::new()),
        }
    }

    /// Creates a new keyed arena with the given capacity.
    #[cfg(any(feature = "std", feature = "ahash"))]
    pub fn with_capacity(size: usize) -> Self {
        Self {
            arena: Arena::with_capacity(size),
            entries: RefCell::new(KeyMap::with_capacity(size)),
        }
    }

    /// Returns the number of elements owned by the arena.
    pub fn len(&self) -> usize {
        self.arena.len()
    }

    /// Inserts a new value in the arena, returning a mutable reference to that vaue.
    ///
    /// Returns [`None`] if a value already exists for `key`.
    pub fn insert(&self, key: K, value: T) -> Option<&mut T> {
        let mut entries = self.entries.borrow_mut();
        if entries.contains_key(&key) {
            return None;
        }
        let data = self.arena.alloc(value);
        entries.insert(key, data);
        Some(data)
    }

    /// Ensures there is enough continuous space for at least `additional` values.
    #[cfg(any(feature = "std", feature = "ahash"))]
    pub fn reserve(&self, additional: usize) {
        self.arena.reserve(additional);
        self.entries.borrow_mut().reserve(additional)
    }

    /// Returns an iterator that provides mutable access to all elements in the arena.
    ///
    /// There is no guaranteed order of entries.
    ///
    /// [`KeyedArena`]s only allow mutable iteration because the entire arena must be borrowed for
    /// the duration of the iteration. The mutable borrow to call this method allows Rust's
    /// borrow checker to enforce this rule.
    pub fn iter_mut(&mut self) -> IterMut<K, T> {
        let entries = self.entries.borrow_mut();
        let iter = entries.iter();
        let iter = unsafe { mem::transmute(iter) };
        IterMut { entries, iter }
    }

    /// Returns an iterator over all keys in the arena.
    pub fn keys(&mut self) -> impl Iterator<Item = &K> {
        self.iter_mut().map(|(k, _)| k)
    }

    /// Returns an iterator over mutable references to all elements in the arena.
    pub fn values_mut(&mut self) -> impl Iterator<Item = &mut T> {
        self.iter_mut().map(|(_, v)| v)
    }

    /// Returns a mutable reference to a value previously inserted into the arena.
    pub fn get_mut<R>(&self, key: &R) -> Option<&mut T>
    where
        K: Borrow<R>,
        R: Key + ?Sized,
    {
        self.entries
            .borrow()
            .get(key)
            .cloned()
            .map(|r| unsafe { &mut *r })
    }

    /// Returns a reference to a value previously inserted into the arena.
    pub fn get<R>(&self, key: &R) -> Option<&T>
    where
        K: Borrow<R>,
        R: Key + ?Sized,
    {
        self.entries
            .borrow()
            .get(key)
            .cloned()
            .map(|r| unsafe { &*r })
    }

    /// Checks if the arena contains a value for the given `key`.
    pub fn contains_key<R>(&self, key: &R) -> bool
    where
        K: Borrow<R>,
        R: Key + ?Sized,
    {
        self.entries.borrow().contains_key(key)
    }
}

impl<K, V> FromIterator<(K, V)> for KeyedArena<K, V>
where
    K: Key,
{
    fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> Self {
        let iter = iter.into_iter();
        let arena = Self::new();
        for (key, value) in iter {
            arena.insert(key, value);
        }
        arena
    }
}

#[cfg(test)]
mod keyed_arena_test {
    #[cfg(not(feature = "std"))]
    extern crate alloc;

    #[cfg(not(feature = "std"))]
    use alloc::{
        borrow::ToOwned,
        collections::BTreeSet,
        string::String,
    };
    use core::cell::Cell;
    #[cfg(feature = "std")]
    use std::collections::BTreeSet;

    use crate::KeyedArena;

    // A shared counter for how many times a value is deallocated.
    struct DropCounter<'c>(&'c Cell<u32>);

    impl<'c> Drop for DropCounter<'c> {
        fn drop(&mut self) {
            self.0.set(self.0.get() + 1);
        }
    }

    // A node type, like one used in a list, tree, or graph data structure.
    //
    // Helps us verify that arena-allocated values can refer to each other.
    struct Node<'d, T> {
        parent: Option<String>,
        value: T,
        #[allow(dead_code)]
        drop_counter: DropCounter<'d>,
    }

    impl<'a, 'd, T> Node<'d, T> {
        pub fn new(parent: Option<String>, value: T, drop_counter: DropCounter<'d>) -> Self {
            Self {
                parent,
                value,
                drop_counter,
            }
        }
    }

    #[test]
    #[allow(dropping_references)]
    fn allocates_and_owns_values() {
        let drop_counter = Cell::new(0);
        {
            let arena: KeyedArena<String, Node<'_, i32>> = KeyedArena::new();

            // Allocate a chain of nodes that refer to each other.
            let node = arena.insert(
                "node1".to_owned(),
                Node::new(None, 1, DropCounter(&drop_counter)),
            );
            assert!(node.is_some());
            assert_eq!(arena.len(), 1);
            let node = arena.insert(
                "node2".to_owned(),
                Node::new(Some("node1".to_owned()), 2, DropCounter(&drop_counter)),
            );
            assert!(node.is_some());
            assert_eq!(arena.len(), 2);
            let node = arena.insert(
                "node3".to_owned(),
                Node::new(Some("node2".to_owned()), 3, DropCounter(&drop_counter)),
            );
            assert!(node.is_some());
            assert_eq!(arena.len(), 3);
            let node = arena.insert(
                "node4".to_owned(),
                Node::new(Some("node3".to_owned()), 4, DropCounter(&drop_counter)),
            );
            assert!(node.is_some());
            assert_eq!(arena.len(), 4);
            let node = arena.insert(
                "node1".to_owned(),
                Node::new(None, 5, DropCounter(&drop_counter)),
            );
            assert!(node.is_none());
            assert_eq!(arena.len(), 4);

            let mut node = arena.get("node4").unwrap();
            assert_eq!(node.value, 4);
            node = arena.get(node.parent.as_ref().unwrap()).unwrap();
            assert_eq!(node.value, 3);
            node = arena.get(node.parent.as_ref().unwrap()).unwrap();
            assert_eq!(node.value, 2);
            node = arena.get(node.parent.as_ref().unwrap()).unwrap();
            assert_eq!(node.value, 1);
            assert_eq!(node.parent, None);

            // We dropped a value from the failed insertion above.
            assert_eq!(drop_counter.get(), 1);
        }
        // All inserted values deallocated at the same time.
        assert_eq!(drop_counter.get(), 5);
    }

    #[test]
    fn iter_mut_itereates_all_values() {
        #[derive(Debug, PartialEq, Eq)]
        struct NoCopy(usize);

        let mut arena = KeyedArena::new();
        for i in 0..10 {
            arena.insert(i, NoCopy(i));
        }
        assert_eq!(
            arena.keys().cloned().collect::<BTreeSet<_>>(),
            (0..10).collect::<BTreeSet<_>>()
        );
    }

    #[test]
    fn iter_mut_allows_mutable_access() {
        let mut arena = KeyedArena::new();
        for i in 0..10 {
            arena.insert(i, i);
        }
        for (_, v) in arena.iter_mut() {
            *v += 1;
        }
        assert_eq!(
            arena
                .values_mut()
                .map(|val| val.clone())
                .collect::<BTreeSet<_>>(),
            (1..11).collect::<BTreeSet<_>>()
        );
    }

    #[test]
    fn contains_key_checks_values() {
        let arena = KeyedArena::new();
        for i in 0..10 {
            arena.insert(i, i);
        }
        for i in 0..10 {
            assert!(arena.contains_key(&i));
        }
        assert!(!arena.contains_key(&11));
        assert!(!arena.contains_key(&20));
        assert!(!arena.contains_key(&-1));
    }

    #[test]
    fn constructible_from_iterator() {
        let arena: KeyedArena<i32, i32> = (0..100).zip(0..100).collect();
        assert_eq!(arena.len(), 100);
    }
}