OpenE2K
/
rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Auto merge of #41286 - lukaramu:std-collections-docs, r=frewsxcv 

Various improvements in std::collections docs

The meat of this PR are:
* changes to (almost all?) iterator struct docs in std::collections such that they use the standard iterator boilerplate and state where they are created
* a bunch of added links (at least as much as possible given std::collections mostly being a facade and whatnot 😅)
* an example for `Bound`
* changed phrasing for some summary sentences to be less redundant as well as more consistant with others in the module

There also are various other fixes, e.g. removing parens from method names in the module docs, changing some imperatives to 3rd person, etc.

r? @steveklabnik
This commit is contained in:
bors 2017-04-15 04:46:27 +00:00
parent be1a74e4d3 2a23e6e277
commit 5f13a3b540
10 changed files with 415 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
src/libcollections/binary_heap.rs
View File

@ -20,11 +20,12 @@
//!
//! This is a larger example that implements [Dijkstra's algorithm][dijkstra]
//! to solve the [shortest path problem][sssp] on a [directed graph][dir_graph].
//! It shows how to use `BinaryHeap` with custom types.
//! It shows how to use [`BinaryHeap`] with custom types.
//!
//! [dijkstra]: http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
//! [sssp]: http://en.wikipedia.org/wiki/Shortest_path_problem
//! [dir_graph]: http://en.wikipedia.org/wiki/Directed_graph
//! [`BinaryHeap`]: struct.BinaryHeap.html
//!
//! ```
//! use std::cmp::Ordering;
@ -218,10 +219,14 @@ pub struct BinaryHeap<T> {
data: Vec<T>,
}
/// A container object that represents the result of the [`peek_mut`] method
/// on `BinaryHeap`. See its documentation for details.
/// Structure wrapping a mutable reference to the greatest item on a
/// `BinaryHeap`.
///
/// This `struct` is created by the [`peek_mut`] method on [`BinaryHeap`]. See
/// its documentation for more.
///
/// [`peek_mut`]: struct.BinaryHeap.html#method.peek_mut
/// [`BinaryHeap`]: struct.BinaryHeap.html
#[stable(feature = "binary_heap_peek_mut", since = "1.12.0")]
pub struct PeekMut<'a, T: 'a + Ord> {
heap: &'a mut BinaryHeap<T>,
@ -434,7 +439,7 @@ impl<T: Ord> BinaryHeap<T> {
/// given `BinaryHeap`. 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
@ -452,6 +457,8 @@ impl<T: Ord> BinaryHeap<T> {
/// assert!(heap.capacity() >= 100);
/// heap.push(4);
/// ```
///
/// [`reserve`]: #method.reserve
#[stable(feature = "rust1", since = "1.0.0")]
pub fn reserve_exact(&mut self, additional: usize) {
self.data.reserve_exact(additional);
@ -971,7 +978,13 @@ impl<'a, T> Drop for Hole<'a, T> {
}
}
/// `BinaryHeap` iterator.
/// An iterator over the elements of a `BinaryHeap`.
///
/// This `struct` is created by the [`iter`] method on [`BinaryHeap`]. See its
/// documentation for more.
///
/// [`iter`]: struct.BinaryHeap.html#method.iter
/// [`BinaryHeap`]: struct.BinaryHeap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a, T: 'a> {
iter: slice::Iter<'a, T>,
@ -1027,7 +1040,13 @@ impl<'a, T> ExactSizeIterator for Iter<'a, T> {
#[unstable(feature = "fused", issue = "35602")]
impl<'a, T> FusedIterator for Iter<'a, T> {}
/// An iterator that moves out of a `BinaryHeap`.
/// An owning iterator over the elements of a `BinaryHeap`.
///
/// This `struct` is created by the [`into_iter`] method on [`BinaryHeap`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`into_iter`]: struct.BinaryHeap.html#method.into_iter
/// [`BinaryHeap`]: struct.BinaryHeap.html
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Clone)]
pub struct IntoIter<T> {
@ -1076,7 +1095,13 @@ impl<T> ExactSizeIterator for IntoIter<T> {
#[unstable(feature = "fused", issue = "35602")]
impl<T> FusedIterator for IntoIter<T> {}
/// An iterator that drains a `BinaryHeap`.
/// A draining iterator over the elements of a `BinaryHeap`.
///
/// This `struct` is created by the [`drain`] method on [`BinaryHeap`]. See its
/// documentation for more.
///
/// [`drain`]: struct.BinaryHeap.html#method.drain
/// [`BinaryHeap`]: struct.BinaryHeap.html
#[stable(feature = "drain", since = "1.6.0")]
#[derive(Debug)]
pub struct Drain<'a, T: 'a> {

77
src/libcollections/btree/map.rs
View File

@ -262,7 +262,13 @@ impl<K, Q: ?Sized> super::Recover<Q> for BTreeMap<K, ()>
}
}
/// An iterator over a `BTreeMap`'s entries.
/// An iterator over the entries of a `BTreeMap`.
///
/// This `struct` is created by the [`iter`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`iter`]: struct.BTreeMap.html#method.iter
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a, K: 'a, V: 'a> {
range: Range<'a, K, V>,
@ -276,7 +282,13 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for Iter<'a, K, V> {
}
}
/// A mutable iterator over a `BTreeMap`'s entries.
/// A mutable iterator over the entries of a `BTreeMap`.
///
/// This `struct` is created by the [`iter_mut`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`iter_mut`]: struct.BTreeMap.html#method.iter_mut
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct IterMut<'a, K: 'a, V: 'a> {
@ -284,7 +296,13 @@ pub struct IterMut<'a, K: 'a, V: 'a> {
length: usize,
}
/// An owning iterator over a `BTreeMap`'s entries.
/// An owning iterator over the entries of a `BTreeMap`.
///
/// This `struct` is created by the [`into_iter`] method on [`BTreeMap`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`into_iter`]: struct.BTreeMap.html#method.into_iter
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IntoIter<K, V> {
front: Handle<NodeRef<marker::Owned, K, V, marker::Leaf>, marker::Edge>,
@ -303,7 +321,13 @@ impl<K: fmt::Debug, V: fmt::Debug> fmt::Debug for IntoIter<K, V> {
}
}
/// An iterator over a `BTreeMap`'s keys.
/// An iterator over the keys of a `BTreeMap`.
///
/// This `struct` is created by the [`keys`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`keys`]: struct.BTreeMap.html#method.keys
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Keys<'a, K: 'a, V: 'a> {
inner: Iter<'a, K, V>,
@ -316,7 +340,13 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for Keys<'a, K, V> {
}
}
/// An iterator over a `BTreeMap`'s values.
/// An iterator over the values of a `BTreeMap`.
///
/// This `struct` is created by the [`values`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`values`]: struct.BTreeMap.html#method.values
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Values<'a, K: 'a, V: 'a> {
inner: Iter<'a, K, V>,
@ -329,14 +359,26 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for Values<'a, K, V>
}
}
/// A mutable iterator over a `BTreeMap`'s values.
/// A mutable iterator over the values of a `BTreeMap`.
///
/// This `struct` is created by the [`values_mut`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`values_mut`]: struct.BTreeMap.html#method.values_mut
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "map_values_mut", since = "1.10.0")]
#[derive(Debug)]
pub struct ValuesMut<'a, K: 'a, V: 'a> {
inner: IterMut<'a, K, V>,
}
/// An iterator over a sub-range of `BTreeMap`'s entries.
/// An iterator over a sub-range of entries in a `BTreeMap`.
///
/// This `struct` is created by the [`range`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`range`]: struct.BTreeMap.html#method.range
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "btree_range", since = "1.17.0")]
pub struct Range<'a, K: 'a, V: 'a> {
front: Handle<NodeRef<marker::Immut<'a>, K, V, marker::Leaf>, marker::Edge>,
@ -350,7 +392,13 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for Range<'a, K, V>
}
}
/// A mutable iterator over a sub-range of `BTreeMap`'s entries.
/// A mutable iterator over a sub-range of entries in a `BTreeMap`.
///
/// This `struct` is created by the [`range_mut`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`range_mut`]: struct.BTreeMap.html#method.range_mut
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "btree_range", since = "1.17.0")]
pub struct RangeMut<'a, K: 'a, V: 'a> {
front: Handle<NodeRef<marker::Mut<'a>, K, V, marker::Leaf>, marker::Edge>,
@ -372,18 +420,19 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for RangeMut<'a, K,
}
/// A view into a single entry in a map, which may either be vacant or occupied.
/// This enum is constructed from the [`entry`] method on [`BTreeMap`].
///
/// This `enum` is constructed from the [`entry`] method on [`BTreeMap`].
///
/// [`BTreeMap`]: struct.BTreeMap.html
/// [`entry`]: struct.BTreeMap.html#method.entry
#[stable(feature = "rust1", since = "1.0.0")]
pub enum Entry<'a, K: 'a, V: 'a> {
/// A vacant `Entry`
/// A vacant entry.
#[stable(feature = "rust1", since = "1.0.0")]
Vacant(#[stable(feature = "rust1", since = "1.0.0")]
VacantEntry<'a, K, V>),
/// An occupied `Entry`
/// An occupied entry.
#[stable(feature = "rust1", since = "1.0.0")]
Occupied(#[stable(feature = "rust1", since = "1.0.0")]
OccupiedEntry<'a, K, V>),
@ -403,7 +452,8 @@ impl<'a, K: 'a + Debug + Ord, V: 'a + Debug> Debug for Entry<'a, K, V> {
}
}
/// A vacant `Entry`. It is part of the [`Entry`] enum.
/// A view into a vacant entry in a `BTreeMap`.
/// It is part of the [`Entry`] enum.
///
/// [`Entry`]: enum.Entry.html
#[stable(feature = "rust1", since = "1.0.0")]
@ -425,7 +475,8 @@ impl<'a, K: 'a + Debug + Ord, V: 'a> Debug for VacantEntry<'a, K, V> {
}
}
/// An occupied `Entry`. It is part of the [`Entry`] enum.
/// A view into an occupied entry in a `BTreeMap`.
/// It is part of the [`Entry`] enum.
///
/// [`Entry`]: enum.Entry.html
#[stable(feature = "rust1", since = "1.0.0")]

