From 68f41b8328d76e171a17a0ac60351f576b9116b5 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Tue, 23 Feb 2021 00:41:41 -0500 Subject: [PATCH 1/2] Add more links between hash and btree collections - Link from `core::hash` to `HashMap` and `HashSet` - Link from HashMap and HashSet to the module-level documentation on when to use the collection - Link from several collections to Wikipedia articles on the general concept --- library/alloc/src/collections/btree/map.rs | 7 ++++--- library/core/src/hash/mod.rs | 10 ++++++++-- library/std/src/collections/hash/map.rs | 3 ++- library/std/src/collections/hash/set.rs | 3 ++- 4 files changed, 16 insertions(+), 7 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index 801615b3dc261..a4bcfa33e0dce 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -20,15 +20,15 @@ use Entry::*; /// We might temporarily have fewer elements during methods. pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT; -// A tree in a `BTreeMap` is a tree in the `node` module with addtional invariants: +// A tree in a `BTreeMap` is a tree in the `node` module with additional invariants: // - Keys must appear in ascending order (according to the key's type). // - If the root node is internal, it must contain at least 1 element. // - Every non-root node contains at least MIN_LEN elements. // -// An empty map may be represented both by the absense of a root node or by a +// An empty map may be represented both by the absence of a root node or by a // root node that is an empty leaf. -/// A map based on a B-Tree. +/// A map based on a [B-Tree]. /// /// B-Trees represent a fundamental compromise between cache-efficiency and actually minimizing /// the amount of work performed in a search. In theory, a binary search tree (BST) is the optimal @@ -62,6 +62,7 @@ pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT; /// undefined behavior. This could include panics, incorrect results, aborts, memory leaks, and /// non-termination. /// +/// [B-Tree]: https://en.wikipedia.org/wiki/B-tree /// [`Cell`]: core::cell::Cell /// [`RefCell`]: core::cell::RefCell /// diff --git a/library/core/src/hash/mod.rs b/library/core/src/hash/mod.rs index cd47f97496a4a..2ff87f4890727 100644 --- a/library/core/src/hash/mod.rs +++ b/library/core/src/hash/mod.rs @@ -1,7 +1,13 @@ //! Generic hashing support. //! -//! This module provides a generic way to compute the hash of a value. The -//! simplest way to make a type hashable is to use `#[derive(Hash)]`: +//! This module provides a generic way to compute the [hash] of a value. +//! Hashes are most commonly used with [`HashMap`] and [`HashSet`]. +//! +//! [hash]: https://en.wikipedia.org/wiki/Hash_function +//! [`HashMap`]: ../../std/collections/struct.HashMap.html +//! [`HashSet`]: ../../std/collections/struct.HashSet.html + +//! The simplest way to make a type hashable is to use `#[derive(Hash)]`: //! //! # Examples //! diff --git a/library/std/src/collections/hash/map.rs b/library/std/src/collections/hash/map.rs index 27f7191831d41..95cb1fd1668b0 100644 --- a/library/std/src/collections/hash/map.rs +++ b/library/std/src/collections/hash/map.rs @@ -15,7 +15,7 @@ use crate::iter::{FromIterator, FusedIterator}; use crate::ops::Index; use crate::sys; -/// A hash map implemented with quadratic probing and SIMD lookup. +/// A [hash map] implemented with quadratic probing and SIMD lookup. /// /// By default, `HashMap` uses a hashing algorithm selected to provide /// resistance against HashDoS attacks. The algorithm is randomly seeded, and a @@ -60,6 +60,7 @@ use crate::sys; /// The original C++ version of SwissTable can be found [here], and this /// [CppCon talk] gives an overview of how the algorithm works. /// +/// [hash map]: crate::collections#use-a-hashmap-when /// [hashing algorithms available on crates.io]: https://crates.io/keywords/hasher /// [SwissTable]: https://abseil.io/blog/20180927-swisstables /// [here]: https://github.com/abseil/abseil-cpp/blob/master/absl/container/internal/raw_hash_set.h diff --git a/library/std/src/collections/hash/set.rs b/library/std/src/collections/hash/set.rs index 912e975aa0a4c..8c801b9f1285d 100644 --- a/library/std/src/collections/hash/set.rs +++ b/library/std/src/collections/hash/set.rs @@ -19,7 +19,7 @@ use super::map::{map_try_reserve_error, RandomState}; // for `bucket.val` in the case of HashSet. I suppose we would need HKT // to get rid of it properly. -/// A hash set implemented as 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 @@ -105,6 +105,7 @@ use super::map::{map_try_reserve_error, RandomState}; /// // use the values stored in the set /// ``` /// +/// [hash set]: crate::collections#use-the-set-variant-of-any-of-these-maps-when /// [`HashMap`]: crate::collections::HashMap /// [`RefCell`]: crate::cell::RefCell /// [`Cell`]: crate::cell::Cell From a7491d932fdfe9ccb1950c1ab660c0bf493cc7bb Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Wed, 17 Mar 2021 09:27:34 -0400 Subject: [PATCH 2/2] fix whitespace Co-authored-by: Yuki Okushi --- library/core/src/hash/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/hash/mod.rs b/library/core/src/hash/mod.rs index 2ff87f4890727..05154f18a9f70 100644 --- a/library/core/src/hash/mod.rs +++ b/library/core/src/hash/mod.rs @@ -6,7 +6,7 @@ //! [hash]: https://en.wikipedia.org/wiki/Hash_function //! [`HashMap`]: ../../std/collections/struct.HashMap.html //! [`HashSet`]: ../../std/collections/struct.HashSet.html - +//! //! The simplest way to make a type hashable is to use `#[derive(Hash)]`: //! //! # Examples