Merge pull request #17 from cuviper/deprecate-inserts

Add more back/front methods and deprecate unspecified inserts

Author: cuviper

benches/bench.rs

@@ -226,12 +226,24 @@ fn entry_hashmap_150(b: &mut Bencher) {
 }
 
 #[bench]
-fn entry_ringmap_150(b: &mut Bencher) {
+fn entry_ringmap_back_150(b: &mut Bencher) {
     let c = 150;
     b.iter(|| {
         let mut map = RingMap::with_capacity(c);
         for x in 0..c {
-            map.entry(x).or_insert(());
+            map.entry(x).or_push_back(());
+        }
+        map
+    });
+}
+
+#[bench]
+fn entry_ringmap_front_150(b: &mut Bencher) {
+    let c = 150;
+    b.iter(|| {
+        let mut map = RingMap::with_capacity(c);
+        for x in 0..c {
+            map.entry(x).or_push_front(());
         }
         map
     });

src/map.rs

@@ -442,27 +442,16 @@ where
     /// Computes in **O(1)** time (amortized average).
     ///
     /// See also [`entry`][Self::entry] if you want to insert *or* modify,
-    /// or [`insert_full`][Self::insert_full] if you need to get the index of
-    /// the corresponding key-value pair.
+    /// or [`push_back`][Self::push_back] or [`push_front`][Self::push_front]
+    /// if you need to get the index of the corresponding key-value pair,
+    /// explicitly choosing which position to make new insertions.
     pub fn insert(&mut self, key: K, value: V) -> Option<V> {
-        self.insert_full(key, value).1
+        self.push_back(key, value).1
     }
 
-    /// Insert a key-value pair in the map, and get their index.
-    ///
-    /// If an equivalent key already exists in the map: the key remains and
-    /// retains in its place in the order, its corresponding value is updated
-    /// with `value`, and the older value is returned inside `(index, Some(_))`.
-    ///
-    /// If no equivalent key existed in the map: the new key-value pair is
-    /// inserted, last in order, and `(index, None)` is returned.
-    ///
-    /// Computes in **O(1)** time (amortized average).
-    ///
-    /// See also [`entry`][Self::entry] if you want to insert *or* modify.
+    #[deprecated = "use `push_back` or `push_front` instead"]
     pub fn insert_full(&mut self, key: K, value: V) -> (usize, Option<V>) {
-        let hash = self.hash(&key);
-        self.core.push_back(hash, key, value)
+        self.push_back(key, value)
     }
 
     /// Appends or updates a key-value pair in the map, and get their index.

src/map/core/entry.rs

@@ -37,38 +37,52 @@ pub enum Entry<'a, K, V> {
 }
 
 impl<'a, K, V> Entry<'a, K, V> {
-    /// Return the index where the key-value pair exists or will be inserted.
+    /// Return the index where the key-value pair exists or may be appended.
+    ///
+    /// Note that some methods may instead prepend new items at index 0.
     pub fn index(&self) -> usize {
         match *self {
             Entry::Occupied(ref entry) => entry.index(),
             Entry::Vacant(ref entry) => entry.index(),
         }
     }
 
-    /// Sets the value of the entry (after inserting if vacant), and returns an `OccupiedEntry`.
+    #[deprecated = "use `push_back_entry` or `push_front_entry` instead"]
+    pub fn insert_entry(self, value: V) -> OccupiedEntry<'a, K, V> {
+        self.push_back_entry(value)
+    }
+
+    /// Sets the value of the entry (after appending if vacant), and returns an `OccupiedEntry`.
     ///
     /// Computes in **O(1)** time (amortized average).
-    pub fn insert_entry(self, value: V) -> OccupiedEntry<'a, K, V> {
+    pub fn push_back_entry(self, value: V) -> OccupiedEntry<'a, K, V> {
         match self {
             Entry::Occupied(mut entry) => {
                 entry.insert(value);
                 entry
             }
-            Entry::Vacant(entry) => entry.insert_entry(value),
+            Entry::Vacant(entry) => entry.push_back_entry(value),
         }
     }
 
-    /// Inserts the given default value in the entry if it is vacant and returns a mutable
-    /// reference to it. Otherwise a mutable reference to an already existent value is returned.
+    /// Sets the value of the entry (after prepending if vacant), and returns an `OccupiedEntry`.
     ///
     /// Computes in **O(1)** time (amortized average).