40
src/libcollections/btree/set.rs
View File

@ -74,9 +74,10 @@ pub struct BTreeSet<T> {
map: BTreeMap<T, ()>,
}
/// An iterator over a `BTreeSet`'s items.
/// An iterator over the items of a `BTreeSet`.
///
/// This structure is created by the [`iter`] method on [`BTreeSet`].
/// This `struct` is created by the [`iter`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`iter`]: struct.BTreeSet.html#method.iter
@ -94,21 +95,23 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for Iter<'a, T> {
}
}
/// An owning iterator over a `BTreeSet`'s items.
/// An owning iterator over the items of a `BTreeSet`.
///
/// This structure is created by the `into_iter` method on [`BTreeSet`]
/// [`BTreeSet`] (provided by the `IntoIterator` trait).
/// This `struct` is created by the [`into_iter`] method on [`BTreeSet`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`into_iter`]: struct.BTreeSet.html#method.into_iter
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct IntoIter<T> {
iter: ::btree_map::IntoIter<T, ()>,
}
/// An iterator over a sub-range of `BTreeSet`'s items.
/// An iterator over a sub-range of items in a `BTreeSet`.
///
/// This structure is created by the [`range`] method on [`BTreeSet`].
/// This `struct` is created by the [`range`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`range`]: struct.BTreeSet.html#method.range
@ -118,9 +121,10 @@ pub struct Range<'a, T: 'a> {
iter: ::btree_map::Range<'a, T, ()>,
}
/// A lazy iterator producing elements in the set difference (in-order).
/// A lazy iterator producing elements in the difference of `BTreeSet`s.
///
/// This structure is created by the [`difference`] method on [`BTreeSet`].
/// This `struct` is created by the [`difference`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`difference`]: struct.BTreeSet.html#method.difference
@ -139,10 +143,10 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for Difference<'a, T> {
}
}
/// A lazy iterator producing elements in the set symmetric difference (in-order).
/// A lazy iterator producing elements in the symmetric difference of `BTreeSet`s.
///
/// This structure is created by the [`symmetric_difference`] method on
/// [`BTreeSet`].
/// This `struct` is created by the [`symmetric_difference`] method on
/// [`BTreeSet`]. See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`symmetric_difference`]: struct.BTreeSet.html#method.symmetric_difference
@ -161,9 +165,10 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for SymmetricDifference<'a, T> {
}
}
/// A lazy iterator producing elements in the set intersection (in-order).
/// A lazy iterator producing elements in the intersection of `BTreeSet`s.
///
/// This structure is created by the [`intersection`] method on [`BTreeSet`].
/// This `struct` is created by the [`intersection`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`intersection`]: struct.BTreeSet.html#method.intersection
@ -182,9 +187,10 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for Intersection<'a, T> {
}
}
/// A lazy iterator producing elements in the set union (in-order).
/// A lazy iterator producing elements in the union of `BTreeSet`s.
///
/// This structure is created by the [`union`] method on [`BTreeSet`].
/// This `struct` is created by the [`union`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`union`]: struct.BTreeSet.html#method.union
@ -728,7 +734,7 @@ impl<T> IntoIterator for BTreeSet<T> {
type Item = T;
type IntoIter = IntoIter<T>;
/// Gets an iterator for moving out the BtreeSet's contents.
/// Gets an iterator for moving out the `BTreeSet`'s contents.
///
/// # Examples
///

36
src/libcollections/lib.rs
View File

@ -135,6 +135,42 @@ mod std {
}
/// An endpoint of a range of keys.
///
/// # Examples
///
/// `Bound`s are range endpoints:
///
/// ```
/// #![feature(collections_range)]
///
/// use std::collections::range::RangeArgument;
/// use std::collections::Bound::*;
///
/// assert_eq!((..100).start(), Unbounded);
/// assert_eq!((1..12).start(), Included(&1));
/// assert_eq!((1..12).end(), Excluded(&12));
/// ```
///
/// Using a tuple of `Bound`s as an argument to [`BTreeMap::range`].
/// Note that in most cases, it's better to use range syntax (`1..5`) instead.
///
/// ```
/// use std::collections::BTreeMap;
/// use std::collections::Bound::{Excluded, Included, Unbounded};
///
/// let mut map = BTreeMap::new();
/// map.insert(3, "a");
/// map.insert(5, "b");
/// map.insert(8, "c");
///
/// for (key, value) in map.range((Excluded(3), Included(8))) {
/// println!("{}: {}", key, value);
/// }
///
/// assert_eq!(Some((&3, &"a")), map.range((Unbounded, Included(5))).next());
/// ```
///
/// [`BTreeMap::range`]: btree_map/struct.BTreeMap.html#method.range
#[stable(feature = "collections_bound", since = "1.17.0")]
#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
pub enum Bound<T> {

28
src/libcollections/linked_list.rs
View File

@ -56,7 +56,13 @@ struct Node<T> {
element: T,
}
/// An iterator over references to the elements of a `LinkedList`.
/// An iterator over the elements of a `LinkedList`.
///
/// This `struct` is created by the [`iter`] method on [`LinkedList`]. See its
/// documentation for more.
///
/// [`iter`]: struct.LinkedList.html#method.iter
/// [`LinkedList`]: struct.LinkedList.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a, T: 'a> {
head: Option<Shared<Node<T>>>,
@ -82,7 +88,13 @@ impl<'a, T> Clone for Iter<'a, T> {
}
}
/// An iterator over mutable references to the elements of a `LinkedList`.
/// A mutable iterator over the elements of a `LinkedList`.
///
/// This `struct` is created by the [`iter_mut`] method on [`LinkedList`]. See its
/// documentation for more.
///
/// [`iter_mut`]: struct.LinkedList.html#method.iter_mut
/// [`LinkedList`]: struct.LinkedList.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IterMut<'a, T: 'a> {
list: &'a mut LinkedList<T>,
@ -100,7 +112,13 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for IterMut<'a, T> {
}
}
/// An iterator over the elements of a `LinkedList`.
/// An owning iterator over the elements of a `LinkedList`.
///
/// This `struct` is created by the [`into_iter`] method on [`LinkedList`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`into_iter`]: struct.LinkedList.html#method.into_iter
/// [`LinkedList`]: struct.LinkedList.html
#[derive(Clone)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IntoIter<T> {
@ -618,12 +636,12 @@ impl<T> LinkedList<T> {
/// Splits the list into two at the given index. Returns everything after the given index,
/// including the index.
///
/// This operation should compute in O(n) time.
///
/// # Panics
///
/// Panics if `at > len`.
///
/// This operation should compute in O(n) time.
///
/// # Examples
///
/// ```

51
src/libcollections/vec_deque.rs
View File

@ -8,8 +8,7 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! `VecDeque` is a double-ended queue, which is implemented with the help of a
//! growing ring buffer.
//! A double-ended queue 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
@ -43,13 +42,17 @@ const MAXIMUM_ZST_CAPACITY: usize = 1 << (32 - 1); // Largest possible power of
#[cfg(target_pointer_width = "64")]
const MAXIMUM_ZST_CAPACITY: usize = 1 << (64 - 1); // Largest possible power of two
/// `VecDeque` is a growable ring buffer, which can be used as a double-ended
/// queue efficiently.
/// A double-ended queue implemented with a growable ring buffer.
///
/// 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
@ -506,7 +509,7 @@ 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
@ -522,6 +525,8 @@ impl<T> VecDeque<T> {
/// buf.reserve_exact(10);
/// assert!(buf.capacity() >= 11);
/// ```
///
/// [`reserve`]: #method.reserve
#[stable(feature = "rust1", since = "1.0.0")]
pub fn reserve_exact(&mut self, additional: usize) {
self.reserve(additional);
@ -1890,7 +1895,13 @@ fn count(tail: usize, head: usize, size: usize) -> usize {
(head.wrapping_sub(tail)) & (size - 1)
}
/// `VecDeque` iterator.
/// An iterator over the elements of a `VecDeque`.
///
/// This `struct` is created by the [`iter`] method on [`VecDeque`]. See its
/// documentation for more.
///
/// [`iter`]: struct.VecDeque.html#method.iter
/// [`VecDeque`]: struct.VecDeque.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a, T: 'a> {
ring: &'a [T],
@ -1971,7 +1982,13 @@ impl<'a, T> ExactSizeIterator for Iter<'a, T> {
impl<'a, T> FusedIterator for Iter<'a, T> {}
/// `VecDeque` mutable iterator.
/// A mutable iterator over the elements of a `VecDeque`.
///
/// This `struct` is created by the [`iter_mut`] method on [`VecDeque`]. See its
/// documentation for more.
///
/// [`iter_mut`]: struct.VecDeque.html#method.iter_mut
/// [`VecDeque`]: struct.VecDeque.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IterMut<'a, T: 'a> {
ring: &'a mut [T],
@ -2047,7 +2064,13 @@ impl<'a, T> ExactSizeIterator for IterMut<'a, T> {
#[unstable(feature = "fused", issue = "35602")]
impl<'a, T> FusedIterator for IterMut<'a, T> {}
/// A by-value `VecDeque` iterator
/// An owning iterator over the elements of a `VecDeque`.
///
/// This `struct` is created by the [`into_iter`] method on [`VecDeque`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`into_iter`]: struct.VecDeque.html#method.into_iter
/// [`VecDeque`]: struct.VecDeque.html
#[derive(Clone)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IntoIter<T> {
@ -2097,7 +2120,13 @@ impl<T> ExactSizeIterator for IntoIter<T> {
#[unstable(feature = "fused", issue = "35602")]
impl<T> FusedIterator for IntoIter<T> {}
/// A draining `VecDeque` iterator
/// A draining iterator over the elements of a `VecDeque`.
///
/// This `struct` is created by the [`drain`] method on [`VecDeque`]. See its
/// documentation for more.
///
/// [`drain`]: struct.VecDeque.html#method.drain
/// [`VecDeque`]: struct.VecDeque.html
#[stable(feature = "drain", since = "1.6.0")]
pub struct Drain<'a, T: 'a> {
after_tail: usize,

109
src/libstd/collections/hash/map.rs
View File

@ -215,8 +215,7 @@ const DISPLACEMENT_THRESHOLD: usize = 128;
// 1. Alfredo Viola (2005). Distributional analysis of Robin Hood linear probing
// hashing with buckets.
/// A hash map implementation which uses linear probing with Robin Hood bucket
/// stealing.
/// A hash map implemented with linear probing and Robin Hood bucket stealing.
///
/// By default, `HashMap` uses a hashing algorithm selected to provide
/// resistance against HashDoS attacks. The algorithm is randomly seeded, and a
@ -235,9 +234,8 @@ const DISPLACEMENT_THRESHOLD: usize = 128;
/// attacks such as HashDoS.
///
/// The hashing algorithm can be replaced on a per-`HashMap` basis using the
/// [`HashMap::default`], [`HashMap::with_hasher`], and
/// [`HashMap::with_capacity_and_hasher`] methods. Many alternative algorithms
/// are available on crates.io, such as the [`fnv`] crate.
/// [`default`], [`with_hasher`], and [`with_capacity_and_hasher`] methods. Many
/// alternative algorithms are available on crates.io, such as the [`fnv`] crate.
///
/// It is required that the keys implement the [`Eq`] and [`Hash`] traits, although
/// this can frequently be achieved by using `#[derive(PartialEq, Eq, Hash)]`.
@ -339,9 +337,9 @@ const DISPLACEMENT_THRESHOLD: usize = 128;
/// [`PartialEq`]: ../../std/cmp/trait.PartialEq.html
/// [`RefCell`]: ../../std/cell/struct.RefCell.html
/// [`Cell`]: ../../std/cell/struct.Cell.html
/// [`HashMap::default`]: #method.default
/// [`HashMap::with_hasher`]: #method.with_hasher
/// [`HashMap::with_capacity_and_hasher`]: #method.with_capacity_and_hasher
/// [`default`]: #method.default
/// [`with_hasher`]: #method.with_hasher
/// [`with_capacity_and_hasher`]: #method.with_capacity_and_hasher
/// [`fnv`]: https://crates.io/crates/fnv
///
/// ```
@ -373,7 +371,7 @@ const DISPLACEMENT_THRESHOLD: usize = 128;
/// }
/// ```
///
/// A HashMap with fixed list of elements can be initialized from an array:
/// A `HashMap` with fixed list of elements can be initialized from an array:
///
/// ```
/// use std::collections::HashMap;
@ -654,12 +652,13 @@ impl<K, V, S> HashMap<K, V, S>
}
}
/// Creates an empty `HashMap` with the specified capacity, using `hasher`
/// Creates an empty `HashMap` with the specified capacity, using `hash_builder`
/// to hash the keys.
///
/// The hash map will be able to hold at least `capacity` elements without
/// reallocating. If `capacity` is 0, the hash map will not allocate.
/// Warning: `hasher` is normally randomly generated, and
///
/// Warning: `hash_builder` is normally randomly generated, and
/// is designed to allow HashMaps to be resistant to attacks that
/// cause many collisions and very poor performance. Setting it
/// manually using this function can expose a DoS attack vector.
@ -686,7 +685,9 @@ impl<K, V, S> HashMap<K, V, S>
}
}
/// Returns a reference to the map's hasher.
/// Returns a reference to the map's [`BuildHasher`].
///
/// [`BuildHasher`]: ../../std/hash/trait.BuildHasher.html
#[stable(feature = "hashmap_public_hasher", since = "1.9.0")]
pub fn hasher(&self) -> &S {
&self.hash_builder
@ -849,7 +850,7 @@ impl<K, V, S> HashMap<K, V, S>
}
/// An iterator visiting all keys in arbitrary order.
/// Iterator element type is `&'a K`.
/// The iterator element type is `&'a K`.
///
/// # Examples
///
@ -871,7 +872,7 @@ impl<K, V, S> HashMap<K, V, S>
}
/// An iterator visiting all values in arbitrary order.
/// Iterator element type is `&'a V`.
/// The iterator element type is `&'a V`.
///
/// # Examples
///
@ -893,7 +894,7 @@ impl<K, V, S> HashMap<K, V, S>
}
/// An iterator visiting all values mutably in arbitrary order.
/// Iterator element type is `&'a mut V`.
/// The iterator element type is `&'a mut V`.
///
/// # Examples
///
@ -920,7 +921,7 @@ impl<K, V, S> HashMap<K, V, S>
}
/// An iterator visiting all key-value pairs in arbitrary order.
/// Iterator element type is `(&'a K, &'a V)`.
/// The iterator element type is `(&'a K, &'a V)`.
///
/// # Examples
///
@ -943,7 +944,7 @@ impl<K, V, S> HashMap<K, V, S>
/// An iterator visiting all key-value pairs in arbitrary order,
/// with mutable references to the values.
/// Iterator element type is `(&'a K, &'a mut V)`.
/// The iterator element type is `(&'a K, &'a mut V)`.
///
/// # Examples
///
@ -1333,7 +1334,13 @@ impl<'a, K, Q: ?Sized, V, S> Index<&'a Q> for HashMap<K, V, S>
}
}
/// HashMap iterator.
/// An iterator over the entries of a `HashMap`.
///
/// This `struct` is created by the [`iter`] method on [`HashMap`]. See its
/// documentation for more.
///
/// [`iter`]: struct.HashMap.html#method.iter
/// [`HashMap`]: struct.HashMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a, K: 'a, V: 'a> {
inner: table::Iter<'a, K, V>,
@ -1356,19 +1363,37 @@ impl<'a, K: Debug, V: Debug> fmt::Debug for Iter<'a, K, V> {
}
}
/// HashMap mutable values iterator.
/// A mutable iterator over the entries of a `HashMap`.
///
/// This `struct` is created by the [`iter_mut`] method on [`HashMap`]. See its
/// documentation for more.
///
/// [`iter_mut`]: struct.HashMap.html#method.iter_mut
/// [`HashMap`]: struct.HashMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IterMut<'a, K: 'a, V: 'a> {
inner: table::IterMut<'a, K, V>,
}
/// HashMap move iterator.
/// An owning iterator over the entries of a `HashMap`.
///
/// This `struct` is created by the [`into_iter`] method on [`HashMap`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`into_iter`]: struct.HashMap.html#method.into_iter
/// [`HashMap`]: struct.HashMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IntoIter<K, V> {
pub(super) inner: table::IntoIter<K, V>,
}
/// HashMap keys iterator.
/// An iterator over the keys of a `HashMap`.
///
/// This `struct` is created by the [`keys`] method on [`HashMap`]. See its
/// documentation for more.
///
/// [`keys`]: struct.HashMap.html#method.keys
/// [`HashMap`]: struct.HashMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Keys<'a, K: 'a, V: 'a> {
inner: Iter<'a, K, V>,
@ -1391,7 +1416,13 @@ impl<'a, K: Debug, V: Debug> fmt::Debug for Keys<'a, K, V> {
}
}
/// HashMap values iterator.
/// An iterator over the values of a `HashMap`.
///
/// This `struct` is created by the [`values`] method on [`HashMap`]. See its
/// documentation for more.
///
/// [`values`]: struct.HashMap.html#method.values
/// [`HashMap`]: struct.HashMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Values<'a, K: 'a, V: 'a> {
inner: Iter<'a, K, V>,
@ -1414,13 +1445,25 @@ impl<'a, K: Debug, V: Debug> fmt::Debug for Values<'a, K, V> {
}
}
/// HashMap drain iterator.
/// A draining iterator over the entries of a `HashMap`.
///
/// This `struct` is created by the [`drain`] method on [`HashMap`]. See its
/// documentation for more.
///
/// [`drain`]: struct.HashMap.html#method.drain
/// [`HashMap`]: struct.HashMap.html
#[stable(feature = "drain", since = "1.6.0")]
pub struct Drain<'a, K: 'a, V: 'a> {
pub(super) inner: table::Drain<'a, K, V>,
}
/// Mutable HashMap values iterator.
/// A mutable iterator over the values of a `HashMap`.
///
/// This `struct` is created by the [`values_mut`] method on [`HashMap`]. See its
/// documentation for more.
///
/// [`values_mut`]: struct.HashMap.html#method.values_mut
/// [`HashMap`]: struct.HashMap.html
#[stable(feature = "map_values_mut", since = "1.10.0")]
pub struct ValuesMut<'a, K: 'a, V: 'a> {
inner: IterMut<'a, K, V>,
@ -1467,19 +1510,20 @@ impl<'a, K, V> InternalEntry<K, V, &'a mut RawTable<K, V>> {
}
}
/// A view into a single location in a map, which may be vacant or occupied.
/// This enum is constructed from the [`entry`] method on [`HashMap`].
/// A view into a single entry in a map, which may either be vacant or occupied.
///
/// This `enum` is constructed from the [`entry`] method on [`HashMap`].
///
/// [`HashMap`]: struct.HashMap.html
/// [`entry`]: struct.HashMap.html#method.entry
#[stable(feature = "rust1", since = "1.0.0")]
pub enum Entry<'a, K: 'a, V: 'a> {
/// An occupied Entry.
/// An occupied entry.
#[stable(feature = "rust1", since = "1.0.0")]
Occupied(#[stable(feature = "rust1", since = "1.0.0")]
OccupiedEntry<'a, K, V>),
/// A vacant Entry.
/// A vacant entry.
#[stable(feature = "rust1", since = "1.0.0")]
Vacant(#[stable(feature = "rust1", since = "1.0.0")]
VacantEntry<'a, K, V>),
@ -1503,7 +1547,7 @@ impl<'a, K: 'a + Debug, V: 'a + Debug> Debug for Entry<'a, K, V> {
}
}
/// A view into a single occupied location in a HashMap.
/// A view into an occupied entry in a `HashMap`.
/// It is part of the [`Entry`] enum.
///
/// [`Entry`]: enum.Entry.html
@ -1523,7 +1567,7 @@ impl<'a, K: 'a + Debug, V: 'a + Debug> Debug for OccupiedEntry<'a, K, V> {
}
}
/// A view into a single empty location in a HashMap.
/// A view into a vacant entry in a `HashMap`.
/// It is part of the [`Entry`] enum.
///
/// [`Entry`]: enum.Entry.html
@ -2366,10 +2410,9 @@ impl DefaultHasher {
#[stable(feature = "hashmap_default_hasher", since = "1.13.0")]
impl Default for DefaultHasher {
/// Creates a new `DefaultHasher` using [`DefaultHasher::new`]. See
/// [`DefaultHasher::new`] documentation for more information.
/// Creates a new `DefaultHasher` using [`new`]. See its documentation for more.
///
/// [`DefaultHasher::new`]: #method.new
/// [`new`]: #method.new
fn default() -> DefaultHasher {
DefaultHasher::new()
}

118
src/libstd/collections/hash/set.rs
View File

@ -24,11 +24,10 @@ use super::map::{self, HashMap, Keys, RandomState};
// for `bucket.val` in the case of HashSet. I suppose we would need HKT
// to get rid of it properly.
/// An implementation of a hash set using the underlying representation of a
/// HashMap where the value is ().
/// A hash set implemented as a `HashMap` where the value is `()`.
///
/// As with the `HashMap` type, a `HashSet` requires that the elements
/// implement the `Eq` and `Hash` traits. This can frequently be achieved by
/// As with the [`HashMap`] type, a `HashSet` requires that the elements
/// implement the [`Eq`] and [`Hash`] traits. This can frequently be achieved by
/// using `#[derive(PartialEq, Eq, Hash)]`. If you implement these yourself,
/// it is important that the following property holds:
///
@ -40,9 +39,9 @@ use super::map::{self, HashMap, Keys, RandomState};
///
///
/// It is a logic error for an item to be modified in such a way that the
/// item's hash, as determined by the `Hash` trait, or its equality, as
/// determined by the `Eq` trait, changes while it is in the set. This is
/// normally only possible through `Cell`, `RefCell`, global state, I/O, or
/// item's hash, as determined by the [`Hash`] trait, or its equality, as
/// determined by the [`Eq`] trait, changes while it is in the set. This is
/// normally only possible through [`Cell`], [`RefCell`], global state, I/O, or
/// unsafe code.
///
/// # Examples
@ -75,8 +74,8 @@ use super::map::{self, HashMap, Keys, RandomState};
/// ```
///
/// The easiest way to use `HashSet` with a custom type is to derive
/// `Eq` and `Hash`. We must also derive `PartialEq`, this will in the
/// future be implied by `Eq`.
/// [`Eq`] and [`Hash`]. We must also derive [`PartialEq`], this will in the
/// future be implied by [`Eq`].
///
/// ```
/// use std::collections::HashSet;
@ -99,7 +98,7 @@ use super::map::{self, HashMap, Keys, RandomState};
/// }
/// ```
///
/// HashSet with fixed list of elements can be initialized from an array:
/// A `HashSet` with fixed list of elements can be initialized from an array:
///
/// ```
/// use std::collections::HashSet;
@ -110,6 +109,13 @@ use super::map::{self, HashMap, Keys, RandomState};
/// // use the values stored in the set
/// }
/// ```
///
/// [`Cell`]: ../../std/cell/struct.Cell.html
/// [`Eq`]: ../../std/cmp/trait.Eq.html
/// [`Hash`]: ../../std/hash/trait.Hash.html
/// [`HashMap`]: struct.HashMap.html
/// [`PartialEq`]: ../../std/cmp/trait.PartialEq.html
/// [`RefCell`]: ../../std/cell/struct.RefCell.html
#[derive(Clone)]
@ -181,7 +187,7 @@ impl<T, S> HashSet<T, S>
HashSet { map: HashMap::with_hasher(hasher) }
}
/// Creates an empty HashSet with with the specified capacity, using
/// Creates an empty `HashSet` with with the specified capacity, using
/// `hasher` to hash the keys.
///
/// The hash set will be able to hold at least `capacity` elements without
@ -208,7 +214,9 @@ impl<T, S> HashSet<T, S>
HashSet { map: HashMap::with_capacity_and_hasher(capacity, hasher) }
}
/// Returns a reference to the set's hasher.
/// Returns a reference to the set's [`BuildHasher`].
///
/// [`BuildHasher`]: ../../std/hash/trait.BuildHasher.html
#[stable(feature = "hashmap_public_hasher", since = "1.9.0")]
pub fn hasher(&self) -> &S {
self.map.hasher()
@ -271,7 +279,7 @@ impl<T, S> HashSet<T, S>
}
/// An iterator visiting all elements in arbitrary order.
/// Iterator element type is &'a T.
/// The iterator element type is `&'a T`.
///
/// # Examples
///
@ -291,7 +299,7 @@ impl<T, S> HashSet<T, S>
Iter { iter: self.map.keys() }
}
/// Visit the values representing the difference,
/// Visits the values representing the difference,
/// i.e. the values that are in `self` but not in `other`.
///
/// # Examples
@ -322,7 +330,7 @@ impl<T, S> HashSet<T, S>
}
}
/// Visit the values representing the symmetric difference,
/// Visits the values representing the symmetric difference,
/// i.e. the values that are in `self` or in `other` but not in both.
///
/// # Examples
@ -350,7 +358,7 @@ impl<T, S> HashSet<T, S>
SymmetricDifference { iter: self.difference(other).chain(other.difference(self)) }
}
/// Visit the values representing the intersection,
/// Visits the values representing the intersection,
/// i.e. the values that are both in `self` and `other`.
///
/// # Examples
@ -376,7 +384,7 @@ impl<T, S> HashSet<T, S>
}
}
/// Visit the values representing the union,
/// Visits the values representing the union,
/// i.e. all the values in `self` or `other`, without duplicates.
///
/// # Examples
@ -460,7 +468,7 @@ impl<T, S> HashSet<T, S>
/// Returns `true` if the set contains a value.
///
/// The value may be any borrowed form of the set's value type, but
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// [`Hash`] and [`Eq`] on the borrowed form *must* match those for
/// the value type.
///
/// # Examples
@ -472,6 +480,9 @@ impl<T, S> HashSet<T, S>
/// assert_eq!(set.contains(&1), true);
/// assert_eq!(set.contains(&4), false);
/// ```
///
/// [`Eq`]: ../../std/cmp/trait.Eq.html
/// [`Hash`]: ../../std/hash/trait.Hash.html
#[stable(feature = "rust1", since = "1.0.0")]
pub fn contains<Q: ?Sized>(&self, value: &Q) -> bool
where T: Borrow<Q>,
@ -483,8 +494,11 @@ impl<T, S> HashSet<T, S>
/// Returns a reference to the value in the set, if any, that is equal to the given value.
///
/// The value may be any borrowed form of the set's value type, but
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// [`Hash`] and [`Eq`] on the borrowed form *must* match those for
/// the value type.
///
/// [`Eq`]: ../../std/cmp/trait.Eq.html
/// [`Hash`]: ../../std/hash/trait.Hash.html
#[stable(feature = "set_recovery", since = "1.9.0")]
pub fn get<Q: ?Sized>(&self, value: &Q) -> Option<&T>
where T: Borrow<Q>,
@ -596,7 +610,7 @@ impl<T, S> HashSet<T, S>
/// present in the set.
///
/// The value may be any borrowed form of the set's value type, but
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// [`Hash`] and [`Eq`] on the borrowed form *must* match those for
/// the value type.
///
/// # Examples
@ -610,6 +624,9 @@ impl<T, S> HashSet<T, S>
/// assert_eq!(set.remove(&2), true);
/// assert_eq!(set.remove(&2), false);
/// ```
///
/// [`Eq`]: ../../std/cmp/trait.Eq.html
/// [`Hash`]: ../../std/hash/trait.Hash.html
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove<Q: ?Sized>(&mut self, value: &Q) -> bool
where T: Borrow<Q>,
@ -621,8 +638,11 @@ impl<T, S> HashSet<T, S>
/// Removes and returns the value in the set, if any, that is equal to the given one.
///
/// The value may be any borrowed form of the set's value type, but
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// [`Hash`] and [`Eq`] on the borrowed form *must* match those for
/// the value type.
///
/// [`Eq`]: ../../std/cmp/trait.Eq.html
/// [`Hash`]: ../../std/hash/trait.Hash.html
#[stable(feature = "set_recovery", since = "1.9.0")]
pub fn take<Q: ?Sized>(&mut self, value: &Q) -> Option<T>
where T: Borrow<Q>,
@ -856,25 +876,49 @@ impl<'a, 'b, T, S> Sub<&'b HashSet<T, S>> for &'a HashSet<T, S>
}
}
/// HashSet iterator
/// An iterator over the items of a `HashSet`.
///
/// This `struct` is created by the [`iter`] method on [`HashSet`].
/// See its documentation for more.
///
/// [`HashSet`]: struct.HashSet.html
/// [`iter`]: struct.HashSet.html#method.iter
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a, K: 'a> {
iter: Keys<'a, K, ()>,
}
/// HashSet move iterator
/// An owning iterator over the items of a `HashSet`.
///
/// This `struct` is created by the [`into_iter`] method on [`HashSet`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`HashSet`]: struct.HashSet.html
/// [`into_iter`]: struct.HashSet.html#method.into_iter
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IntoIter<K> {
iter: map::IntoIter<K, ()>,
}
/// HashSet drain iterator
/// A draining iterator over the items of a `HashSet`.
///
/// This `struct` is created by the [`drain`] method on [`HashSet`].
/// See its documentation for more.
///
/// [`HashSet`]: struct.HashSet.html
/// [`drain`]: struct.HashSet.html#method.drain
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Drain<'a, K: 'a> {
iter: map::Drain<'a, K, ()>,
}
/// Intersection iterator
/// A lazy iterator producing elements in the intersection of `HashSet`s.
///
/// This `struct` is created by the [`intersection`] method on [`HashSet`].
/// See its documentation for more.
///
/// [`HashSet`]: struct.HashSet.html
/// [`intersection`]: struct.HashSet.html#method.intersection
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Intersection<'a, T: 'a, S: 'a> {
// iterator of the first set
@ -883,7 +927,13 @@ pub struct Intersection<'a, T: 'a, S: 'a> {
other: &'a HashSet<T, S>,
}
/// Difference iterator
/// A lazy iterator producing elements in the difference of `HashSet`s.
///
/// This `struct` is created by the [`difference`] method on [`HashSet`].
/// See its documentation for more.
///
/// [`HashSet`]: struct.HashSet.html
/// [`difference`]: struct.HashSet.html#method.difference
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Difference<'a, T: 'a, S: 'a> {
// iterator of the first set
@ -892,13 +942,25 @@ pub struct Difference<'a, T: 'a, S: 'a> {
other: &'a HashSet<T, S>,
}
/// Symmetric difference iterator.
/// A lazy iterator producing elements in the symmetric difference of `HashSet`s.
///
/// This `struct` is created by the [`symmetric_difference`] method on
/// [`HashSet`]. See its documentation for more.
///
/// [`HashSet`]: struct.HashSet.html
/// [`symmetric_difference`]: struct.HashSet.html#method.symmetric_difference
#[stable(feature = "rust1", since = "1.0.0")]
pub struct SymmetricDifference<'a, T: 'a, S: 'a> {
iter: Chain<Difference<'a, T, S>, Difference<'a, T, S>>,
}
/// Set union iterator.
/// A lazy iterator producing elements in the union of `HashSet`s.
///
/// This `struct` is created by the [`union`] method on [`HashSet`].
/// See its documentation for more.
///
/// [`HashSet`]: struct.HashSet.html
/// [`union`]: struct.HashSet.html#method.union
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Union<'a, T: 'a, S: 'a> {
iter: Chain<Iter<'a, T>, Difference<'a, T, S>>,

