@@ -909,8 +909,11 @@ where
909909 /// Attempts to get mutable references to `N` values in the map at once.
910910 ///
911911 /// Returns an array of length `N` with the results of each query. For soundness, at most one
912- /// mutable reference will be returned to any value. `None` will be returned if any of the
913- /// keys are duplicates or missing.
912+ /// mutable reference will be returned to any value. `None` will be used if the key is missing.
913+ ///
914+ /// # Panics
915+ ///
916+ /// Panics if any keys are overlapping.
914917 ///
915918 /// # Examples
916919 ///
@@ -924,35 +927,55 @@ where
924927 /// libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691);
925928 /// libraries.insert("Library of Congress".to_string(), 1800);
926929 ///
930+ /// // Get Athenæum and Bodleian Library
931+ /// let [Some(a), Some(b)] = libraries.get_many_mut([
932+ /// "Athenæum",
933+ /// "Bodleian Library",
934+ /// ]) else { panic!() };
935+ ///
936+ /// // Assert values of Athenæum and Library of Congress
927937 /// let got = libraries.get_many_mut([
928938 /// "Athenæum",
929939 /// "Library of Congress",
930940 /// ]);
931941 /// assert_eq!(
932942 /// got,
933- /// Some( [
934- /// &mut 1807,
935- /// &mut 1800,
936- /// ]) ,
943+ /// [
944+ /// Some( &mut 1807) ,
945+ /// Some( &mut 1800) ,
946+ /// ],
937947 /// );
938948 ///
939949 /// // Missing keys result in None
940950 /// let got = libraries.get_many_mut([
941951 /// "Athenæum",
942952 /// "New York Public Library",
943953 /// ]);
944- /// assert_eq!(got, None);
954+ /// assert_eq!(
955+ /// got,
956+ /// [
957+ /// Some(&mut 1807),
958+ /// None
959+ /// ]
960+ /// );
961+ /// ```
962+ ///
963+ /// ```should_panic
964+ /// #![feature(map_many_mut)]
965+ /// use std::collections::HashMap;
945966 ///
946- /// // Duplicate keys result in None
967+ /// let mut libraries = HashMap::new();
968+ /// libraries.insert("Athenæum".to_string(), 1807);
969+ ///
970+ /// // Duplicate keys panic!
947971 /// let got = libraries.get_many_mut([
948972 /// "Athenæum",
949973 /// "Athenæum",
950974 /// ]);
951- /// assert_eq!(got, None);
952975 /// ```
953976 #[ inline]
954977 #[ unstable( feature = "map_many_mut" , issue = "97601" ) ]
955- pub fn get_many_mut < Q : ?Sized , const N : usize > ( & mut self , ks : [ & Q ; N ] ) -> Option < [ & ' _ mut V ; N ] >
978+ pub fn get_many_mut < Q : ?Sized , const N : usize > ( & mut self , ks : [ & Q ; N ] ) -> [ Option < & ' _ mut V > ; N ]
956979 where
957980 K : Borrow < Q > ,
958981 Q : Hash + Eq ,
@@ -963,10 +986,10 @@ where
963986 /// Attempts to get mutable references to `N` values in the map at once, without validating that
964987 /// the values are unique.
965988 ///
966- /// Returns an array of length `N` with the results of each query. `None` will be returned if
967- /// any of the keys are missing.
989+ /// Returns an array of length `N` with the results of each query. `None` will be used if
990+ /// the key is missing.
968991 ///
969- /// For a safe alternative see [`get_many_mut`](Self ::get_many_mut).
992+ /// For a safe alternative see [`get_many_mut`](`HashMap ::get_many_mut` ).
970993 ///
971994 /// # Safety
972995 ///
@@ -987,31 +1010,39 @@ where
9871010 /// libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691);
9881011 /// libraries.insert("Library of Congress".to_string(), 1800);
9891012 ///
990- /// let got = libraries.get_many_mut([
1013+ /// // SAFETY: The keys do not overlap.
1014+ /// let [Some(a), Some(b)] = (unsafe { libraries.get_many_unchecked_mut([
1015+ /// "Athenæum",
1016+ /// "Bodleian Library",
1017+ /// ]) }) else { panic!() };
1018+ ///
1019+ /// // SAFETY: The keys do not overlap.
1020+ /// let got = unsafe { libraries.get_many_unchecked_mut([
9911021 /// "Athenæum",
9921022 /// "Library of Congress",
993- /// ]);
1023+ /// ]) } ;
9941024 /// assert_eq!(
9951025 /// got,
996- /// Some( [
997- /// &mut 1807,
998- /// &mut 1800,
999- /// ]) ,
1026+ /// [
1027+ /// Some( &mut 1807) ,
1028+ /// Some( &mut 1800) ,
1029+ /// ],
10001030 /// );
10011031 ///
1002- /// // Missing keys result in None
1003- /// let got = libraries.get_many_mut ([
1032+ /// // SAFETY: The keys do not overlap.
1033+ /// let got = unsafe { libraries.get_many_unchecked_mut ([
10041034 /// "Athenæum",
10051035 /// "New York Public Library",
1006- /// ]);
1007- /// assert_eq!(got, None);
1036+ /// ]) };
1037+ /// // Missing keys result in None
1038+ /// assert_eq!(got, [Some(&mut 1807), None]);
10081039 /// ```
10091040 #[ inline]
10101041 #[ unstable( feature = "map_many_mut" , issue = "97601" ) ]
10111042 pub unsafe fn get_many_unchecked_mut < Q : ?Sized , const N : usize > (
10121043 & mut self ,
10131044 ks : [ & Q ; N ] ,
1014- ) -> Option < [ & ' _ mut V ; N ] >
1045+ ) -> [ Option < & ' _ mut V > ; N ]
10151046 where
10161047 K : Borrow < Q > ,
10171048 Q : Hash + Eq ,
@@ -2978,64 +3009,6 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
29783009 pub fn remove ( self ) -> V {
29793010 self . base . remove ( )
29803011 }
2981-
2982- /// Replaces the entry, returning the old key and value. The new key in the hash map will be
2983- /// the key used to create this entry.
2984- ///
2985- /// # Examples
2986- ///
2987- /// ```
2988- /// #![feature(map_entry_replace)]
2989- /// use std::collections::hash_map::{Entry, HashMap};
2990- /// use std::rc::Rc;
2991- ///
2992- /// let mut map: HashMap<Rc<String>, u32> = HashMap::new();
2993- /// map.insert(Rc::new("Stringthing".to_string()), 15);
2994- ///
2995- /// let my_key = Rc::new("Stringthing".to_string());
2996- ///
2997- /// if let Entry::Occupied(entry) = map.entry(my_key) {
2998- /// // Also replace the key with a handle to our other key.
2999- /// let (old_key, old_value): (Rc<String>, u32) = entry.replace_entry(16);
3000- /// }
3001- ///
3002- /// ```
3003- #[ inline]
3004- #[ unstable( feature = "map_entry_replace" , issue = "44286" ) ]
3005- pub fn replace_entry ( self , value : V ) -> ( K , V ) {
3006- self . base . replace_entry ( value)
3007- }
3008-
3009- /// Replaces the key in the hash map with the key used to create this entry.
3010- ///
3011- /// # Examples
3012- ///
3013- /// ```
3014- /// #![feature(map_entry_replace)]
3015- /// use std::collections::hash_map::{Entry, HashMap};
3016- /// use std::rc::Rc;
3017- ///
3018- /// let mut map: HashMap<Rc<String>, u32> = HashMap::new();
3019- /// let known_strings: Vec<Rc<String>> = Vec::new();
3020- ///
3021- /// // Initialise known strings, run program, etc.
3022- ///
3023- /// reclaim_memory(&mut map, &known_strings);
3024- ///
3025- /// fn reclaim_memory(map: &mut HashMap<Rc<String>, u32>, known_strings: &[Rc<String>] ) {
3026- /// for s in known_strings {
3027- /// if let Entry::Occupied(entry) = map.entry(Rc::clone(s)) {
3028- /// // Replaces the entry's key with our version of it in `known_strings`.
3029- /// entry.replace_key();
3030- /// }
3031- /// }
3032- /// }
3033- /// ```
3034- #[ inline]
3035- #[ unstable( feature = "map_entry_replace" , issue = "44286" ) ]
3036- pub fn replace_key ( self ) -> K {
3037- self . base . replace_key ( )
3038- }
30393012}
30403013
30413014impl < ' a , K : ' a , V : ' a > VacantEntry < ' a , K , V > {
0 commit comments