-    pub fn or_insert(self, default: V) -> &'a mut V {
+    pub fn push_front_entry(self, value: V) -> OccupiedEntry<'a, K, V> {
         match self {
-            Entry::Occupied(entry) => entry.into_mut(),
-            Entry::Vacant(entry) => entry.insert(default),
+            Entry::Occupied(mut entry) => {
+                entry.insert(value);
+                entry
+            }
+            Entry::Vacant(entry) => entry.push_front_entry(value),
         }
     }
 
+    #[deprecated = "use `or_push_back` or `or_push_front` instead"]
+    pub fn or_insert(self, default: V) -> &'a mut V {
+        self.or_push_back(default)
+    }
+
     /// Appends the given default value in the entry if it is vacant and returns a mutable
     /// reference to it. Otherwise a mutable reference to an already existent value is returned.
     ///
@@ -91,34 +105,112 @@ impl<'a, K, V> Entry<'a, K, V> {
         }
     }
 
-    /// Inserts the result of the `call` function in the entry if it is vacant and returns a mutable
+    #[deprecated = "use `or_push_back_default` or `or_push_front_default` instead"]
+    pub fn or_default(self) -> &'a mut V
+    where
+        V: Default,
+    {
+        self.or_push_back_default()
+    }
+
+    /// Appends a default-constructed value in the entry if it is vacant and returns a mutable
+    /// reference to it. Otherwise a mutable reference to an already existent value is returned.
+    ///
+    /// Computes in **O(1)** time (amortized average).
+    pub fn or_push_back_default(self) -> &'a mut V
+    where
+        V: Default,
+    {
+        self.or_push_back_with(V::default)
+    }
+
+    /// Prepends a default-constructed value in the entry if it is vacant and returns a mutable
     /// reference to it. Otherwise a mutable reference to an already existent value is returned.
     ///
     /// Computes in **O(1)** time (amortized average).
+    pub fn or_push_front_default(self) -> &'a mut V
+    where
+        V: Default,
+    {
+        self.or_push_front_with(V::default)
+    }
+
+    #[deprecated = "use `or_push_back_with` or `or_push_front_with` instead"]
     pub fn or_insert_with<F>(self, call: F) -> &'a mut V
+    where
+        F: FnOnce() -> V,
+    {
+        self.or_push_back_with(call)
+    }
+
+    /// Appends the result of the `call` function in the entry if it is vacant and returns a mutable
+    /// reference to it. Otherwise a mutable reference to an already existent value is returned.
+    ///
+    /// Computes in **O(1)** time (amortized average).
+    pub fn or_push_back_with<F>(self, call: F) -> &'a mut V
     where
         F: FnOnce() -> V,
     {
         match self {
             Entry::Occupied(entry) => entry.into_mut(),
-            Entry::Vacant(entry) => entry.insert(call()),
+            Entry::Vacant(entry) => entry.push_back(call()),
         }
     }
 
-    /// Inserts the result of the `call` function with a reference to the entry's key if it is
+    /// Prepends the result of the `call` function in the entry if it is vacant and returns a mutable
+    /// reference to it. Otherwise a mutable reference to an already existent value is returned.
+    ///
+    /// Computes in **O(1)** time (amortized average).
+    pub fn or_push_front_with<F>(self, call: F) -> &'a mut V
+    where
+        F: FnOnce() -> V,
+    {
+        match self {
+            Entry::Occupied(entry) => entry.into_mut(),
+            Entry::Vacant(entry) => entry.push_front(call()),
+        }
+    }
+
+    #[deprecated = "use `or_push_back_with_key` or `or_push_front_with_key` instead"]
+    pub fn or_insert_with_key<F>(self, call: F) -> &'a mut V
+    where
+        F: FnOnce(&K) -> V,
+    {
+        self.or_push_back_with_key(call)
+    }
+
+    /// Appends the result of the `call` function with a reference to the entry's key if it is
     /// vacant, and returns a mutable reference to the new value. Otherwise a mutable reference to
     /// an already existent value is returned.
     ///
     /// Computes in **O(1)** time (amortized average).
