squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

Describe VecDeque with more consistent names

Browse source
This commit is contained in:
Stein Somers 2022-02-11 11:55:46 +01:00
parent 902e59057e
commit 5d5359759d
1 changed files with 110 additions and 110 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

220
library/alloc/src/collections/vec_deque/mod.rs
View file

@ -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 @@ unsafe impl<#[may_dangle] T, A: Allocator> Drop for VecDeque<T, A> {
#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Default for VecDeque<T> {
/// Creates an empty `VecDeque<T>`.
/// Creates an empty deque.
#[inline]
fn default() -> VecDeque<T> {
VecDeque::new()
@ -483,14 +483,14 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
impl<T> VecDeque<T> {
/// Creates an empty `VecDeque`.
/// Creates an empty deque.
///
/// # Examples
///
/// ```
/// use std::collections::VecDeque;
///
/// let vector: VecDeque<u32> = VecDeque::new();
/// let deque: VecDeque<u32> = VecDeque::new();
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
@ -499,14 +499,14 @@ impl<T> VecDeque<T> {
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<u32> = VecDeque::with_capacity(10);
/// let deque: VecDeque<u32> = VecDeque::with_capacity(10);
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
@ -517,14 +517,14 @@ impl<T> VecDeque<T> {
}
impl<T, A: Allocator> VecDeque<T, A> {
/// Creates an empty `VecDeque`.
/// Creates an empty deque.
///
/// # Examples
///
/// ```
/// use std::collections::VecDeque;
///
/// let vector: VecDeque<u32> = VecDeque::new();
/// let deque: VecDeque<u32> = VecDeque::new();
/// ```
#[inline]
#[unstable(feature = "allocator_api", issue = "32838")]
@ -532,14 +532,14 @@ impl<T, A: Allocator> VecDeque<T, A> {
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<u32> = VecDeque::with_capacity(10);
/// let deque: VecDeque<u32> = VecDeque::with_capacity(10);
/// ```
#[unstable(feature = "allocator_api", issue = "32838")]
pub fn with_capacity_in(capacity: usize, alloc: A) -> VecDeque<T, A> {
@ -636,7 +636,7 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
/// Tries to reserve the minimum capacity for exactly `additional` more elements to
/// be inserted in the given `VecDeque<T>`. 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
/// Tries to reserve capacity for at least `additional` more elements to be inserted
/// in the given `VecDeque<T>`. 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
/// ```
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
/// ```
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
(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::<VecDeque<_>>();
/// let deque: VecDeque<_> = [1, 2, 3].into();
/// let range = deque.range(2..).copied().collect::<VecDeque<_>>();
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
/// # 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::<VecDeque<_>>();
/// let mut deque: VecDeque<_> = [1, 2, 3].into();
/// let drained = deque.drain(2..).collect::<VecDeque<_>>();
/// 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 @@ impl<T, A: Allocator> VecDeque<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 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
/// ```
/// use std::collections::VecDeque;
///
/// let mut vector: VecDeque<u32> = VecDeque::new();
/// let mut deque: VecDeque<u32> = 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
/// Provides a mutable reference to the front element, or `None` if the
/// `VecDeque` is empty.
/// deque is empty.
///
/// # Examples
///
@ -1384,7 +1384,7 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
/// Provides a mutable reference to the back element, or `None` if the
/// `VecDeque` is empty.
/// deque is empty.
///
/// # Examples
///
@ -1428,7 +1428,7 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
}
/// Prepends an element to the `VecDeque`.
/// Prepends an element to the deque.
///
/// # Examples
///
@ -1505,7 +1505,7 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
}
/// Appends an element to the back of the `VecDeque`.
/// Appends an element to the back of the deque.
///
/// # Examples
///
@ -1535,7 +1535,7 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
///
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
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 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
}
/// 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 @@ impl<T, A: Allocator> VecDeque<T, A> {
/// For example, [7, 15, 3, 5, 4, 12, 6] is a partitioned under the predicate x % 2 != 0
/// (all odd numbers are at the start, all even at the end).
///
/// If this deque is not partitioned, the returned result is unspecified and meaningless,
/// If the deque is not partitioned, the returned result is unspecified and meaningless,
/// as this method performs a kind of binary search.
///
/// See also [`binary_search`], [`binary_search_by`], and [`binary_search_by_key`].
@ -2724,7 +2724,7 @@ impl<T, A: Allocator> VecDeque<T, A> {
}
impl<T: Clone, A: Allocator> VecDeque<T, A> {
/// 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<T, A: Allocator> IntoIterator for VecDeque<T, A> {
type Item = T;
type IntoIter = IntoIter<T, A>;
/// 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<T, A> {
IntoIter::new(self)