Rollup merge of #37304 - GuillaumeGomez:collections_url, r=frewsxcv
Add missing urls in collections module r? @steveklabnik
This commit is contained in:
Jonathan Turner
GitHub
commit
855f3e740c
@ -15,7 +15,7 @@
|
||||
//! standard implementations, it should be possible for two libraries to
|
||||
//! communicate without significant data conversion.
|
||||
//!
|
||||
//! To get this out of the way: you should probably just use `Vec` or `HashMap`.
|
||||
//! To get this out of the way: you should probably just use [`Vec`] or [`HashMap`].
|
||||
//! These two collections cover most use cases for generic data storage and
|
||||
//! 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
|
||||
@ -25,10 +25,10 @@
|
||||
//!
|
||||
//! Rust's collections can be grouped into four major categories:
|
||||
//!
|
||||
//! * Sequences: `Vec`, `VecDeque`, `LinkedList`
|
||||
//! * Maps: `HashMap`, `BTreeMap`
|
||||
//! * Sets: `HashSet`, `BTreeSet`
|
||||
//! * Misc: `BinaryHeap`
|
||||
//! * Sequences: [`Vec`], [`VecDeque`], [`LinkedList`]
|
||||
//! * Maps: [`HashMap`], [`BTreeMap`]
|
||||
//! * Sets: [`HashSet`], [`BTreeSet`]
|
||||
//! * Misc: [`BinaryHeap`]
|
||||
//!
|
||||
//! # When Should You Use Which Collection?
|
||||
//!
|
||||
@ -46,13 +46,13 @@
|
||||
//! * You want a heap-allocated array.
|
||||
//!
|
||||
//! ### Use a `VecDeque` when:
|
||||
//! * You want a `Vec` that supports efficient insertion at both ends of the
|
||||
//! * 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
|
||||
//! * 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
|
||||
@ -92,38 +92,38 @@
|
||||
//! Throughout the documentation, we will follow a few conventions. For all
|
||||
//! operations, the collection's size is denoted by n. If another collection is
|
||||
//! involved in the operation, it contains m elements. Operations which have an
|
||||
//! *amortized* cost are suffixed with a `*`. Operations with an *expected*
|
||||
//! *amortized* cost are suffixed with a `*`. Operations with an *expected*
|
||||
//! cost are suffixed with a `~`.
|
||||
//!
|
||||
//! All amortized costs are for the potential need to resize when capacity is
|
||||
//! exhausted. If a resize occurs it will take O(n) time. Our collections never
|
||||
//! exhausted. If a resize occurs it will take O(n) time. Our collections never
|
||||
//! automatically shrink, so removal operations aren't amortized. Over a
|
||||
//! sufficiently large series of operations, the average cost per operation will
|
||||
//! deterministically equal the given cost.
|
||||
//!
|
||||
//! Only HashMap has expected costs, due to the probabilistic nature of hashing.
|
||||
//! It is theoretically possible, though very unlikely, for HashMap to
|
||||
//! Only [`HashMap`] has expected costs, due to the probabilistic nature of hashing.
|
||||
//! It is theoretically possible, though very unlikely, for [`HashMap`] to
|
||||
//! experience worse performance.
|
||||
//!
|
||||
//! ## Sequences
|
||||
//!
|
||||
//! | | get(i) | insert(i) | remove(i) | append | split_off(i) |
|
||||
//! |--------------|----------------|-----------------|----------------|--------|----------------|
|
||||
//! | Vec | O(1) | O(n-i)* | O(n-i) | O(m)* | O(n-i) |
|
||||
//! | VecDeque | O(1) | O(min(i, n-i))* | O(min(i, n-i)) | O(m)* | O(min(i, n-i)) |
|
||||
//! | LinkedList | O(min(i, n-i)) | O(min(i, n-i)) | O(min(i, n-i)) | O(1) | O(min(i, n-i)) |
|
||||
//! | | get(i) | insert(i) | remove(i) | append | split_off(i) |
|
||||
//! |----------------|----------------|-----------------|----------------|--------|----------------|
|
||||
//! | [`Vec`] | O(1) | O(n-i)* | O(n-i) | O(m)* | O(n-i) |
|
||||
//! | [`VecDeque`] | O(1) | O(min(i, n-i))* | O(min(i, n-i)) | O(m)* | O(min(i, n-i)) |
|
||||
//! | [`LinkedList`] | O(min(i, n-i)) | O(min(i, n-i)) | O(min(i, n-i)) | O(1) | O(min(i, n-i)) |
|
||||
//!
|
||||
//! Note that where ties occur, Vec is generally going to be faster than VecDeque, and VecDeque
|
||||
//! is generally going to be faster than LinkedList.
|
||||
//! Note that where ties occur, [`Vec`] is generally going to be faster than [`VecDeque`], and
|
||||
//! [`VecDeque`] is generally going to be faster than [`LinkedList`].
|
||||
//!
|
||||
//! ## Maps
|
||||
//!
|
||||
//! For Sets, all operations have the cost of the equivalent Map operation.
|
||||
//!
|
||||
//! | | get | insert | remove | predecessor | append |
|
||||
//! |----------|-----------|----------|----------|-------------|--------|
|
||||
//! | HashMap | O(1)~ | O(1)~* | O(1)~ | N/A | N/A |
|
||||
//! | BTreeMap | O(log n) | O(log n) | O(log n) | O(log n) | O(n+m) |
|
||||
//! | | get | insert | remove | predecessor | append |
|
||||
//! |--------------|-----------|----------|----------|-------------|--------|
|
||||
//! | [`HashMap`] | O(1)~ | O(1)~* | O(1)~ | N/A | N/A |
|
||||
//! | [`BTreeMap`] | O(log n) | O(log n) | O(log n) | O(log n) | O(n+m) |
|
||||
//!
|
||||
//! # Correct and Efficient Usage of Collections
|
||||
//!
|
||||
@ -136,7 +136,7 @@
|
||||
//! ## Capacity Management
|
||||
//!
|
||||
//! Many collections provide several constructors and methods that refer to
|
||||
//! "capacity". These collections are generally built on top of an array.
|
||||
//! "capacity". These collections are generally built on top of an array.
|
||||
//! Optimally, this array would be exactly the right size to fit only the
|
||||
//! elements stored in the collection, but for the collection to do this would
|
||||
//! be very inefficient. If the backing array was exactly the right size at all
|
||||
@ -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
|
||||
//! this. [`Vec`] and [`VecDeque`] can be relied on to allocate exactly the
|
||||
//! 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
|
||||
//! 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
|
||||
//! 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
|
||||
//! information on demand. This can be useful for debugging purposes, or for
|
||||
//! use with the `reserve` methods.
|
||||
//! 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.
|
||||
//!
|
||||
//! ## Iterators
|
||||
//!
|
||||
@ -194,15 +194,15 @@
|
||||
//!
|
||||
//! 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
|
||||
//! collection in the most "natural" order. For sequence collections like `Vec`,
|
||||
//! `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
|
||||
//! will be yielded in sorted order. For unordered collections like `HashMap`,
|
||||
//! at 0. For ordered collections like [`BTreeMap`], this means that the items
|
||||
//! will be yielded in sorted order. For unordered collections like [`HashMap`],
|
||||
//! the items will be yielded in whatever order the internal representation made
|
||||
//! most convenient. This is great for reading through all the contents of the
|
||||
//! collection.
|
||||
@ -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
|
||||
@ -406,6 +406,16 @@
|
||||
//! // ...but the key hasn't changed. b is still "baz", not "xyz".
|
||||
//! assert_eq!(map.keys().next().unwrap().b, "baz");
|
||||
//! ```
|
||||
//!
|
||||
//! [`Vec`]: ../../std/vec/struct.Vec.html
|
||||
//! [`HashMap`]: ../../std/collections/struct.HashMap.html
|
||||
//! [`VecDeque`]: ../../std/collections/struct.VecDeque.html
|
||||
//! [`LinkedList`]: ../../std/collections/struct.LinkedList.html
|
||||
//! [`BTreeMap`]: ../../std/collections/struct.BTreeMap.html
|
||||
//! [`HashSet`]: ../../std/collections/struct.HashSet.html
|
||||
//! [`BTreeSet`]: ../../std/collections/struct.BTreeSet.html
|
||||
//! [`BinaryHeap`]: ../../std/collections/struct.BinaryHeap.html
|
||||
//! [`IntoIterator`]: ../../std/iter/trait.IntoIterator.html
|
||||
|
||||
#![stable(feature = "rust1", since = "1.0.0")]
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user