-    pub fn or_insert_with_key<F>(self, call: F) -> &'a mut V
+    pub fn or_push_back_with_key<F>(self, call: F) -> &'a mut V
     where
         F: FnOnce(&K) -> V,
     {
         match self {
             Entry::Occupied(entry) => entry.into_mut(),
             Entry::Vacant(entry) => {
                 let value = call(&entry.key);
-                entry.insert(value)
+                entry.push_back(value)
+            }
+        }
+    }
+
+    /// Prepends the result of the `call` function with a reference to the entry's key if it is
+    /// vacant, and returns a mutable reference to the new value. Otherwise a mutable reference to
+    /// an already existent value is returned.
+    ///
+    /// Computes in **O(1)** time (amortized average).
+    pub fn or_push_front_with_key<F>(self, call: F) -> &'a mut V
+    where
+        F: FnOnce(&K) -> V,
+    {
+        match self {
+            Entry::Occupied(entry) => entry.into_mut(),
+            Entry::Vacant(entry) => {
+                let value = call(&entry.key);
+                entry.push_front(value)
             }
         }
     }
@@ -142,20 +234,6 @@ impl<'a, K, V> Entry<'a, K, V> {
         }
         self
     }
-
-    /// Inserts a default-constructed value in the entry if it is vacant and returns a mutable
-    /// reference to it. Otherwise a mutable reference to an already existent value is returned.
-    ///
-    /// Computes in **O(1)** time (amortized average).
-    pub fn or_default(self) -> &'a mut V
-    where
-        V: Default,
-    {
-        match self {
-            Entry::Occupied(entry) => entry.into_mut(),
-            Entry::Vacant(entry) => entry.insert(V::default()),
-        }
-    }
 }
 
 impl<K: fmt::Debug, V: fmt::Debug> fmt::Debug for Entry<'_, K, V> {
@@ -392,7 +470,10 @@ pub struct VacantEntry<'a, K, V> {
 }
 
 impl<'a, K, V> VacantEntry<'a, K, V> {
-    /// Return the index where a key-value pair may be inserted.
+    /// Return the index where a key-value pair may be appended.
+    ///
+    /// Note that some methods may instead prepend new items at index 0, or
+    /// even insert at arbitrary indexes in-between.
     pub fn index(&self) -> usize {
         self.map.indices.len()
     }
@@ -411,18 +492,17 @@ impl<'a, K, V> VacantEntry<'a, K, V> {
         self.key
     }
 
-    /// Inserts the entry's key and the given value into the map,
-    /// and returns a mutable reference to the value.
+    #[deprecated = "use `push_back` or `push_front` instead"]
     pub fn insert(self, value: V) -> &'a mut V {
-        // this is now redundant...
         self.push_back(value)
     }
 
-    /// Inserts the entry's key and the given value into the map, and returns an `OccupiedEntry`.
-    ///
-    /// Computes in **O(1)** time (amortized average).
-    pub fn insert_entry(self, value: V) -> OccupiedEntry<'a, K, V> {
-        self.map.push_back_unique(self.hash, self.key, value)
+    /// Appends the entry's key and the given value onto the map,
+    /// and returns a mutable reference to the value.
+    pub fn push_back(self, value: V) -> &'a mut V {
+        self.map
+            .push_back_unique(self.hash, self.key, value)
+            .into_mut()
     }
 
     /// Prepends the entry's key and the given value onto the map,
@@ -433,12 +513,23 @@ impl<'a, K, V> VacantEntry<'a, K, V> {
             .into_mut()
     }
 
-    /// Appends the entry's key and the given value onto the map,
-    /// and returns a mutable reference to the value.
-    pub fn push_back(self, value: V) -> &'a mut V {
-        self.map
-            .push_back_unique(self.hash, self.key, value)
-            .into_mut()
+    #[deprecated = "use `push_back_entry` or `push_front_entry` instead"]
+    pub fn insert_entry(self, value: V) -> OccupiedEntry<'a, K, V> {
+        self.push_back_entry(value)
+    }
+
+    /// Appends the entry's key and the given value into the map, and returns an `OccupiedEntry`.
+    ///
+    /// Computes in **O(1)** time (amortized average).
+    pub fn push_back_entry(self, value: V) -> OccupiedEntry<'a, K, V> {
+        self.map.push_back_unique(self.hash, self.key, value)
+    }
+
+    /// Prepends the entry's key and the given value into the map, and returns an `OccupiedEntry`.
+    ///
+    /// Computes in **O(1)** time (amortized average).
+    pub fn push_front_entry(self, value: V) -> OccupiedEntry<'a, K, V> {
+        self.map.push_front_unique(self.hash, self.key, value)
     }
 
     /// Inserts the entry's key and the given value into the map at its ordered