Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add missing urls and small nits #39513

Closed
wants to merge 1 commit into from
Closed

Add missing urls and small nits #39513

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 58 additions & 25 deletions src/libcollections/vec_deque.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,15 @@ const MAXIMUM_ZST_CAPACITY: usize = 1 << (64 - 1); // Largest possible power of
/// `VecDeque` is a growable ring buffer, which can be used as a double-ended
/// queue efficiently.
///
/// The "default" usage of this type as a queue is to use `push_back` to add to
/// the queue, and `pop_front` to remove from the queue. `extend` and `append`
/// The "default" usage of this type as a queue is to use [`push_back`] to add to
/// the queue, and [`pop_front`] to remove from the queue. [`extend`] and [`append`]
/// push onto the back in this manner, and iterating over `VecDeque` goes front
/// to back.
///
/// [`push_back`]: #method.push_back
/// [`pop_front`]: #method.pop_front
/// [`extend`]: #method.extend
/// [`append`]: #method.append
#[stable(feature = "rust1", since = "1.0.0")]
pub struct VecDeque<T> {
// tail and head are pointers into the buffer. Tail always points
Expand Down Expand Up @@ -92,13 +97,13 @@ impl<T> Default for VecDeque<T> {
}

impl<T> VecDeque<T> {
/// Marginally more convenient
/// Marginally more convenient.
#[inline]
fn ptr(&self) -> *mut T {
self.buf.ptr()
}

/// Marginally more convenient
/// Marginally more convenient.
#[inline]
fn cap(&self) -> usize {
if mem::size_of::<T>() == 0 {
Expand All @@ -109,19 +114,19 @@ impl<T> VecDeque<T> {
}
}

/// Turn ptr into a slice
/// Turn ptr into a slice.
#[inline]
unsafe fn buffer_as_slice(&self) -> &[T] {
slice::from_raw_parts(self.ptr(), self.cap())
}

/// Turn ptr into a mut slice
/// Turn ptr into a mut slice.
#[inline]
unsafe fn buffer_as_mut_slice(&mut self) -> &mut [T] {
slice::from_raw_parts_mut(self.ptr(), self.cap())
}

/// Moves an element out of the buffer
/// Moves an element out of the buffer.
#[inline]
unsafe fn buffer_read(&mut self, off: usize) -> T {
ptr::read(self.ptr().offset(off as isize))
Expand All @@ -133,7 +138,7 @@ impl<T> VecDeque<T> {
ptr::write(self.ptr().offset(off as isize), value);
}

/// Returns true if and only if the buffer is at capacity
/// Returns true if and only if the buffer is at capacity.
#[inline]
fn is_full(&self) -> bool {
self.cap() - self.len() == 1
Expand Down Expand Up @@ -506,12 +511,15 @@ impl<T> VecDeque<T> {
/// given `VecDeque`. 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
/// capacity can not be relied upon to be precisely minimal. Prefer [`reserve`] if future
/// insertions are expected.
///
/// # Panics
///
/// Panics if the new capacity overflows `usize`.
/// Panics if the new capacity overflows [`usize`].
///
/// [`reserve`]: #method.reserve
/// [`usize`]: ../../std/primitive.usize.html
///
/// # Examples
///
Expand All @@ -532,7 +540,9 @@ impl<T> VecDeque<T> {
///
/// # Panics
///
/// Panics if the new capacity overflows `usize`.
/// Panics if the new capacity overflows [`usize`].
///
/// [`usize`]: ../../std/primitive.usize.html
///
/// # Examples
///
Expand Down Expand Up @@ -788,7 +798,7 @@ impl<T> VecDeque<T> {
count(self.tail, self.head, self.cap())
}

/// Returns true if the buffer contains no elements
/// Returns true if the buffer contains no elements.
///
/// # Examples
///
Expand All @@ -812,14 +822,17 @@ impl<T> VecDeque<T> {
/// consumed until the end.
///
/// Note 2: It is unspecified how many elements are removed from the deque,
/// if the `Drain` value is not dropped, but the borrow it holds expires
/// (eg. due to mem::forget).
/// if the [`Drain`] value is not dropped, but the borrow it holds expires
/// (eg. due to [`mem::forget`]).
///
/// # 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.
///
/// [`Drain`]: ../../std/collections/vec_deque/struct.Drain.html
/// [`mem::forget`]: ../../std/mem/fn.forget.html
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -941,9 +954,11 @@ impl<T> VecDeque<T> {
a.contains(x) || b.contains(x)
}

/// Provides a reference to the front element, or `None` if the sequence is
/// Provides a reference to the front element, or [`None`] if the sequence is
/// empty.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand All @@ -965,9 +980,11 @@ impl<T> VecDeque<T> {
}
}

/// Provides a mutable reference to the front element, or `None` if the
/// Provides a mutable reference to the front element, or [`None`] if the
/// sequence is empty.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand All @@ -993,9 +1010,11 @@ impl<T> VecDeque<T> {
}
}

/// Provides a reference to the back element, or `None` if the sequence is
/// Provides a reference to the back element, or [`None`] if the sequence is
/// empty.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand All @@ -1017,9 +1036,11 @@ impl<T> VecDeque<T> {
}
}

/// Provides a mutable reference to the back element, or `None` if the
/// Provides a mutable reference to the back element, or [`None`] if the
/// sequence is empty.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand All @@ -1046,9 +1067,11 @@ impl<T> VecDeque<T> {
}
}

