Rollup merge of rust-lang#143529 - pixel27:master, r=jhpratt

Renamed retain_mut to retain on LinkedList as mentioned in the ACP

This is for proposal: rust-lang/libs-team#250

The original check-in (rust-lang#114136) contained both methods **retain** and **retain_mut**, which does not conform to rust-lang/libs-team#250 (comment).

I updated the retain documentation to specify **&mut e**, removed the **retain** method and renamed **retain_mut** to **retain** to conform to the request.

The pull request doesn't really contain much that is new, just removes the unwanted method to meet the requirements.

I've run the tests "library/alloc" on the code and no issues.

Hopefully I'm not stepping on the original author's toes. I just ran across a need for the method and wondered why it was unstable.

Author: jhpratt

library/alloc/src/collections/linked_list.rs

@@ -1031,7 +1031,7 @@ impl<T, A: Allocator> LinkedList<T, A> {
 
     /// Retains only the elements specified by the predicate.
     ///
-    /// In other words, remove all elements `e` for which `f(&e)` returns false.
+    /// In other words, remove all elements `e` for which `f(&mut e)` returns false.
     /// This method operates in place, visiting each element exactly once in the
     /// original order, and preserves the order of the retained elements.
     ///
@@ -1047,7 +1047,7 @@ impl<T, A: Allocator> LinkedList<T, A> {
     /// d.push_front(2);
     /// d.push_front(3);
     ///
-    /// d.retain(|&x| x % 2 == 0);
+    /// d.retain(|&mut x| x % 2 == 0);
     ///
     /// assert_eq!(d.pop_front(), Some(2));
     /// assert_eq!(d.pop_front(), None);
@@ -1074,41 +1074,6 @@ impl<T, A: Allocator> LinkedList<T, A> {
     /// ```
     #[unstable(feature = "linked_list_retain", issue = "114135")]
     pub fn retain<F>(&mut self, mut f: F)
-    where
-        F: FnMut(&T) -> bool,
-    {
-        self.retain_mut(|elem| f(elem));
-    }
-
-    /// Retains only the elements specified by the predicate.
-    ///
-    /// In other words, remove all elements `e` for which `f(&mut e)` returns false.
-    /// This method operates in place, visiting each element exactly once in the
-    /// original order, and preserves the order of the retained elements.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// #![feature(linked_list_retain)]
-    /// use std::collections::LinkedList;
-    ///
-    /// let mut d = LinkedList::new();
-    ///
-    /// d.push_front(1);
-    /// d.push_front(2);
-    /// d.push_front(3);
-    ///
-    /// d.retain_mut(|x| if *x % 2 == 0 {
-    ///     *x += 1;
-    ///     true
-    /// } else {
-    ///     false
-    /// });
-    /// assert_eq!(d.pop_front(), Some(3));
-    /// assert_eq!(d.pop_front(), None);
-    /// ```
-    #[unstable(feature = "linked_list_retain", issue = "114135")]
-    pub fn retain_mut<F>(&mut self, mut f: F)
     where
         F: FnMut(&mut T) -> bool,
     {