Update mod.rs

Author: balt-dev

library/alloc/src/collections/vec_deque/mod.rs

@@ -183,8 +183,11 @@ impl<T, A: Allocator> VecDeque<T, A> {
     }
 
     /// Writes an element into the buffer, moving it and returning a pointer to it.
+    /// # Safety
+    ///
+    /// May only be called if `off < self.capacity()`.
     #[inline]
-    unsafe fn buffer_write(&mut self, off: usize, value: T) -> *mut T {
+    unsafe fn buffer_write(&mut self, off: usize, value: T) -> &mut T {
         unsafe {
             let ptr = self.ptr().add(off);
             ptr::write(ptr, value);
@@ -1901,59 +1904,57 @@ impl<T, A: Allocator> VecDeque<T, A> {
             self.buffer_write(self.head, value);
         }
     }
-
-    /// Appends an element to the back of the deque.
+    
+    /// Prepends an element to the deque, returning a reference to it.
     ///
     /// # Examples
     ///
     /// ```
+    /// #![feature(push_mut)]
     /// use std::collections::VecDeque;
     ///
-    /// let mut buf = VecDeque::new();
-    /// buf.push_back(1);
-    /// buf.push_back(3);
-    /// assert_eq!(3, *buf.back().unwrap());
+    /// let mut d = VecDeque::from([1, 2, 3]);
+    /// let x = d.push_front_mut(8);
+    /// *x -= 1;
+    /// assert_eq!(d.front(), Some(&7));
     /// ```
-    #[stable(feature = "rust1", since = "1.0.0")]
-    #[rustc_confusables("push", "put", "append")]
+    #[unstable(feature = "push_mut", issue = "135974")]
     #[track_caller]
-    pub fn push_back(&mut self, value: T) {
+    #[must_use = "if you don't need a reference to the value, use VecDeque::push_front instead"]
+    pub fn push_front_mut(&mut self, value: T) -> &mut T {
         if self.is_full() {
             self.grow();
         }
 
-        unsafe { self.buffer_write(self.to_physical_idx(self.len), value) };
+        self.head = self.wrap_sub(self.head, 1);
         self.len += 1;
+        // SAFETY: We know that self.head is within range of the deque.
+        unsafe { self.buffer_write(self.head, value) }
     }
 
-    /// Prepends an element to the deque, returning a reference to it.
+    /// Appends an element to the back of the deque.
     ///
     /// # Examples
     ///
     /// ```
-    /// #![feature(push_mut)]
     /// use std::collections::VecDeque;
     ///
-    /// let mut d = VecDeque::from([1, 2, 3]);
-    /// let x = d.push_front_mut(1);
-    /// *x -= 1;
-    /// assert_eq!(d.front(), Some(&0));
+    /// let mut buf = VecDeque::new();
+    /// buf.push_back(1);
+    /// buf.push_back(3);
+    /// assert_eq!(3, *buf.back().unwrap());
     /// ```
-    #[unstable(feature = "push_mut", issue = "135974")]
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[rustc_confusables("push", "put", "append")]
     #[track_caller]
-    #[must_use = "if you don't need a reference to the value, use VecDeque::push_front instead"]
-    pub fn push_front_mut(&mut self, value: T) -> &mut T {
+    pub fn push_back(&mut self, value: T) {
         if self.is_full() {
             self.grow();
         }
-
-        self.head = self.wrap_sub(self.head, 1);
+        
+        // SAFETY: We know that self.head is within range of the deque.
+        unsafe { self.buffer_write(self.to_physical_idx(self.len), value) };
         self.len += 1;
-
-        unsafe {
-            let ptr = self.buffer_write(self.head, value);
-            &mut *ptr
-        }
     }
 
     /// Appends an element to the back of the deque, returning a reference to it.
@@ -1965,9 +1966,9 @@ impl<T, A: Allocator> VecDeque<T, A> {
     /// use std::collections::VecDeque;
     ///
     /// let mut d = VecDeque::from([1, 2, 3]);
-    /// let x = d.push_back_mut(3);
+    /// let x = d.push_back_mut(9);
     /// *x += 1;
-    /// assert_eq!(d.back(), Some(&4));
+    /// assert_eq!(d.back(), Some(&10));
     /// ```
     #[unstable(feature = "push_mut", issue = "135974")]
     #[track_caller]
@@ -2158,7 +2159,7 @@ impl<T, A: Allocator> VecDeque<T, A> {
                 self.wrap_copy(self.to_physical_idx(index), self.to_physical_idx(index + 1), k);
                 let ptr = self.buffer_write(self.to_physical_idx(index), value);
                 self.len += 1;
-                Some(&mut *ptr)
+                Some(ptr)
             }
         } else {
             let old_head = self.head;
@@ -2167,7 +2168,7 @@ impl<T, A: Allocator> VecDeque<T, A> {
                 self.wrap_copy(old_head, self.head, index);
                 let ptr = self.buffer_write(self.to_physical_idx(index), value);
                 self.len += 1;
-                Some(&mut *ptr)
+                Some(ptr)
             }
         }
     }