@@ -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 ]
956979where
957980K : Borrow < Q > ,
958981Q : 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" ) ]
10111042pub unsafe fn get_many_unchecked_mut < Q : ?Sized , const N : usize > (
10121043& mut self ,
10131044ks : [ & Q ; N ] ,
1014- ) -> Option < [ & ' _ mut V ; N ] >
1045+ ) -> [ Option < & ' _ mut V > ; N ]
10151046where
10161047K : Borrow < Q > ,
10171048Q : Hash + Eq ,
@@ -2978,64 +3009,6 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
29783009pub fn remove ( self ) -> V {
29793010self . 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