/// Removes the first element and returns it, or `None` if the sequence is
/// Removes the first element and returns it, or [`None`] if the sequence is
/// empty.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -1131,9 +1154,11 @@ impl<T> VecDeque<T> {
unsafe { self.buffer_write(head, value) }
}

/// Removes the last element from a buffer and returns it, or `None` if
/// Removes the last element from a buffer and returns it, or [`None`] if
/// it is empty.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -1166,10 +1191,12 @@ impl<T> VecDeque<T> {
///
/// This does not preserve ordering, but is O(1).
///
/// Returns `None` if `index` is out of bounds.
/// Returns [`None`] if `index` is out of bounds.
///
/// Element at index 0 is the front of the queue.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -1201,10 +1228,12 @@ impl<T> VecDeque<T> {
///
/// This does not preserve ordering, but is O(1).
///
/// Returns `None` if `index` is out of bounds.
/// Returns [`None`] if `index` is out of bounds.
///
/// Element at index 0 is the front of the queue.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -1238,7 +1267,7 @@ impl<T> VecDeque<T> {
///
/// # Panics
///
/// Panics if `index` is greater than `VecDeque`'s length
/// Panics if `index` is greater than `VecDeque`'s length.
///
/// # Examples
///
Expand Down Expand Up @@ -1463,10 +1492,12 @@ impl<T> VecDeque<T> {
/// Removes and returns the element at `index` from the `VecDeque`.
/// 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.
/// Returns [`None`] if `index` is out of bounds.
///
/// Element at index 0 is the front of the queue.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -1709,7 +1740,9 @@ impl<T> VecDeque<T> {
///
/// # Panics
///
/// Panics if the new number of elements in self overflows a `usize`.
/// Panics if the new number of elements in self overflows a [`usize`].
///
/// [`usize`]: ../../std/primitive.usize.html
///
/// # Examples
///
Expand Down
10 changes: 8 additions & 2 deletions src/libstd/collections/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
//! processing. They are exceptionally good at doing what they do. All the other
//! collections in the standard library have specific use cases where they are
//! the optimal choice, but these cases are borderline *niche* in comparison.
//! Even when `Vec` and `HashMap` are technically suboptimal, they're probably a
//! Even when [`Vec`] and [`HashMap`] are technically suboptimal, they're probably a
//! good enough choice to get started.
//!
//! Rust's collections can be grouped into four major categories:
Expand All @@ -37,6 +37,7 @@
//! individual collections can be found on their own documentation pages.
//!
//! ### Use a `Vec` when:
//!
//! * You want to collect items up to be processed or sent elsewhere later, and
//! don't care about any properties of the actual values being stored.
//! * You want a sequence of elements in a particular order, and will only be
Expand All @@ -46,31 +47,36 @@
//! * You want a heap-allocated array.
//!
//! ### Use a `VecDeque` when:
//!
//! * You want a [`Vec`] that supports efficient insertion at both ends of the
//! sequence.
//! * You want a queue.
//! * You want a double-ended queue (deque).
//!
//! ### Use a `LinkedList` when:
//!
//! * You want a [`Vec`] or [`VecDeque`] of unknown size, and can't tolerate
//! amortization.
//! * You want to efficiently split and append lists.
//! * You are *absolutely* certain you *really*, *truly*, want a doubly linked
//! list.
//!
//! ### Use a `HashMap` when:
//!
//! * You want to associate arbitrary keys with an arbitrary value.
//! * You want a cache.
//! * You want a map, with no extra functionality.
//!
//! ### Use a `BTreeMap` when:
//!
//! * You're interested in what the smallest or largest key-value pair is.
//! * You want to find the largest or smallest key that is smaller or larger
//! than something.
//! * You want to be able to get all of the entries in order on-demand.
//! * You want a sorted map.
//!
//! ### Use the `Set` variant of any of these `Map`s when:
//!
//! * You just want to remember which keys you've seen.
//! * There is no meaningful value to associate with your keys.
//! * You just want a set.
Expand Down Expand Up @@ -451,7 +457,7 @@ pub mod hash_map {
#[stable(feature = "rust1", since = "1.0.0")]
pub mod hash_set {
//! An implementation of a hash set using the underlying representation of a
//! HashMap where the value is ().
//! `HashMap` where the value is ().
#[stable(feature = "rust1", since = "1.0.0")]
pub use super::hash::set::*;
}