Rollup merge of #92977 - kornelski:popdoc, r=dtolnay

Docs: recommend VecDeque instead of Vec::remove(0)

Suggestion based on a [discussion](https://internals.rust-lang.org/t/should-vec-have-a-try-remove-mut-self-usize-option-t-function/15964/9?u=kornel) where user needlessly struggled with `remove(0)` and accidentally created a quadratic cost.

1 files changed, 9 insertions, 1 deletions

diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs
index 78f989e730d..16ba5c008cd 100644
--- a/library/alloc/src/vec/mod.rs
+++ b/library/alloc/src/vec/mod.rs
@@ -1372,9 +1372,12 @@ impl<T, A: Allocator> Vec<T, A> {
     ///
     /// Note: Because this shifts over the remaining elements, it has a
     /// worst-case performance of *O*(*n*). If you don't need the order of elements
-    /// to be preserved, use [`swap_remove`] instead.
+    /// to be preserved, use [`swap_remove`] instead. If you'd like to remove
+    /// elements from the beginning of the `Vec`, consider using
+    /// [`VecDeque::pop_front`] instead.
     ///
     /// [`swap_remove`]: Vec::swap_remove
+    /// [`VecDeque::pop_front`]: crate::collections::VecDeque::pop_front
     ///
     /// # Panics
     ///
@@ -1735,6 +1738,11 @@ impl<T, A: Allocator> Vec<T, A> {
     /// Removes the last element from a vector and returns it, or [`None`] if it
     /// is empty.
     ///
+    /// If you'd like to pop the first element, consider using
+    /// [`VecDeque::pop_front`] instead.
+    ///
+    /// [`VecDeque::pop_front`]: crate::collections::VecDeque::pop_front
+    ///
     /// # Examples
     ///
     /// ```