indexmap/map/
mutable.rs

1use core::hash::{BuildHasher, Hash};
2
3use super::{
4    Bucket, Entry, Equivalent, IndexMap, IndexedEntry, IterMut2, OccupiedEntry, VacantEntry,
5};
6
7/// Opt-in mutable access to [`IndexMap`] keys.
8///
9/// These methods expose `&mut K`, mutable references to the key as it is stored
10/// in the map.
11/// You are allowed to modify the keys in the map **if the modification
12/// does not change the key's hash and equality**.
13///
14/// If keys are modified erroneously, you can no longer look them up.
15/// This is sound (memory safe) but a logical error hazard (just like
16/// implementing `PartialEq`, `Eq`, or `Hash` incorrectly would be).
17///
18/// `use` this trait to enable its methods for `IndexMap`.
19///
20/// This trait is sealed and cannot be implemented for types outside this crate.
21#[expect(private_bounds)]
22pub trait MutableKeys: Sealed {
23    type Key;
24    type Value;
25
26    /// Return item index, mutable reference to key and value
27    ///
28    /// Computes in **O(1)** time (average).
29    fn get_full_mut2<Q>(&mut self, key: &Q) -> Option<(usize, &mut Self::Key, &mut Self::Value)>
30    where
31        Q: ?Sized + Hash + Equivalent<Self::Key>;
32
33    /// Return mutable reference to key and value at an index.
34    ///
35    /// Valid indices are `0 <= index < self.len()`.
36    ///
37    /// Computes in **O(1)** time.
38    fn get_index_mut2(&mut self, index: usize) -> Option<(&mut Self::Key, &mut Self::Value)>;
39
40    /// Return an iterator over the key-value pairs of the map, in their order
41    fn iter_mut2(&mut self) -> IterMut2<'_, Self::Key, Self::Value>;
42
43    /// Scan through each key-value pair in the map and keep those where the
44    /// closure `keep` returns `true`.
45    ///
46    /// The elements are visited in order, and remaining elements keep their
47    /// order.
48    ///
49    /// Computes in **O(n)** time (average).
50    fn retain2<F>(&mut self, keep: F)
51    where
52        F: FnMut(&mut Self::Key, &mut Self::Value) -> bool;
53}
54
55/// Opt-in mutable access to [`IndexMap`] keys.
56///
57/// See [`MutableKeys`] for more information.
58impl<K, V, S> MutableKeys for IndexMap<K, V, S>
59where
60    S: BuildHasher,
61{
62    type Key = K;
63    type Value = V;
64
65    fn get_full_mut2<Q>(&mut self, key: &Q) -> Option<(usize, &mut K, &mut V)>
66    where
67        Q: ?Sized + Hash + Equivalent<K>,
68    {
69        if let Some(i) = self.get_index_of(key) {
70            let entry = &mut self.as_entries_mut()[i];
71            Some((i, &mut entry.key, &mut entry.value))
72        } else {
73            None
74        }
75    }
76
77    fn get_index_mut2(&mut self, index: usize) -> Option<(&mut K, &mut V)> {
78        self.as_entries_mut().get_mut(index).map(Bucket::muts)
79    }
80
81    fn iter_mut2(&mut self) -> IterMut2<'_, Self::Key, Self::Value> {
82        IterMut2::new(self.as_entries_mut())
83    }
84
85    fn retain2<F>(&mut self, keep: F)
86    where
87        F: FnMut(&mut K, &mut V) -> bool,
88    {
89        self.core.retain_in_order(keep);
90    }
91}
92
93/// Opt-in mutable access to [`Entry`] keys.
94///
95/// These methods expose `&mut K`, mutable references to the key as it is stored
96/// in the map.
97/// You are allowed to modify the keys in the map **if the modification
98/// does not change the key's hash and equality**.
99///
100/// If keys are modified erroneously, you can no longer look them up.
101/// This is sound (memory safe) but a logical error hazard (just like
102/// implementing `PartialEq`, `Eq`, or `Hash` incorrectly would be).
103///
104/// `use` this trait to enable its methods for `Entry`.
105///
106/// This trait is sealed and cannot be implemented for types outside this crate.
107#[expect(private_bounds)]
108pub trait MutableEntryKey: Sealed {
109    type Key;
110
111    /// Gets a mutable reference to the entry's key, either within the map if occupied,
112    /// or else the new key that was used to find the entry.
113    fn key_mut(&mut self) -> &mut Self::Key;
114}
115
116/// Opt-in mutable access to [`Entry`] keys.
117///
118/// See [`MutableEntryKey`] for more information.
119impl<K, V> MutableEntryKey for Entry<'_, K, V> {
120    type Key = K;
121    fn key_mut(&mut self) -> &mut Self::Key {
122        match self {
123            Entry::Occupied(e) => e.key_mut(),
124            Entry::Vacant(e) => e.key_mut(),
125        }
126    }
127}
128
129/// Opt-in mutable access to [`OccupiedEntry`] keys.
130///
131/// See [`MutableEntryKey`] for more information.
132impl<K, V> MutableEntryKey for OccupiedEntry<'_, K, V> {
133    type Key = K;
134    fn key_mut(&mut self) -> &mut Self::Key {
135        self.key_mut()
136    }
137}
138
139/// Opt-in mutable access to [`VacantEntry`] keys.
140///
141/// See [`MutableEntryKey`] for more information.
142impl<K, V> MutableEntryKey for VacantEntry<'_, K, V> {
143    type Key = K;
144    fn key_mut(&mut self) -> &mut Self::Key {
145        self.key_mut()
146    }
147}
148
149/// Opt-in mutable access to [`IndexedEntry`] keys.
150///
151/// See [`MutableEntryKey`] for more information.
152impl<K, V> MutableEntryKey for IndexedEntry<'_, K, V> {
153    type Key = K;
154    fn key_mut(&mut self) -> &mut Self::Key {
155        self.key_mut()
156    }
157}
158
159trait Sealed {}
160
161impl<K, V, S> Sealed for IndexMap<K, V, S> {}
162impl<K, V> Sealed for Entry<'_, K, V> {}
163impl<K, V> Sealed for OccupiedEntry<'_, K, V> {}
164impl<K, V> Sealed for VacantEntry<'_, K, V> {}
165impl<K, V> Sealed for IndexedEntry<'_, K, V> {}
indexmap/map/mutable.rs

indexmap/map/
mutable.rs
