Auto merge of #63045 - Rosto75:master, r=jonas-schievink

Change the placement of two functions.

Right now, the order is as follows:
`pop_front()`
`push_front()`
`push_back()`
`pop_back()`

`swap_remove_back()`
`swap_remove_front()`

I believe it would be more natural, and easier to follow, if we place `pop_back()` right after the `pop_front()`, and `swap_remove_back()` after the `swap_remove_front()` like this:
`pop_front()`
`pop_back()`
`push_front()`
`push_back()`

`swap_remove_front()`
`swap_remove_back()`

The rest of the documentation (at least in this module) adheres to the same logic, where the 'front' function always precedes its 'back' equivalent.

src/liballoc/collections/vec_deque.rs

@@ -1199,6 +1199,31 @@ impl<T> VecDeque<T> {
         }
     }
 
+    /// Removes the last element from the `VecDeque` and returns it, or `None` if
+    /// it is empty.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::collections::VecDeque;
+    ///
+    /// let mut buf = VecDeque::new();
+    /// assert_eq!(buf.pop_back(), None);
+    /// buf.push_back(1);
+    /// buf.push_back(3);
+    /// assert_eq!(buf.pop_back(), Some(3));
+    /// ```
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub fn pop_back(&mut self) -> Option<T> {
+        if self.is_empty() {
+            None
+        } else {
+            self.head = self.wrap_sub(self.head, 1);
+            let head = self.head;
+            unsafe { Some(self.buffer_read(head)) }
+        }
+    }
+
     /// Prepends an element to the `VecDeque`.
     ///
     /// # Examples
@@ -1243,38 +1268,13 @@ impl<T> VecDeque<T> {
         unsafe { self.buffer_write(head, value) }
     }
 
-    /// Removes the last element from the `VecDeque` and returns it, or `None` if
-    /// it is empty.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// use std::collections::VecDeque;
-    ///
-    /// let mut buf = VecDeque::new();
-    /// assert_eq!(buf.pop_back(), None);
-    /// buf.push_back(1);
-    /// buf.push_back(3);
-    /// assert_eq!(buf.pop_back(), Some(3));
-    /// ```
-    #[stable(feature = "rust1", since = "1.0.0")]
-    pub fn pop_back(&mut self) -> Option<T> {
-        if self.is_empty() {
-            None
-        } else {
-            self.head = self.wrap_sub(self.head, 1);
-            let head = self.head;
-            unsafe { Some(self.buffer_read(head)) }
-        }
-    }
-
     #[inline]
     fn is_contiguous(&self) -> bool {
         self.tail <= self.head
     }
 
-    /// Removes an element from anywhere in the `VecDeque` and returns it, replacing it with the
-    /// last element.
+    /// Removes an element from anywhere in the `VecDeque` and returns it,
+    /// replacing it with the first element.
     ///
     /// This does not preserve ordering, but is O(1).
     ///
@@ -1288,28 +1288,28 @@ impl<T> VecDeque<T> {
     /// use std::collections::VecDeque;
     ///
     /// let mut buf = VecDeque::new();
-    /// assert_eq!(buf.swap_remove_back(0), None);
+    /// assert_eq!(buf.swap_remove_front(0), None);
     /// buf.push_back(1);
     /// buf.push_back(2);
     /// buf.push_back(3);
     /// assert_eq!(buf, [1, 2, 3]);
     ///
-    /// assert_eq!(buf.swap_remove_back(0), Some(1));
-    /// assert_eq!(buf, [3, 2]);
+    /// assert_eq!(buf.swap_remove_front(2), Some(3));
+    /// assert_eq!(buf, [2, 1]);
     /// ```
     #[stable(feature = "deque_extras_15", since = "1.5.0")]
-    pub fn swap_remove_back(&mut self, index: usize) -> Option<T> {
+    pub fn swap_remove_front(&mut self, index: usize) -> Option<T> {
         let length = self.len();
-        if length > 0 && index < length - 1 {
-            self.swap(index, length - 1);
+        if length > 0 && index < length && index != 0 {
+            self.swap(index, 0);
         } else if index >= length {
             return None;
         }
-        self.pop_back()
+        self.pop_front()
     }
 
-    /// Removes an element from anywhere in the `VecDeque` and returns it,
-    /// replacing it with the first element.
+    /// Removes an element from anywhere in the `VecDeque` and returns it, replacing it with the
+    /// last element.
     ///
     /// This does not preserve ordering, but is O(1).
     ///
@@ -1323,24 +1323,24 @@ impl<T> VecDeque<T> {
     /// use std::collections::VecDeque;
     ///
     /// let mut buf = VecDeque::new();
-    /// assert_eq!(buf.swap_remove_front(0), None);
+    /// assert_eq!(buf.swap_remove_back(0), None);
     /// buf.push_back(1);
     /// buf.push_back(2);
     /// buf.push_back(3);
     /// assert_eq!(buf, [1, 2, 3]);
     ///
-    /// assert_eq!(buf.swap_remove_front(2), Some(3));
-    /// assert_eq!(buf, [2, 1]);
+    /// assert_eq!(buf.swap_remove_back(0), Some(1));
+    /// assert_eq!(buf, [3, 2]);
     /// ```
     #[stable(feature = "deque_extras_15", since = "1.5.0")]
-    pub fn swap_remove_front(&mut self, index: usize) -> Option<T> {
+    pub fn swap_remove_back(&mut self, index: usize) -> Option<T> {
         let length = self.len();
-        if length > 0 && index < length && index != 0 {
-            self.swap(index, 0);
+        if length > 0 && index < length - 1 {
+            self.swap(index, length - 1);
         } else if index >= length {
             return None;
         }
-        self.pop_front()
+        self.pop_back()
     }
 
     /// Inserts an element at `index` within the `VecDeque`, shifting all elements with indices