indexmap/map/
mutable.rs

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

indexmap/map/
mutable.rs