60
src/libstd/collections/mod.rs
View File

@ -157,29 +157,29 @@
//! information to do this itself. Therefore, it is up to us programmers to give
//! it hints.
//!
//! Any `with_capacity()` constructor will instruct the collection to allocate
//! Any `with_capacity` constructor will instruct the collection to allocate
//! enough space for the specified number of elements. Ideally this will be for
//! exactly that many elements, but some implementation details may prevent
//! this. [`Vec`] and [`VecDeque`] can be relied on to allocate exactly the
//! requested amount, though. Use `with_capacity()` when you know exactly how many
//! requested amount, though. Use `with_capacity` when you know exactly how many
//! elements will be inserted, or at least have a reasonable upper-bound on that
//! number.
//!
//! When anticipating a large influx of elements, the `reserve()` family of
//! When anticipating a large influx of elements, the `reserve` family of
//! methods can be used to hint to the collection how much room it should make
//! for the coming items. As with `with_capacity()`, the precise behavior of
//! for the coming items. As with `with_capacity`, the precise behavior of
//! these methods will be specific to the collection of interest.
//!
//! For optimal performance, collections will generally avoid shrinking
//! themselves. If you believe that a collection will not soon contain any more
//! elements, or just really need the memory, the `shrink_to_fit()` method prompts
//! elements, or just really need the memory, the `shrink_to_fit` method prompts
//! the collection to shrink the backing array to the minimum size capable of
//! holding its elements.
//!
//! Finally, if ever you're interested in what the actual capacity of the
//! collection is, most collections provide a `capacity()` method to query this
//! collection is, most collections provide a `capacity` method to query this
//! information on demand. This can be useful for debugging purposes, or for
//! use with the `reserve()` methods.
//! use with the `reserve` methods.
//!
//! ## Iterators
//!
@ -194,11 +194,11 @@
//!
//! All of the standard collections provide several iterators for performing
//! bulk manipulation of their contents. The three primary iterators almost
//! every collection should provide are `iter()`, `iter_mut()`, and `into_iter()`.
//! every collection should provide are `iter`, `iter_mut`, and `into_iter`.
//! Some of these are not provided on collections where it would be unsound or
//! unreasonable to provide them.
//!
//! `iter()` provides an iterator of immutable references to all the contents of a
//! `iter` provides an iterator of immutable references to all the contents of a
//! collection in the most "natural" order. For sequence collections like [`Vec`],
//! this means the items will be yielded in increasing order of index starting
//! at 0. For ordered collections like [`BTreeMap`], this means that the items
@ -214,8 +214,8 @@
//! }
//! ```
//!
//! `iter_mut()` provides an iterator of *mutable* references in the same order as
//! `iter()`. This is great for mutating all the contents of the collection.
//! `iter_mut` provides an iterator of *mutable* references in the same order as
//! `iter`. This is great for mutating all the contents of the collection.
//!
//! ```
//! let mut vec = vec![1, 2, 3, 4];
@ -224,12 +224,12 @@
//! }
//! ```
//!
//! `into_iter()` transforms the actual collection into an iterator over its
//! `into_iter` transforms the actual collection into an iterator over its
//! contents by-value. This is great when the collection itself is no longer
//! needed, and the values are needed elsewhere. Using `extend()` with `into_iter()`
//! needed, and the values are needed elsewhere. Using `extend` with `into_iter`
//! is the main way that contents of one collection are moved into another.
//! `extend()` automatically calls `into_iter()`, and takes any `T: `[`IntoIterator`].
//! Calling `collect()` on an iterator itself is also a great way to convert one
//! `extend` automatically calls `into_iter`, and takes any `T: `[`IntoIterator`].
//! Calling `collect` on an iterator itself is also a great way to convert one
//! collection into another. Both of these methods should internally use the
//! capacity management tools discussed in the previous section to do this as
//! efficiently as possible.
@ -248,9 +248,9 @@
//! ```
//!
//! Iterators also provide a series of *adapter* methods for performing common
//! threads to sequences. Among the adapters are functional favorites like `map()`,
//! `fold()`, `skip()` and `take()`. Of particular interest to collections is the
//! `rev()` adapter, that reverses any iterator that supports this operation. Most
//! threads to sequences. Among the adapters are functional favorites like `map`,
//! `fold`, `skip` and `take`. Of particular interest to collections is the
//! `rev` adapter, that reverses any iterator that supports this operation. Most
//! collections provide reversible iterators as the way to iterate over them in
//! reverse order.
//!
@ -263,27 +263,27 @@
//!
//! Several other collection methods also return iterators to yield a sequence
//! of results but avoid allocating an entire collection to store the result in.
//! This provides maximum flexibility as `collect()` or `extend()` can be called to
//! This provides maximum flexibility as `collect` or `extend` can be called to
//! "pipe" the sequence into any collection if desired. Otherwise, the sequence
//! can be looped over with a `for` loop. The iterator can also be discarded
//! after partial use, preventing the computation of the unused items.
//!
//! ## Entries
//!
//! The `entry()` API is intended to provide an efficient mechanism for
//! The `entry` API is intended to provide an efficient mechanism for
//! manipulating the contents of a map conditionally on the presence of a key or
//! not. The primary motivating use case for this is to provide efficient
//! accumulator maps. For instance, if one wishes to maintain a count of the
//! number of times each key has been seen, they will have to perform some
//! conditional logic on whether this is the first time the key has been seen or
//! not. Normally, this would require a `find()` followed by an `insert()`,
//! not. Normally, this would require a `find` followed by an `insert`,
//! effectively duplicating the search effort on each insertion.
//!
//! When a user calls `map.entry(&key)`, the map will search for the key and
//! then yield a variant of the `Entry` enum.
//!
//! If a `Vacant(entry)` is yielded, then the key *was not* found. In this case
//! the only valid operation is to `insert()` a value into the entry. When this is
//! the only valid operation is to `insert` a value into the entry. When this is
//! done, the vacant entry is consumed and converted into a mutable reference to
//! the value that was inserted. This allows for further manipulation of the
//! value beyond the lifetime of the search itself. This is useful if complex
@ -291,14 +291,14 @@
//! just inserted.
//!
//! If an `Occupied(entry)` is yielded, then the key *was* found. In this case,
//! the user has several options: they can `get()`, `insert()` or `remove()` the
//! the user has several options: they can `get`, `insert` or `remove` the
//! value of the occupied entry. Additionally, they can convert the occupied
//! entry into a mutable reference to its value, providing symmetry to the
//! vacant `insert()` case.
//! vacant `insert` case.
//!
//! ### Examples
//!
//! Here are the two primary ways in which `entry()` is used. First, a simple
//! Here are the two primary ways in which `entry` is used. First, a simple
//! example where the logic performed on the values is trivial.
//!
//! #### Counting the number of times each character in a string occurs
@ -322,7 +322,7 @@
//! ```
//!
//! When the logic to be performed on the value is more complex, we may simply
//! use the `entry()` API to ensure that the value is initialized and perform the
//! use the `entry` API to ensure that the value is initialized and perform the
//! logic afterwards.
//!
//! #### Tracking the inebriation of customers at a bar
@ -360,7 +360,7 @@
//!
//! # Insert and complex keys
//!
//! If we have a more complex key, calls to `insert()` will
//! If we have a more complex key, calls to `insert` will
//! not update the value of the key. For example:
//!
//! ```
@ -442,16 +442,14 @@ mod hash;
#[stable(feature = "rust1", since = "1.0.0")]
pub mod hash_map {
//! A hash map implementation which uses linear probing with Robin
//! Hood bucket stealing.
//! A hash map implemented with linear probing and Robin Hood bucket stealing.
#[stable(feature = "rust1", since = "1.0.0")]
pub use super::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 ().
//! A hash set implemented as a `HashMap` where the value is `()`.
#[stable(feature = "rust1", since = "1.0.0")]
pub use super::hash::set::*;
}

3
src/tools/linkchecker/main.rs
View File

@ -142,7 +142,8 @@ fn check(cache: &mut Cache,
if file.ends_with("btree_set/struct.BTreeSet.html") ||
file.ends_with("collections/struct.BTreeSet.html") ||
file.ends_with("collections/btree_map/struct.BTreeMap.html") ||
file.ends_with("collections/hash_map/struct.HashMap.html") {
file.ends_with("collections/hash_map/struct.HashMap.html") ||
file.ends_with("collections/hash_set/struct.HashSet.html") {
return None;
}