Various fixes throughout std::collections' docs
* Added links where possible (limited because of facading) * Changed references to methods from `foo()` to `foo` in module docs * Changed references to methods from `HashMap::foo` to just `foo` in top-level docs for `HashMap` and the `default` doc for `DefaultHasher` * Various small other fixes
This commit is contained in:
parent
d64de94efa
commit
d688c4d806
|
@ -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;
|
||||
|
@ -438,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
|
||||
|
@ -456,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);
|
||||
|
|
|
@ -734,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
|
||||
///
|
||||
|
|
|
@ -636,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
|
||||
///
|
||||
/// ```
|
||||
|
|
|
@ -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
|
||||
|
@ -506,7 +511,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 +527,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);
|
||||
|
|
|
@ -235,9 +235,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 +338,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 +372,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 +653,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 +686,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 +851,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 +873,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 +895,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 +922,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 +945,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
|
||||
///
|
||||
|
@ -2408,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()
|
||||
}
|
||||
|
|
|
@ -25,10 +25,10 @@ use super::map::{self, HashMap, Keys, RandomState};
|
|||
// to get rid of it properly.
|
||||
|
||||
/// An implementation of a hash set using the underlying representation of a
|
||||
/// HashMap where the value is ().
|
||||
/// `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 +40,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 +75,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 +99,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 +110,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 +188,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 +215,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 +280,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 +300,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 +331,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 +359,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 +385,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 +469,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 +481,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 +495,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 +611,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 +625,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 +639,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>,
|
||||
|
|
|
@ -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:
|
||||
//!
|
||||
//! ```
|
||||
|
@ -451,7 +451,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::*;
|
||||
}
|
||||
|
|
Loading…
Reference in New Issue