Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-21 20:23:28 +00:00
Code Issues Projects Releases Packages Wiki Activity

explain absence of new constructor in Hash{Map, Set} docs; suggest default (#3077)

Browse source 
# Objective

Fixes #2823.

## Solution

This PR adds notes to the `HashMap` and `HashSet` docs explaining why `HashMap::new()` (resp. `HashSet::new()`) is not available, and guiding the user toward using the `Default` implementation for an empty collection.
This commit is contained in:
dataphract 2021-11-06 20:53:12 +00:00
parent b3cd48228b
commit f4cfcc0e44
1 changed files with 70 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
crates/bevy_utils/src/lib.rs
View file

@ -31,10 +31,43 @@ impl std::hash::BuildHasher for FixedState {
}
}
/// A std hash map implementing AHash, a high speed keyed hashing algorithm
/// intended for use in in-memory hashmaps.
/// A [`HashMap`][std::collections::HashMap] implementing [aHash][aHash], a high
/// speed keyed hashing algorithm intended for use in in-memory hashmaps.
///
/// AHash is designed for performance and is NOT cryptographically secure.
///
/// # Construction
///
/// Users may be surprised when a `HashMap` cannot be constructed with `HashMap::new()`:
///
/// ```compile_fail
/// # fn main() {
/// use bevy_utils::HashMap;
///
/// // Produces an error like "no function or associated item named `new` found [...]"
/// let map: HashMap<String, String> = HashMap::new();
/// # }
/// ```
///
/// The standard library's [`HashMap::new`][std::collections::HashMap::new] is
/// implemented only for `HashMap`s which use the
/// [`DefaultHasher`][std::collections::hash_map::DefaultHasher], so it's not
/// available for Bevy's `HashMap`.
///
/// However, an empty `HashMap` can easily be constructed using the `Default`
/// implementation:
///
/// ```
/// # fn main() {
/// use bevy_utils::HashMap;
///
/// // This works!
/// let map: HashMap<String, String> = HashMap::default();
/// assert!(map.is_empty());
/// # }
/// ```
///
/// [aHash]: https://github.com/tkaitchuck/aHash
pub type HashMap<K, V> = std::collections::HashMap<K, V, RandomState>;
pub trait AHashExt {
@ -88,10 +121,43 @@ impl<K, V> AHashExt for StableHashMap<K, V> {
}
}
/// A std hash set implementing AHash, a high speed keyed hashing algorithm
/// intended for use in in-memory hashmaps.
/// A [`HashSet`][std::collections::HashSet] implementing [aHash][aHash], a high
/// speed keyed hashing algorithm intended for use in in-memory hashmaps.
///
/// AHash is designed for performance and is NOT cryptographically secure.
///
/// # Construction
///
/// Users may be surprised when a `HashSet` cannot be constructed with `HashSet::new()`:
///
/// ```compile_fail
/// # fn main() {
/// use bevy_utils::HashSet;
///
/// // Produces an error like "no function or associated item named `new` found [...]"
/// let map: HashSet<String> = HashSet::new();
/// # }
/// ```
///
/// The standard library's [`HashSet::new`][std::collections::HashSet::new] is
/// implemented only for `HashSet`s which use the
/// [`DefaultHasher`][std::collections::hash_map::DefaultHasher], so it's not
/// available for Bevy's `HashSet`.
///
/// However, an empty `HashSet` can easily be constructed using the `Default`
/// implementation:
///
/// ```
/// # fn main() {
/// use bevy_utils::HashSet;
///
/// // This works!
/// let map: HashSet<String> = HashSet::default();
/// assert!(map.is_empty());
/// # }
/// ```
///
/// [aHash]: https://github.com/tkaitchuck/aHash
pub type HashSet<K> = std::collections::HashSet<K, RandomState>;
impl<K> AHashExt for HashSet<K> {