indexmap/map/
mutable.rs

Help
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.
21pub trait MutableKeys: private::Sealed {
22    type Key;
23    type Value;
24
25    /// Return item index, mutable reference to key and value
26    ///
27    /// Computes in **O(1)** time (average).
28    fn get_full_mut2<Q>(&mut self, key: &Q) -> Option<(usize, &mut Self::Key, &mut Self::Value)>
29    where
30        Q: ?Sized + Hash + Equivalent<Self::Key>;
31
32    /// Return mutable reference to key and value at an index.
33    ///
34    /// Valid indices are `0 <= index < self.len()`.
35    ///
36    /// Computes in **O(1)** time.
37    fn get_index_mut2(&mut self, index: usize) -> Option<(&mut Self::Key, &mut Self::Value)>;
38
39    /// Return an iterator over the key-value pairs of the map, in their order
40    fn iter_mut2(&mut self) -> IterMut2<'_, Self::Key, Self::Value>;
41
42    /// Scan through each key-value pair in the map and keep those where the
43    /// closure `keep` returns `true`.
44    ///
45    /// The elements are visited in order, and remaining elements keep their
46    /// order.
47    ///
48    /// Computes in **O(n)** time (average).
49    fn retain2<F>(&mut self, keep: F)
50    where
51        F: FnMut(&mut Self::Key, &mut Self::Value) -> bool;
52}
53
54/// Opt-in mutable access to [`IndexMap`] keys.
55///
56/// See [`MutableKeys`] for more information.
57impl<K, V, S> MutableKeys for IndexMap<K, V, S>
58where
59    S: BuildHasher,
60{
61    type Key = K;
62    type Value = V;
63
64    fn get_full_mut2<Q>(&mut self, key: &Q) -> Option<(usize, &mut K, &mut V)>
65    where
66        Q: ?Sized + Hash + Equivalent<K>,
67    {
68        if let Some(i) = self.get_index_of(key) {
69            let entry = &mut self.as_entries_mut()[i];
70            Some((i, &mut entry.key, &mut entry.value))
71        } else {
72            None
73        }
74    }
75
76    fn get_index_mut2(&mut self, index: usize) -> Option<(&mut K, &mut V)> {
77        self.as_entries_mut().get_mut(index).map(Bucket::muts)
78    }
79
80    fn iter_mut2(&mut self) -> IterMut2<'_, Self::Key, Self::Value> {
81        IterMut2::new(self.as_entries_mut())
82    }
83
84    fn retain2<F>(&mut self, keep: F)
85    where
86        F: FnMut(&mut K, &mut V) -> bool,
87    {
88        self.core.retain_in_order(keep);
89    }
90}
91
92/// Opt-in mutable access to [`Entry`] keys.
93///
94/// These methods expose `&mut K`, mutable references to the key as it is stored
95/// in the map.
96/// You are allowed to modify the keys in the map **if the modification
97/// does not change the key’s hash and equality**.
98///
99/// If keys are modified erroneously, you can no longer look them up.
100/// This is sound (memory safe) but a logical error hazard (just like
101/// implementing `PartialEq`, `Eq`, or `Hash` incorrectly would be).
102///
103/// `use` this trait to enable its methods for `Entry`.
104///
105/// This trait is sealed and cannot be implemented for types outside this crate.
106pub trait MutableEntryKey: private::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        self.key_mut()
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
157mod private {
158    pub trait Sealed {}
159
160    impl<K, V, S> Sealed for super::IndexMap<K, V, S> {}
161    impl<K, V> Sealed for super::Entry<'_, K, V> {}
162    impl<K, V> Sealed for super::OccupiedEntry<'_, K, V> {}
163    impl<K, V> Sealed for super::VacantEntry<'_, K, V> {}
164    impl<K, V> Sealed for super::IndexedEntry<'_, K, V> {}
165}
indexmap/map/mutable.rs

indexmap/map/
mutable.rs
