mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #129866 - root-goblin:patch-1, r=workingjubilee

Browse Source 
Clarify documentation labelling and definitions for std::collections

Page affected: https://doc.rust-lang.org/std/collections/index.html#performance

Changes:
- bulleted conventions
- expanded definitions on terms used
- more accessible language
- more informative headings
This commit is contained in:
Matthias Krüger 2024-09-11 20:04:22 +02:00 committed by GitHub
commit 6d7ccad93d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 35 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
library/std/src/collections/mod.rs
View File

@ -79,42 +79,50 @@
//! see each type's documentation, and note that the names of actual methods may //! see each type's documentation, and note that the names of actual methods may
//! differ from the tables below on certain collections. //! differ from the tables below on certain collections.
//! //!
//! Throughout the documentation, we will follow a few conventions. For all //! Throughout the documentation, we will adhere to the following conventions
//! operations, the collection's size is denoted by n. If another collection is //! for operation notation:
//! involved in the operation, it contains m elements. Operations which have an
//! *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 //! * The collection's size is denoted by `n`.
//! exhausted. If a resize occurs it will take *O*(*n*) time. Our collections never //! * If a second collection is involved, its size is denoted by `m`.
//! automatically shrink, so removal operations aren't amortized. Over a //! * Item indices are denoted by `i`.
//! sufficiently large series of operations, the average cost per operation will //! * Operations which have an *amortized* cost are suffixed with a `*`.
//! deterministically equal the given cost. //! * Operations with an *expected* cost are suffixed with a `~`.
//! //!
//! Only [`HashMap`] has expected costs, due to the probabilistic nature of hashing. //! Calling operations that add to a collection will occasionally require a
//! It is theoretically possible, though very unlikely, for [`HashMap`] to //! collection to be resized - an extra operation that takes *O*(*n*) time.
//! experience worse performance.
//! //!
//! ## Sequences //! *Amortized* costs are calculated to account for the time cost of such resize
//! operations *over a sufficiently large series of operations*. An individual
//! operation may be slower or faster due to the sporadic nature of collection
//! resizing, however the average cost per operation will approach the amortized
//! cost.
//! //!
//! | | get(i) | insert(i) | remove(i) | append | split_off(i) | //! Rust's collections never automatically shrink, so removal operations aren't
//! |----------------|------------------------|-------------------------|------------------------|-----------|------------------------| //! amortized.
//! | [`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 //! [`HashMap`] uses *expected* costs. It is theoretically possible, though very
//! [`VecDeque`] is generally going to be faster than [`LinkedList`]. //! unlikely, for [`HashMap`] to experience significantly worse performance than
//! the expected cost. This is due to the probabilistic nature of hashing - i.e.
//! it is possible to generate a duplicate hash given some input key that will
//! requires extra computation to correct.
//! //!
//! ## Maps //! ## Cost of Collection Operations
//!
//!
//! | | get(i) | insert(i) | remove(i) | append(Vec(m)) | split_off(i) | range | append |
//! |----------------|------------------------|-------------------------|------------------------|-------------------|------------------------|-----------------|--------------|
//! | [`Vec`] | *O*(1) | *O*(*n*-*i*)* | *O*(*n*-*i*) | *O*(*m*)* | *O*(*n*-*i*) | N/A | N/A |
//! | [`VecDeque`] | *O*(1) | *O*(min(*i*, *n*-*i*))* | *O*(min(*i*, *n*-*i*)) | *O*(*m*)* | *O*(min(*i*, *n*-*i*)) | N/A | N/A |
//! | [`LinkedList`] | *O*(min(*i*, *n*-*i*)) | *O*(min(*i*, *n*-*i*)) | *O*(min(*i*, *n*-*i*)) | *O*(1) | *O*(min(*i*, *n*-*i*)) | N/A | N/A |
//! | [`HashMap`] | *O*(1)~ | *O*(1)~* | *O*(1)~ | N/A | N/A | N/A | N/A |
//! | [`BTreeMap`] | *O*(log(*n*)) | *O*(log(*n*)) | *O*(log(*n*)) | N/A | N/A | *O*(log(*n*)) | *O*(*n*+*m*) |
//!
//! Note that where ties occur, [`Vec`] is generally going to be faster than
//! [`VecDeque`], and [`VecDeque`] is generally going to be faster than
//! [`LinkedList`].
//! //!
//! For Sets, all operations have the cost of the equivalent Map operation. //! For Sets, all operations have the cost of the equivalent Map operation.
//! //!
//! | | get | insert | remove | range | 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 //! # Correct and Efficient Usage of Collections
//! //!
//! Of course, knowing which collection is the right one for the job doesn't //! Of course, knowing which collection is the right one for the job doesn't