bevy_utils: Re-introduce with_capacity(). (#2393)

# Objective
Re-introduce `AHashExt` and respective `with_capacity()` implementations to give a more ergonomic way to set a `HashMap` / `HashSet` capacity.

As a note, this has also been discussed and agreed on issue #2115, which this PR addresses (leaving `new()` out of the `AHashExt` trait).

Fixes #2115.

## Solution
PR #1235 had removed the `AHashExt` trait and respective `with_capacity()`s implementations, leaving only the less ergonomic `HashMap::with_capacity_and_hasher(size, Default::default())` option available.

This re-introduces `AHashExt` and respective `with_capacity()` implementations to give a more ergonomic way to set a `HashMap` / `HashSet` capacity.

Author: tiagolam

crates/bevy_utils/src/lib.rs

@@ -37,6 +37,29 @@ impl std::hash::BuildHasher for FixedState {
 /// AHash is designed for performance and is NOT cryptographically secure.
 pub type HashMap<K, V> = std::collections::HashMap<K, V, RandomState>;
 
+pub trait AHashExt {
+    fn with_capacity(capacity: usize) -> Self;
+}
+
+impl<K, V> AHashExt for HashMap<K, V> {
+    /// Creates an empty `HashMap` with the specified capacity with AHash.
+    ///
+    /// The hash map will be able to hold at least `capacity` elements without
+    /// reallocating. If `capacity` is 0, the hash map will not allocate.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use bevy_utils::{HashMap, AHashExt};
+    /// let mut map: HashMap<&str, i32> = HashMap::with_capacity(10);
+    /// assert!(map.capacity() >= 10);
+    /// ```
+    #[inline]
+    fn with_capacity(capacity: usize) -> Self {
+        HashMap::with_capacity_and_hasher(capacity, RandomState::default())
+    }
+}
+
 /// A stable std hash map implementing AHash, a high speed keyed hashing algorithm
 /// intended for use in in-memory hashmaps.
 ///
@@ -46,12 +69,50 @@ pub type HashMap<K, V> = std::collections::HashMap<K, V, RandomState>;
 /// AHash is designed for performance and is NOT cryptographically secure.
 pub type StableHashMap<K, V> = std::collections::HashMap<K, V, FixedState>;
 
+impl<K, V> AHashExt for StableHashMap<K, V> {
+    /// Creates an empty `StableHashMap` with the specified capacity with AHash.
+    ///
+    /// The hash map will be able to hold at least `capacity` elements without
+    /// reallocating. If `capacity` is 0, the hash map will not allocate.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use bevy_utils::{StableHashMap, AHashExt};
+    /// let mut map: StableHashMap<&str, i32> = StableHashMap::with_capacity(10);
+    /// assert!(map.capacity() >= 10);
+    /// ```
+    #[inline]
+    fn with_capacity(capacity: usize) -> Self {
+        StableHashMap::with_capacity_and_hasher(capacity, FixedState::default())
+    }
+}
+
 /// A std hash set implementing AHash, a high speed keyed hashing algorithm
 /// intended for use in in-memory hashmaps.
 ///
 /// AHash is designed for performance and is NOT cryptographically secure.
 pub type HashSet<K> = std::collections::HashSet<K, RandomState>;
 
+impl<K> AHashExt for HashSet<K> {
+    /// Creates an empty `HashSet` with the specified capacity with AHash.
+    ///
+    /// The hash set will be able to hold at least `capacity` elements without
+    /// reallocating. If `capacity` is 0, the hash set will not allocate.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use bevy_utils::{HashSet, AHashExt};
+    /// let set: HashSet<i32> = HashSet::with_capacity(10);
+    /// assert!(set.capacity() >= 10);
+    /// ```
+    #[inline]
+    fn with_capacity(capacity: usize) -> Self {
+        HashSet::with_capacity_and_hasher(capacity, RandomState::default())
+    }
+}
+
 /// A stable std hash set implementing AHash, a high speed keyed hashing algorithm
 /// intended for use in in-memory hashmaps.
 ///
@@ -60,3 +121,22 @@ pub type HashSet<K> = std::collections::HashSet<K, RandomState>;
 ///
 /// AHash is designed for performance and is NOT cryptographically secure.
 pub type StableHashSet<K> = std::collections::HashSet<K, FixedState>;
+
+impl<K> AHashExt for StableHashSet<K> {
+    /// Creates an empty `StableHashSet` with the specified capacity with AHash.
+    ///
+    /// The hash set will be able to hold at least `capacity` elements without
+    /// reallocating. If `capacity` is 0, the hash set will not allocate.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use bevy_utils::{StableHashSet, AHashExt};
+    /// let set: StableHashSet<i32> = StableHashSet::with_capacity(10);
+    /// assert!(set.capacity() >= 10);
+    /// ```
+    #[inline]
+    fn with_capacity(capacity: usize) -> Self {
+        StableHashSet::with_capacity_and_hasher(capacity, FixedState::default())
+    }
+}