add extend_front to VecDeque with specialization like extend (unfinished)

Author: antonilol

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

@@ -47,7 +47,7 @@ pub use self::iter::Iter;
 
 mod iter;
 
-use self::spec_extend::SpecExtend;
+use self::spec_extend::{SpecExtend, SpecExtendFront};
 
 mod spec_extend;
 
@@ -176,6 +176,21 @@ impl<T, A: Allocator> VecDeque<T, A> {
         self.len += 1;
     }
 
+    /// Prepends an element to the buffer.
+    ///
+    /// # Safety
+    ///
+    /// May only be called if `deque.len() < deque.capacity()`
+    #[inline]
+    unsafe fn push_front_unchecked(&mut self, element: T) {
+        // SAFETY: Because of the precondition, it's guaranteed that there is space
+        // in the logical array after the last element.
+        unsafe { self.buffer_write(self.head, element) };
+        self.head = self.wrap_sub(self.head, 1);
+        // This can't overflow because `deque.len() < deque.capacity() <= usize::MAX`.
+        self.len += 1;
+    }
+
     /// Moves an element out of the buffer
     #[inline]
     unsafe fn buffer_read(&mut self, off: usize) -> T {
@@ -1968,6 +1983,24 @@ impl<T, A: Allocator> VecDeque<T, A> {
         unsafe { self.buffer_write(self.to_physical_idx(len), value) }
     }
 
+    /// Prepends all elements from the iterator to the front of the deque, as if [`push_front`][VecDeque::push_front] was called with the elements of the iterator.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(deque_extend_front)]
+    /// use std::collections::VecDeque;
+    ///
+    /// let mut d = VecDeque::from([4, 5, 6]);
+    /// d.extend_front([3, 2, 1]);
+    /// assert_eq!(deque, [1, 2, 3, 4, 5, 6]);
+    /// ```
+    #[unstable(feature = "deque_extend_front", issue = "none")]
+    #[track_caller]
+    pub fn extend_front<I: IntoIterator<Item = T>>(&mut self, iter: I) {
+        <Self as SpecExtendFront<T, I::IntoIter>>::spec_extend_front(self, iter.into_iter());
+    }
+
     #[inline]
     fn is_contiguous(&self) -> bool {
         // Do the calculation like this to avoid overflowing if len + head > usize::MAX

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

@@ -1,3 +1,5 @@
+#[cfg(not(test))]
+use core::iter::Rev;
 use core::iter::TrustedLen;
 use core::slice;
 
@@ -120,3 +122,58 @@ where
         }
     }
 }
+
+// Specialization trait used for VecDeque::extend_front
+pub(super) trait SpecExtendFront<T, I> {
+    #[track_caller]
+    fn spec_extend_front(&mut self, iter: I);
+}
+
+impl<T, I, A: Allocator> SpecExtendFront<T, I> for VecDeque<T, A>
+where
+    I: Iterator<Item = T>,
+{
+    #[track_caller]
+    default fn spec_extend_front(&mut self, mut iter: I) {
+        // This function should be the moral equivalent of:
+        //
+        // for item in iter {
+        //     self.push_front(item);
+        // }
+
+        while let Some(element) = iter.next() {
+            let (lower, _) = iter.size_hint();
+            self.reserve(lower.saturating_add(1));
+
+            // SAFETY: We just reserved space for at least one element.
+            unsafe { self.push_front_unchecked(element) };
+
+            // Inner loop to avoid repeatedly calling `reserve`.
+            while self.len < self.capacity() {
+                let Some(element) = iter.next() else {
+                    return;
+                };
+                // SAFETY: The loop condition guarantees that `self.len() < self.capacity()`.
+                unsafe { self.push_front_unchecked(element) };
+            }
+        }
+    }
+}
+
+#[cfg(not(test))]
+impl<T, A: Allocator> SpecExtendFront<T, Rev<vec::IntoIter<T>>> for VecDeque<T, A> {
+    #[track_caller]
+    fn spec_extend_front(&mut self, iterator: Rev<vec::IntoIter<T>>) {
+        let mut iterator = iterator.into_inner();
+
+        let slice = iterator.as_slice();
+        self.reserve(slice.len());
+
+        unsafe {
+            self.head = self.wrap_sub(self.head, slice.len());
+            self.copy_slice(self.head, slice);
+            self.len += slice.len();
+        }
+        iterator.forget_remaining_elements();
+    }
+}

library/alloc/src/lib.rs

@@ -139,6 +139,7 @@
 #![feature(ptr_alignment_type)]
 #![feature(ptr_internals)]
 #![feature(ptr_metadata)]
+#![feature(rev_into_inner)]
 #![feature(set_ptr_value)]
 #![feature(sized_type_properties)]
 #![feature(slice_from_ptr_range)]