From 5d5359759deb935580c31c0474f2430894369f10 Mon Sep 17 00:00:00 2001 From: Stein Somers Date: Fri, 11 Feb 2022 11:55:46 +0100 Subject: [PATCH] Describe VecDeque with more consistent names --- .../alloc/src/collections/vec_deque/mod.rs | 220 +++++++++--------- 1 file changed, 110 insertions(+), 110 deletions(-) diff --git a/library/alloc/src/collections/vec_deque/mod.rs b/library/alloc/src/collections/vec_deque/mod.rs index a8a18d65585..db2ad5e8d28 100644 --- a/library/alloc/src/collections/vec_deque/mod.rs +++ b/library/alloc/src/collections/vec_deque/mod.rs @@ -1,4 +1,4 @@ -//! A double-ended queue implemented with a growable ring buffer. +//! A double-ended queue (deque) implemented with a growable ring buffer. //! //! This queue has *O*(1) amortized inserts and removals from both ends of the //! container. It also has *O*(1) indexing like a vector. The contained elements @@ -156,7 +156,7 @@ fn drop(&mut self) { #[stable(feature = "rust1", since = "1.0.0")] impl Default for VecDeque { - /// Creates an empty `VecDeque`. + /// Creates an empty deque. #[inline] fn default() -> VecDeque { VecDeque::new() @@ -483,14 +483,14 @@ unsafe fn handle_capacity_increase(&mut self, old_capacity: usize) { } impl VecDeque { - /// Creates an empty `VecDeque`. + /// Creates an empty deque. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let vector: VecDeque = VecDeque::new(); + /// let deque: VecDeque = VecDeque::new(); /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] @@ -499,14 +499,14 @@ pub fn new() -> VecDeque { VecDeque::new_in(Global) } - /// Creates an empty `VecDeque` with space for at least `capacity` elements. + /// Creates an empty deque with space for at least `capacity` elements. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let vector: VecDeque = VecDeque::with_capacity(10); + /// let deque: VecDeque = VecDeque::with_capacity(10); /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] @@ -517,14 +517,14 @@ pub fn with_capacity(capacity: usize) -> VecDeque { } impl VecDeque { - /// Creates an empty `VecDeque`. + /// Creates an empty deque. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let vector: VecDeque = VecDeque::new(); + /// let deque: VecDeque = VecDeque::new(); /// ``` #[inline] #[unstable(feature = "allocator_api", issue = "32838")] @@ -532,14 +532,14 @@ pub fn new_in(alloc: A) -> VecDeque { VecDeque::with_capacity_in(INITIAL_CAPACITY, alloc) } - /// Creates an empty `VecDeque` with space for at least `capacity` elements. + /// Creates an empty deque with space for at least `capacity` elements. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let vector: VecDeque = VecDeque::with_capacity(10); + /// let deque: VecDeque = VecDeque::with_capacity(10); /// ``` #[unstable(feature = "allocator_api", issue = "32838")] pub fn with_capacity_in(capacity: usize, alloc: A) -> VecDeque { @@ -636,7 +636,7 @@ pub fn swap(&mut self, i: usize, j: usize) { unsafe { ptr::swap(self.ptr().add(ri), self.ptr().add(rj)) } } - /// Returns the number of elements the `VecDeque` can hold without + /// Returns the number of elements the deque can hold without /// reallocating. /// /// # Examples @@ -654,7 +654,7 @@ pub fn capacity(&self) -> usize { } /// Reserves the minimum capacity for exactly `additional` more elements to be inserted in the - /// given `VecDeque`. Does nothing if the capacity is already sufficient. + /// given deque. Does nothing if the capacity is already sufficient. /// /// Note that the allocator may give the collection more space than it requests. Therefore /// capacity can not be relied upon to be precisely minimal. Prefer [`reserve`] if future @@ -681,7 +681,7 @@ pub fn reserve_exact(&mut self, additional: usize) { } /// Reserves capacity for at least `additional` more elements to be inserted in the given - /// `VecDeque`. The collection may reserve more space to avoid frequent reallocations. + /// deque. The collection may reserve more space to avoid frequent reallocations. /// /// # Panics /// @@ -714,7 +714,7 @@ pub fn reserve(&mut self, additional: usize) { } /// Tries to reserve the minimum capacity for exactly `additional` more elements to - /// be inserted in the given `VecDeque`. After calling `try_reserve_exact`, + /// be inserted in the given deque. After calling `try_reserve_exact`, /// capacity will be greater than or equal to `self.len() + additional`. /// Does nothing if the capacity is already sufficient. /// @@ -756,7 +756,7 @@ pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveE } /// Tries to reserve capacity for at least `additional` more elements to be inserted - /// in the given `VecDeque`. The collection may reserve more space to avoid + /// in the given deque. The collection may reserve more space to avoid /// frequent reallocations. After calling `try_reserve`, capacity will be /// greater than or equal to `self.len() + additional`. Does nothing if /// capacity is already sufficient. @@ -805,10 +805,10 @@ pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> Ok(()) } - /// Shrinks the capacity of the `VecDeque` as much as possible. + /// Shrinks the capacity of the deque as much as possible. /// /// It will drop down as close as possible to the length but the allocator may still inform the - /// `VecDeque` that there is space for a few more elements. + /// deque that there is space for a few more elements. /// /// # Examples /// @@ -826,7 +826,7 @@ pub fn shrink_to_fit(&mut self) { self.shrink_to(0); } - /// Shrinks the capacity of the `VecDeque` with a lower bound. + /// Shrinks the capacity of the deque with a lower bound. /// /// The capacity will remain at least as large as both the length /// and the supplied value. @@ -909,10 +909,10 @@ pub fn shrink_to(&mut self, min_capacity: usize) { } } - /// Shortens the `VecDeque`, keeping the first `len` elements and dropping + /// Shortens the deque, keeping the first `len` elements and dropping /// the rest. /// - /// If `len` is greater than the `VecDeque`'s current length, this has no + /// If `len` is greater than the deque's current length, this has no /// effect. /// /// # Examples @@ -1027,10 +1027,10 @@ pub fn iter_mut(&mut self) -> IterMut<'_, T> { } /// Returns a pair of slices which contain, in order, the contents of the - /// `VecDeque`. + /// deque. /// /// If [`make_contiguous`] was previously called, all elements of the - /// `VecDeque` will be in the first slice and the second slice will be empty. + /// deque will be in the first slice and the second slice will be empty. /// /// [`make_contiguous`]: VecDeque::make_contiguous /// @@ -1039,18 +1039,18 @@ pub fn iter_mut(&mut self) -> IterMut<'_, T> { /// ``` /// use std::collections::VecDeque; /// - /// let mut vector = VecDeque::new(); + /// let mut deque = VecDeque::new(); /// - /// vector.push_back(0); - /// vector.push_back(1); - /// vector.push_back(2); + /// deque.push_back(0); + /// deque.push_back(1); + /// deque.push_back(2); /// - /// assert_eq!(vector.as_slices(), (&[0, 1, 2][..], &[][..])); + /// assert_eq!(deque.as_slices(), (&[0, 1, 2][..], &[][..])); /// - /// vector.push_front(10); - /// vector.push_front(9); + /// deque.push_front(10); + /// deque.push_front(9); /// - /// assert_eq!(vector.as_slices(), (&[9, 10][..], &[0, 1, 2][..])); + /// assert_eq!(deque.as_slices(), (&[9, 10][..], &[0, 1, 2][..])); /// ``` #[inline] #[stable(feature = "deque_extras_15", since = "1.5.0")] @@ -1062,10 +1062,10 @@ pub fn as_slices(&self) -> (&[T], &[T]) { } /// Returns a pair of slices which contain, in order, the contents of the - /// `VecDeque`. + /// deque. /// /// If [`make_contiguous`] was previously called, all elements of the - /// `VecDeque` will be in the first slice and the second slice will be empty. + /// deque will be in the first slice and the second slice will be empty. /// /// [`make_contiguous`]: VecDeque::make_contiguous /// @@ -1074,17 +1074,17 @@ pub fn as_slices(&self) -> (&[T], &[T]) { /// ``` /// use std::collections::VecDeque; /// - /// let mut vector = VecDeque::new(); + /// let mut deque = VecDeque::new(); /// - /// vector.push_back(0); - /// vector.push_back(1); + /// deque.push_back(0); + /// deque.push_back(1); /// - /// vector.push_front(10); - /// vector.push_front(9); + /// deque.push_front(10); + /// deque.push_front(9); /// - /// vector.as_mut_slices().0[0] = 42; - /// vector.as_mut_slices().1[0] = 24; - /// assert_eq!(vector.as_slices(), (&[42, 10][..], &[24, 1][..])); + /// deque.as_mut_slices().0[0] = 42; + /// deque.as_mut_slices().1[0] = 24; + /// assert_eq!(deque.as_slices(), (&[42, 10][..], &[24, 1][..])); /// ``` #[inline] #[stable(feature = "deque_extras_15", since = "1.5.0")] @@ -1097,34 +1097,34 @@ pub fn as_mut_slices(&mut self) -> (&mut [T], &mut [T]) { } } - /// Returns the number of elements in the `VecDeque`. + /// Returns the number of elements in the deque. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let mut v = VecDeque::new(); - /// assert_eq!(v.len(), 0); - /// v.push_back(1); - /// assert_eq!(v.len(), 1); + /// let mut deque = VecDeque::new(); + /// assert_eq!(deque.len(), 0); + /// deque.push_back(1); + /// assert_eq!(deque.len(), 1); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn len(&self) -> usize { count(self.tail, self.head, self.cap()) } - /// Returns `true` if the `VecDeque` is empty. + /// Returns `true` if the deque is empty. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let mut v = VecDeque::new(); - /// assert!(v.is_empty()); - /// v.push_front(1); - /// assert!(!v.is_empty()); + /// let mut deque = VecDeque::new(); + /// assert!(deque.is_empty()); + /// deque.push_front(1); + /// assert!(!deque.is_empty()); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn is_empty(&self) -> bool { @@ -1141,24 +1141,24 @@ fn range_tail_head(&self, range: R) -> (usize, usize) (tail, head) } - /// Creates an iterator that covers the specified range in the `VecDeque`. + /// Creates an iterator that covers the specified range in the deque. /// /// # Panics /// /// Panics if the starting point is greater than the end point or if - /// the end point is greater than the length of the vector. + /// the end point is greater than the length of the deque. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let v: VecDeque<_> = [1, 2, 3].into(); - /// let range = v.range(2..).copied().collect::>(); + /// let deque: VecDeque<_> = [1, 2, 3].into(); + /// let range = deque.range(2..).copied().collect::>(); /// assert_eq!(range, [3]); /// /// // A full range covers all contents - /// let all = v.range(..); + /// let all = deque.range(..); /// assert_eq!(all.len(), 3); /// ``` #[inline] @@ -1176,29 +1176,29 @@ pub fn range(&self, range: R) -> Iter<'_, T> } } - /// Creates an iterator that covers the specified mutable range in the `VecDeque`. + /// Creates an iterator that covers the specified mutable range in the deque. /// /// # Panics /// /// Panics if the starting point is greater than the end point or if - /// the end point is greater than the length of the vector. + /// the end point is greater than the length of the deque. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let mut v: VecDeque<_> = [1, 2, 3].into(); - /// for v in v.range_mut(2..) { + /// let mut deque: VecDeque<_> = [1, 2, 3].into(); + /// for v in deque.range_mut(2..) { /// *v *= 2; /// } - /// assert_eq!(v, [1, 2, 6]); + /// assert_eq!(deque, [1, 2, 6]); /// /// // A full range covers all contents - /// for v in v.range_mut(..) { + /// for v in deque.range_mut(..) { /// *v *= 2; /// } - /// assert_eq!(v, [2, 4, 12]); + /// assert_eq!(deque, [2, 4, 12]); /// ``` #[inline] #[stable(feature = "deque_range", since = "1.51.0")] @@ -1216,7 +1216,7 @@ pub fn range_mut(&mut self, range: R) -> IterMut<'_, T> } /// Creates a draining iterator that removes the specified range in the - /// `VecDeque` and yields the removed items. + /// deque and yields the removed items. /// /// Note 1: The element range is removed even if the iterator is not /// consumed until the end. @@ -1228,21 +1228,21 @@ pub fn range_mut(&mut self, range: R) -> IterMut<'_, T> /// # Panics /// /// Panics if the starting point is greater than the end point or if - /// the end point is greater than the length of the vector. + /// the end point is greater than the length of the deque. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let mut v: VecDeque<_> = [1, 2, 3].into(); - /// let drained = v.drain(2..).collect::>(); + /// let mut deque: VecDeque<_> = [1, 2, 3].into(); + /// let drained = deque.drain(2..).collect::>(); /// assert_eq!(drained, [3]); - /// assert_eq!(v, [1, 2]); + /// assert_eq!(deque, [1, 2]); /// /// // A full range clears all contents - /// v.drain(..); - /// assert!(v.is_empty()); + /// deque.drain(..); + /// assert!(deque.is_empty()); /// ``` #[inline] #[stable(feature = "drain", since = "1.6.0")] @@ -1297,17 +1297,17 @@ pub fn drain(&mut self, range: R) -> Drain<'_, T, A> unsafe { Drain::new(drain_head, head, iter, deque) } } - /// Clears the `VecDeque`, removing all values. + /// Clears the deque, removing all values. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// - /// let mut v = VecDeque::new(); - /// v.push_back(1); - /// v.clear(); - /// assert!(v.is_empty()); + /// let mut deque = VecDeque::new(); + /// deque.push_back(1); + /// deque.clear(); + /// assert!(deque.is_empty()); /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] @@ -1315,7 +1315,7 @@ pub fn clear(&mut self) { self.truncate(0); } - /// Returns `true` if the `VecDeque` contains an element equal to the + /// Returns `true` if the deque contains an element equal to the /// given value. /// /// # Examples @@ -1323,13 +1323,13 @@ pub fn clear(&mut self) { /// ``` /// use std::collections::VecDeque; /// - /// let mut vector: VecDeque = VecDeque::new(); + /// let mut deque: VecDeque = VecDeque::new(); /// - /// vector.push_back(0); - /// vector.push_back(1); + /// deque.push_back(0); + /// deque.push_back(1); /// - /// assert_eq!(vector.contains(&1), true); - /// assert_eq!(vector.contains(&10), false); + /// assert_eq!(deque.contains(&1), true); + /// assert_eq!(deque.contains(&10), false); /// ``` #[stable(feature = "vec_deque_contains", since = "1.12.0")] pub fn contains(&self, x: &T) -> bool @@ -1340,7 +1340,7 @@ pub fn contains(&self, x: &T) -> bool a.contains(x) || b.contains(x) } - /// Provides a reference to the front element, or `None` if the `VecDeque` is + /// Provides a reference to the front element, or `None` if the deque is /// empty. /// /// # Examples @@ -1361,7 +1361,7 @@ pub fn front(&self) -> Option<&T> { } /// Provides a mutable reference to the front element, or `None` if the - /// `VecDeque` is empty. + /// deque is empty. /// /// # Examples /// @@ -1384,7 +1384,7 @@ pub fn front_mut(&mut self) -> Option<&mut T> { self.get_mut(0) } - /// Provides a reference to the back element, or `None` if the `VecDeque` is + /// Provides a reference to the back element, or `None` if the deque is /// empty. /// /// # Examples @@ -1405,7 +1405,7 @@ pub fn back(&self) -> Option<&T> { } /// Provides a mutable reference to the back element, or `None` if the - /// `VecDeque` is empty. + /// deque is empty. /// /// # Examples /// @@ -1428,7 +1428,7 @@ pub fn back_mut(&mut self) -> Option<&mut T> { self.get_mut(self.len().wrapping_sub(1)) } - /// Removes the first element and returns it, or `None` if the `VecDeque` is + /// Removes the first element and returns it, or `None` if the deque is /// empty. /// /// # Examples @@ -1455,7 +1455,7 @@ pub fn pop_front(&mut self) -> Option { } } - /// Removes the last element from the `VecDeque` and returns it, or `None` if + /// Removes the last element from the deque and returns it, or `None` if /// it is empty. /// /// # Examples @@ -1480,7 +1480,7 @@ pub fn pop_back(&mut self) -> Option { } } - /// Prepends an element to the `VecDeque`. + /// Prepends an element to the deque. /// /// # Examples /// @@ -1505,7 +1505,7 @@ pub fn push_front(&mut self, value: T) { } } - /// Appends an element to the back of the `VecDeque`. + /// Appends an element to the back of the deque. /// /// # Examples /// @@ -1535,7 +1535,7 @@ fn is_contiguous(&self) -> bool { self.tail <= self.head } - /// Removes an element from anywhere in the `VecDeque` and returns it, + /// Removes an element from anywhere in the deque and returns it, /// replacing it with the first element. /// /// This does not preserve ordering, but is *O*(1). @@ -1570,8 +1570,8 @@ pub fn swap_remove_front(&mut self, index: usize) -> Option { self.pop_front() } - /// Removes an element from anywhere in the `VecDeque` and returns it, replacing it with the - /// last element. + /// Removes an element from anywhere in the deque and returns it, + /// replacing it with the last element. /// /// This does not preserve ordering, but is *O*(1). /// @@ -1605,14 +1605,14 @@ pub fn swap_remove_back(&mut self, index: usize) -> Option { self.pop_back() } - /// Inserts an element at `index` within the `VecDeque`, shifting all elements with indices - /// greater than or equal to `index` towards the back. + /// Inserts an element at `index` within the deque, shifting all elements + /// with indices greater than or equal to `index` towards the back. /// /// Element at index 0 is the front of the queue. /// /// # Panics /// - /// Panics if `index` is greater than `VecDeque`'s length + /// Panics if `index` is greater than deque's length /// /// # Examples /// @@ -1829,7 +1829,7 @@ pub fn insert(&mut self, index: usize, value: T) { } } - /// Removes and returns the element at `index` from the `VecDeque`. + /// Removes and returns the element at `index` from the deque. /// Whichever end is closer to the removal point will be moved to make /// room, and all the affected elements will be moved to new positions. /// Returns `None` if `index` is out of bounds. @@ -2007,10 +2007,10 @@ pub fn remove(&mut self, index: usize) -> Option { elem } - /// Splits the `VecDeque` into two at the given index. + /// Splits the deque into two at the given index. /// /// Returns a newly allocated `VecDeque`. `self` contains elements `[0, at)`, - /// and the returned `VecDeque` contains elements `[at, len)`. + /// and the returned deque contains elements `[at, len)`. /// /// Note that the capacity of `self` does not change. /// @@ -2227,7 +2227,7 @@ fn grow(&mut self) { debug_assert!(!self.is_full()); } - /// Modifies the `VecDeque` in-place so that `len()` is equal to `new_len`, + /// Modifies the deque in-place so that `len()` is equal to `new_len`, /// either by removing excess elements from the back or by appending /// elements generated by calling `generator` to the back. /// @@ -2272,7 +2272,7 @@ pub fn resize_with(&mut self, new_len: usize, generator: impl FnMut() -> T) { /// /// Once the internal storage is contiguous, the [`as_slices`] and /// [`as_mut_slices`] methods will return the entire contents of the - /// `VecDeque` in a single slice. + /// deque in a single slice. /// /// [`as_slices`]: VecDeque::as_slices /// [`as_mut_slices`]: VecDeque::as_mut_slices @@ -2524,7 +2524,7 @@ unsafe fn rotate_right_inner(&mut self, k: usize) { } } - /// Binary searches this sorted `VecDeque` for a given element. + /// Binary searches the sorted deque for a given element. /// /// If the value is found then [`Result::Ok`] is returned, containing the /// index of the matching element. If there are multiple matches, then any @@ -2556,7 +2556,7 @@ unsafe fn rotate_right_inner(&mut self, k: usize) { /// assert!(matches!(r, Ok(1..=4))); /// ``` /// - /// If you want to insert an item to a sorted `VecDeque`, while maintaining + /// If you want to insert an item to a sorted deque, while maintaining /// sort order: /// /// ``` @@ -2577,12 +2577,12 @@ pub fn binary_search(&self, x: &T) -> Result self.binary_search_by(|e| e.cmp(x)) } - /// Binary searches this sorted `VecDeque` with a comparator function. + /// Binary searches the sorted deque with a comparator function. /// /// The comparator function should implement an order consistent - /// with the sort order of the underlying `VecDeque`, returning an - /// order code that indicates whether its argument is `Less`, - /// `Equal` or `Greater` than the desired target. + /// with the sort order of the deque, returning an order code that + /// indicates whether its argument is `Less`, `Equal` or `Greater` + /// than the desired target. /// /// If the value is found then [`Result::Ok`] is returned, containing the /// index of the matching element. If there are multiple matches, then any @@ -2630,9 +2630,9 @@ pub fn binary_search_by<'a, F>(&'a self, mut f: F) -> Result } } - /// Binary searches this sorted `VecDeque` with a key extraction function. + /// Binary searches the sorted deque with a key extraction function. /// - /// Assumes that the `VecDeque` is sorted by the key, for instance with + /// Assumes that the deque is sorted by the key, for instance with /// [`make_contiguous().sort_by_key()`] using the same key extraction function. /// /// If the value is found then [`Result::Ok`] is returned, containing the @@ -2687,7 +2687,7 @@ pub fn binary_search_by_key<'a, B, F>(&'a self, b: &B, mut f: F) -> Result(&self, mut pred: P) -> usize } impl VecDeque { - /// Modifies the `VecDeque` in-place so that `len()` is equal to new_len, + /// Modifies the deque in-place so that `len()` is equal to new_len, /// either by removing excess elements from the back or by appending clones of `value` /// to the back. /// @@ -2878,7 +2878,7 @@ impl IntoIterator for VecDeque { type Item = T; type IntoIter = IntoIter; - /// Consumes the `VecDeque` into a front-to-back iterator yielding elements by + /// Consumes the deque into a front-to-back iterator yielding elements by /// value. fn into_iter(self) -> IntoIter { IntoIter::new(self)