hashbrown-0.14.5/.cargo_vcs_info.json0000644000000001360000000000100131160ustar { "git": { "sha1": "025d0f58b62d074f5fd660a22fe293cdc237d589" }, "path_in_vcs": "" }hashbrown-0.14.5/.gitignore000064400000000000000000000000361046102023000136750ustar 00000000000000/target **/*.rs.bk Cargo.lock hashbrown-0.14.5/CHANGELOG.md000064400000000000000000000433341046102023000135260ustar 00000000000000# Change Log All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/) and this project adheres to [Semantic Versioning](https://semver.org/). ## [Unreleased] ### Changed - Changed `hash_set::{Entry, VacantEntry}::insert` to return `OccupiedEntry`. (#495) ## [v0.14.5] - 2024-04-28 ### Fixed - Fixed index calculation in panic guard of `clone_from_impl`. (#511) ## ~~[v0.14.4] - 2024-03-19~~ This release was _yanked_ due to a breaking change. ## [v0.14.3] - 2023-11-26 ### Added - Specialized `fold` implementation of iterators. (#480) ### Fixed - Avoid using unstable `ptr::invalid_mut` on nightly. (#481) ## [v0.14.2] - 2023-10-19 ### Added - `HashTable` type which provides a low-level but safe API with explicit hashing. (#466) ### Fixed - Disabled the use of NEON instructions on big-endian ARM. (#475) - Disabled the use of NEON instructions on Miri. (#476) ## [v0.14.1] - 2023-09-28 ### Added - Allow serializing `HashMap`s that use a custom allocator. (#449) ### Changed - Use the `Equivalent` trait from the `equivalent` crate. (#442) - Slightly improved performance of table resizing. (#451) - Relaxed MSRV to 1.63.0. (#457) - Removed `Clone` requirement from custom allocators. (#468) ### Fixed - Fixed custom allocators being leaked in some situations. (#439, #465) ## [v0.14.0] - 2023-06-01 ### Added - Support for `allocator-api2` crate for interfacing with custom allocators on stable. (#417) - Optimized implementation for ARM using NEON instructions. (#430) - Support for rkyv serialization. (#432) - `Equivalent` trait to look up values without `Borrow`. (#345) - `Hash{Map,Set}::raw_table_mut` is added whic returns a mutable reference. (#404) - Fast path for `clear` on empty tables. (#428) ### Changed - Optimized insertion to only perform a single lookup. (#277) - `DrainFilter` (`drain_filter`) has been renamed to `ExtractIf` and no longer drops remaining elements when the iterator is dropped. #(374) - Bumped MSRV to 1.64.0. (#431) - `{Map,Set}::raw_table` now returns an immutable reference. (#404) - `VacantEntry` and `OccupiedEntry` now use the default hasher if none is specified in generics. (#389) - `RawTable::data_start` now returns a `NonNull` to match `RawTable::data_end`. (#387) - `RawIter::{reflect_insert, reflect_remove}` are now unsafe. (#429) - `RawTable::find_potential` is renamed to `find_or_find_insert_slot` and returns an `InsertSlot`. (#429) - `RawTable::remove` now also returns an `InsertSlot`. (#429) - `InsertSlot` can be used to insert an element with `RawTable::insert_in_slot`. (#429) - `RawIterHash` no longer has a lifetime tied to that of the `RawTable`. (#427) - The trait bounds of `HashSet::raw_table` have been relaxed to not require `Eq + Hash`. (#423) - `EntryRef::and_replace_entry_with` and `OccupiedEntryRef::replace_entry_with` were changed to give a `&K` instead of a `&Q` to the closure. ### Removed - Support for `bumpalo` as an allocator with custom wrapper. Use `allocator-api2` feature in `bumpalo` to use it as an allocator for `hashbrown` collections. (#417) ## [v0.13.2] - 2023-01-12 ### Fixed - Added `#[inline(always)]` to `find_inner`. (#375) - Fixed `RawTable::allocation_info` for empty tables. (#376) ## [v0.13.1] - 2022-11-10 ### Added - Added `Equivalent` trait to customize key lookups. (#350) - Added support for 16-bit targets. (#368) - Added `RawTable::allocation_info` which provides information about the memory usage of a table. (#371) ### Changed - Bumped MSRV to 1.61.0. - Upgraded to `ahash` 0.8. (#357) - Make `with_hasher_in` const. (#355) - The following methods have been removed from the `RawTable` API in favor of safer alternatives: - `RawTable::erase_no_drop` => Use `RawTable::erase` or `RawTable::remove` instead. - `Bucket::read` => Use `RawTable::remove` instead. - `Bucket::drop` => Use `RawTable::erase` instead. - `Bucket::write` => Use `Bucket::as_mut` instead. ### Fixed - Ensure that `HashMap` allocations don't exceed `isize::MAX`. (#362) - Fixed issue with field retagging in scopeguard. (#359) ## [v0.12.3] - 2022-07-17 ### Fixed - Fixed double-drop in `RawTable::clone_from`. (#348) ## [v0.12.2] - 2022-07-09 ### Added - Added `Entry` API for `HashSet`. (#342) - Added `Extend<&'a (K, V)> for HashMap`. (#340) - Added length-based short-circuiting for hash table iteration. (#338) - Added a function to access the `RawTable` of a `HashMap`. (#335) ### Changed - Edited `do_alloc` to reduce LLVM IR generated. (#341) ## [v0.12.1] - 2022-05-02 ### Fixed - Fixed underflow in `RawIterRange::size_hint`. (#325) - Fixed the implementation of `Debug` for `ValuesMut` and `IntoValues`. (#325) ## [v0.12.0] - 2022-01-17 ### Added - Added `From<[T; N]>` and `From<[(K, V); N]>` for `HashSet` and `HashMap` respectively. (#297) - Added an `allocator()` getter to HashMap and HashSet. (#257) - Added `insert_unique_unchecked` to `HashMap` and `HashSet`. (#293) - Added `into_keys` and `into_values` to HashMap. (#295) - Implement `From` on `HashSet` and `HashMap`. (#298) - Added `entry_ref` API to `HashMap`. (#201) ### Changed - Bumped minimum Rust version to 1.56.1 and edition to 2021. - Use u64 for the GroupWord on WebAssembly. (#271) - Optimized `find`. (#279) - Made rehashing and resizing less generic to reduce compilation time. (#282) - Inlined small functions. (#283) - Use `BuildHasher::hash_one` when `feature = "nightly"` is enabled. (#292) - Relaxed the bounds on `Debug` for `HashSet`. (#296) - Rename `get_each_mut` to `get_many_mut` and align API with the stdlib. (#291) - Don't hash the key when searching in an empty table. (#305) ### Fixed - Guard against allocations exceeding isize::MAX. (#268) - Made `RawTable::insert_no_grow` unsafe. (#254) - Inline `static_empty`. (#280) - Fixed trait bounds on Send/Sync impls. (#303) ## [v0.11.2] - 2021-03-25 ### Fixed - Added missing allocator type parameter to `HashMap`'s and `HashSet`'s `Clone` impls. (#252) ## [v0.11.1] - 2021-03-20 ### Fixed - Added missing `pub` modifier to `BumpWrapper`. (#251) ## [v0.11.0] - 2021-03-14 ### Added - Added safe `try_insert_no_grow` method to `RawTable`. (#229) - Added support for `bumpalo` as an allocator without the `nightly` feature. (#231) - Implemented `Default` for `RawTable`. (#237) - Added new safe methods `RawTable::get_each_mut`, `HashMap::get_each_mut`, and `HashMap::get_each_key_value_mut`. (#239) - Added `From>` for `HashSet`. (#235) - Added `try_insert` method to `HashMap`. (#247) ### Changed - The minimum Rust version has been bumped to 1.49.0. (#230) - Significantly improved compilation times by reducing the amount of generated IR. (#205) ### Removed - We no longer re-export the unstable allocator items from the standard library, nor the stable shims approximating the same. (#227) - Removed hasher specialization support from `aHash`, which was resulting in inconsistent hashes being generated for a key. (#248) ### Fixed - Fixed union length comparison. (#228) ## ~~[v0.10.0] - 2021-01-16~~ This release was _yanked_ due to inconsistent hashes being generated with the `nightly` feature. (#248) ### Changed - Parametrized `RawTable`, `HashSet` and `HashMap` over an allocator. (#133) - Improved branch prediction hints on stable. (#209) - Optimized hashing of primitive types with AHash using specialization. (#207) - Only instantiate `RawTable`'s reserve functions once per key-value. (#204) ## [v0.9.1] - 2020-09-28 ### Added - Added safe methods to `RawTable` (#202): - `get`: `find` and `as_ref` - `get_mut`: `find` and `as_mut` - `insert_entry`: `insert` and `as_mut` - `remove_entry`: `find` and `remove` - `erase_entry`: `find` and `erase` ### Changed - Removed `from_key_hashed_nocheck`'s `Q: Hash`. (#200) - Made `RawTable::drain` safe. (#201) ## [v0.9.0] - 2020-09-03 ### Fixed - `drain_filter` now removes and yields items that do match the predicate, rather than items that don't. This is a **breaking change** to match the behavior of the `drain_filter` methods in `std`. (#187) ### Added - Added `replace_entry_with` to `OccupiedEntry`, and `and_replace_entry_with` to `Entry`. (#190) - Implemented `FusedIterator` and `size_hint` for `DrainFilter`. (#188) ### Changed - The minimum Rust version has been bumped to 1.36 (due to `crossbeam` dependency). (#193) - Updated `ahash` dependency to 0.4. (#198) - `HashMap::with_hasher` and `HashSet::with_hasher` are now `const fn`. (#195) - Removed `T: Hash + Eq` and `S: BuildHasher` bounds on `HashSet::new`, `with_capacity`, `with_hasher`, and `with_capacity_and_hasher`. (#185) ## [v0.8.2] - 2020-08-08 ### Changed - Avoid closures to improve compile times. (#183) - Do not iterate to drop if empty. (#182) ## [v0.8.1] - 2020-07-16 ### Added - Added `erase` and `remove` to `RawTable`. (#171) - Added `try_with_capacity` to `RawTable`. (#174) - Added methods that allow re-using a `RawIter` for `RawDrain`, `RawIntoIter`, and `RawParIter`. (#175) - Added `reflect_remove` and `reflect_insert` to `RawIter`. (#175) - Added a `drain_filter` function to `HashSet`. (#179) ### Changed - Deprecated `RawTable::erase_no_drop` in favor of `erase` and `remove`. (#176) - `insert_no_grow` is now exposed under the `"raw"` feature. (#180) ## [v0.8.0] - 2020-06-18 ### Fixed - Marked `RawTable::par_iter` as `unsafe`. (#157) ### Changed - Reduced the size of `HashMap`. (#159) - No longer create tables with a capacity of 1 element. (#162) - Removed `K: Eq + Hash` bounds on `retain`. (#163) - Pulled in `HashMap` changes from rust-lang/rust (#164): - `extend_one` support on nightly. - `CollectionAllocErr` renamed to `TryReserveError`. - Added `HashSet::get_or_insert_owned`. - `Default` for `HashSet` no longer requires `T: Eq + Hash` and `S: BuildHasher`. ## [v0.7.2] - 2020-04-27 ### Added - Added `or_insert_with_key` to `Entry`. (#152) ### Fixed - Partially reverted `Clone` optimization which was unsound. (#154) ### Changed - Disabled use of `const-random` by default, which prevented reproducible builds. (#155) - Optimized `repeat` function. (#150) - Use `NonNull` for buckets, which improves codegen for iterators. (#148) ## [v0.7.1] - 2020-03-16 ### Added - Added `HashMap::get_key_value_mut`. (#145) ### Changed - Optimized `Clone` implementation. (#146) ## [v0.7.0] - 2020-01-31 ### Added - Added a `drain_filter` function to `HashMap`. (#135) ### Changed - Updated `ahash` dependency to 0.3. (#141) - Optimized set union and intersection. (#130) - `raw_entry` can now be used without requiring `S: BuildHasher`. (#123) - `RawTable::bucket_index` can now be used under the `raw` feature. (#128) ## [v0.6.3] - 2019-10-31 ### Added - Added an `ahash-compile-time-rng` feature (enabled by default) which allows disabling the `compile-time-rng` feature in `ahash` to work around a Cargo bug. (#125) ## [v0.6.2] - 2019-10-23 ### Added - Added an `inline-more` feature (enabled by default) which allows choosing a tradeoff between runtime performance and compilation time. (#119) ## [v0.6.1] - 2019-10-04 ### Added - Added `Entry::insert` and `RawEntryMut::insert`. (#118) ### Changed - `Group::static_empty` was changed from a `const` to a `static` (#116). ## [v0.6.0] - 2019-08-13 ### Fixed - Fixed AHash accidentally depending on `std`. (#110) ### Changed - The minimum Rust version has been bumped to 1.32 (due to `rand` dependency). ## ~~[v0.5.1] - 2019-08-04~~ This release was _yanked_ due to a breaking change for users of `no-default-features`. ### Added - The experimental and unsafe `RawTable` API is available under the "raw" feature. (#108) - Added entry-like methods for `HashSet`. (#98) ### Changed - Changed the default hasher from FxHash to AHash. (#97) - `hashbrown` is now fully `no_std` on recent Rust versions (1.36+). (#96) ### Fixed - We now avoid growing the table during insertions when it wasn't necessary. (#106) - `RawOccupiedEntryMut` now properly implements `Send` and `Sync`. (#100) - Relaxed `lazy_static` version. (#92) ## [v0.5.0] - 2019-06-12 ### Fixed - Resize with a more conservative amount of space after deletions. (#86) ### Changed - Exposed the Layout of the failed allocation in CollectionAllocErr::AllocErr. (#89) ## [v0.4.0] - 2019-05-30 ### Fixed - Fixed `Send` trait bounds on `IterMut` not matching the libstd one. (#82) ## [v0.3.1] - 2019-05-30 ### Fixed - Fixed incorrect use of slice in unsafe code. (#80) ## [v0.3.0] - 2019-04-23 ### Changed - Changed shrink_to to not panic if min_capacity < capacity. (#67) ### Fixed - Worked around emscripten bug emscripten-core/emscripten-fastcomp#258. (#66) ## [v0.2.2] - 2019-04-16 ### Fixed - Inlined non-nightly lowest_set_bit_nonzero. (#64) - Fixed build on latest nightly. (#65) ## [v0.2.1] - 2019-04-14 ### Changed - Use for_each in map Extend and FromIterator. (#58) - Improved worst-case performance of HashSet.is_subset. (#61) ### Fixed - Removed incorrect debug_assert. (#60) ## [v0.2.0] - 2019-03-31 ### Changed - The code has been updated to Rust 2018 edition. This means that the minimum Rust version has been bumped to 1.31 (2018 edition). ### Added - Added `insert_with_hasher` to the raw_entry API to allow `K: !(Hash + Eq)`. (#54) - Added support for using hashbrown as the hash table implementation in libstd. (#46) ### Fixed - Fixed cargo build with minimal-versions. (#45) - Fixed `#[may_dangle]` attributes to match the libstd `HashMap`. (#46) - ZST keys and values are now handled properly. (#46) ## [v0.1.8] - 2019-01-14 ### Added - Rayon parallel iterator support (#37) - `raw_entry` support (#31) - `#[may_dangle]` on nightly (#31) - `try_reserve` support (#31) ### Fixed - Fixed variance on `IterMut`. (#31) ## [v0.1.7] - 2018-12-05 ### Fixed - Fixed non-SSE version of convert_special_to_empty_and_full_to_deleted. (#32) - Fixed overflow in rehash_in_place. (#33) ## [v0.1.6] - 2018-11-17 ### Fixed - Fixed compile error on nightly. (#29) ## [v0.1.5] - 2018-11-08 ### Fixed - Fixed subtraction overflow in generic::Group::match_byte. (#28) ## [v0.1.4] - 2018-11-04 ### Fixed - Fixed a bug in the `erase_no_drop` implementation. (#26) ## [v0.1.3] - 2018-11-01 ### Added - Serde support. (#14) ### Fixed - Make the compiler inline functions more aggressively. (#20) ## [v0.1.2] - 2018-10-31 ### Fixed - `clear` segfaults when called on an empty table. (#13) ## [v0.1.1] - 2018-10-30 ### Fixed - `erase_no_drop` optimization not triggering in the SSE2 implementation. (#3) - Missing `Send` and `Sync` for hash map and iterator types. (#7) - Bug when inserting into a table smaller than the group width. (#5) ## v0.1.0 - 2018-10-29 - Initial release [Unreleased]: https://github.com/rust-lang/hashbrown/compare/v0.14.5...HEAD [v0.14.5]: https://github.com/rust-lang/hashbrown/compare/v0.14.4...v0.14.5 [v0.14.4]: https://github.com/rust-lang/hashbrown/compare/v0.14.3...v0.14.4 [v0.14.3]: https://github.com/rust-lang/hashbrown/compare/v0.14.2...v0.14.3 [v0.14.2]: https://github.com/rust-lang/hashbrown/compare/v0.14.1...v0.14.2 [v0.14.1]: https://github.com/rust-lang/hashbrown/compare/v0.14.0...v0.14.1 [v0.14.0]: https://github.com/rust-lang/hashbrown/compare/v0.13.2...v0.14.0 [v0.13.2]: https://github.com/rust-lang/hashbrown/compare/v0.13.1...v0.13.2 [v0.13.1]: https://github.com/rust-lang/hashbrown/compare/v0.12.3...v0.13.1 [v0.12.3]: https://github.com/rust-lang/hashbrown/compare/v0.12.2...v0.12.3 [v0.12.2]: https://github.com/rust-lang/hashbrown/compare/v0.12.1...v0.12.2 [v0.12.1]: https://github.com/rust-lang/hashbrown/compare/v0.12.0...v0.12.1 [v0.12.0]: https://github.com/rust-lang/hashbrown/compare/v0.11.2...v0.12.0 [v0.11.2]: https://github.com/rust-lang/hashbrown/compare/v0.11.1...v0.11.2 [v0.11.1]: https://github.com/rust-lang/hashbrown/compare/v0.11.0...v0.11.1 [v0.11.0]: https://github.com/rust-lang/hashbrown/compare/v0.10.0...v0.11.0 [v0.10.0]: https://github.com/rust-lang/hashbrown/compare/v0.9.1...v0.10.0 [v0.9.1]: https://github.com/rust-lang/hashbrown/compare/v0.9.0...v0.9.1 [v0.9.0]: https://github.com/rust-lang/hashbrown/compare/v0.8.2...v0.9.0 [v0.8.2]: https://github.com/rust-lang/hashbrown/compare/v0.8.1...v0.8.2 [v0.8.1]: https://github.com/rust-lang/hashbrown/compare/v0.8.0...v0.8.1 [v0.8.0]: https://github.com/rust-lang/hashbrown/compare/v0.7.2...v0.8.0 [v0.7.2]: https://github.com/rust-lang/hashbrown/compare/v0.7.1...v0.7.2 [v0.7.1]: https://github.com/rust-lang/hashbrown/compare/v0.7.0...v0.7.1 [v0.7.0]: https://github.com/rust-lang/hashbrown/compare/v0.6.3...v0.7.0 [v0.6.3]: https://github.com/rust-lang/hashbrown/compare/v0.6.2...v0.6.3 [v0.6.2]: https://github.com/rust-lang/hashbrown/compare/v0.6.1...v0.6.2 [v0.6.1]: https://github.com/rust-lang/hashbrown/compare/v0.6.0...v0.6.1 [v0.6.0]: https://github.com/rust-lang/hashbrown/compare/v0.5.1...v0.6.0 [v0.5.1]: https://github.com/rust-lang/hashbrown/compare/v0.5.0...v0.5.1 [v0.5.0]: https://github.com/rust-lang/hashbrown/compare/v0.4.0...v0.5.0 [v0.4.0]: https://github.com/rust-lang/hashbrown/compare/v0.3.1...v0.4.0 [v0.3.1]: https://github.com/rust-lang/hashbrown/compare/v0.3.0...v0.3.1 [v0.3.0]: https://github.com/rust-lang/hashbrown/compare/v0.2.2...v0.3.0 [v0.2.2]: https://github.com/rust-lang/hashbrown/compare/v0.2.1...v0.2.2 [v0.2.1]: https://github.com/rust-lang/hashbrown/compare/v0.2.0...v0.2.1 [v0.2.0]: https://github.com/rust-lang/hashbrown/compare/v0.1.8...v0.2.0 [v0.1.8]: https://github.com/rust-lang/hashbrown/compare/v0.1.7...v0.1.8 [v0.1.7]: https://github.com/rust-lang/hashbrown/compare/v0.1.6...v0.1.7 [v0.1.6]: https://github.com/rust-lang/hashbrown/compare/v0.1.5...v0.1.6 [v0.1.5]: https://github.com/rust-lang/hashbrown/compare/v0.1.4...v0.1.5 [v0.1.4]: https://github.com/rust-lang/hashbrown/compare/v0.1.3...v0.1.4 [v0.1.3]: https://github.com/rust-lang/hashbrown/compare/v0.1.2...v0.1.3 [v0.1.2]: https://github.com/rust-lang/hashbrown/compare/v0.1.1...v0.1.2 [v0.1.1]: https://github.com/rust-lang/hashbrown/compare/v0.1.0...v0.1.1 hashbrown-0.14.5/Cargo.toml0000644000000050700000000000100111160ustar # THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies. # # If you are reading this file be aware that the original Cargo.toml # will likely look very different (and much more reasonable). # See Cargo.toml.orig for the original contents. [package] edition = "2021" rust-version = "1.63.0" name = "hashbrown" version = "0.14.5" authors = ["Amanieu d'Antras "] exclude = [ ".github", "/ci/*", ] description = "A Rust port of Google's SwissTable hash map" readme = "README.md" keywords = [ "hash", "no_std", "hashmap", "swisstable", ] categories = [ "data-structures", "no-std", ] license = "MIT OR Apache-2.0" repository = "https://github.com/rust-lang/hashbrown" [package.metadata.docs.rs] features = [ "nightly", "rayon", "serde", "raw", ] rustdoc-args = ["--generate-link-to-definition"] [dependencies.ahash] version = "0.8.7" optional = true default-features = false [dependencies.alloc] version = "1.0.0" optional = true package = "rustc-std-workspace-alloc" [dependencies.allocator-api2] version = "0.2.9" features = ["alloc"] optional = true default-features = false [dependencies.compiler_builtins] version = "0.1.2" optional = true [dependencies.core] version = "1.0.0" optional = true package = "rustc-std-workspace-core" [dependencies.equivalent] version = "1.0" optional = true default-features = false [dependencies.rayon] version = "1.0" optional = true [dependencies.rkyv] version = "0.7.42" features = ["alloc"] optional = true default-features = false [dependencies.serde] version = "1.0.25" optional = true default-features = false [dev-dependencies.bumpalo] version = "3.13.0" features = ["allocator-api2"] [dev-dependencies.doc-comment] version = "0.3.1" [dev-dependencies.fnv] version = "1.0.7" [dev-dependencies.lazy_static] version = "1.4" [dev-dependencies.rand] version = "0.8.3" features = ["small_rng"] [dev-dependencies.rayon] version = "1.0" [dev-dependencies.rkyv] version = "0.7.42" features = ["validation"] [dev-dependencies.serde_test] version = "1.0" [features] default = [ "ahash", "inline-more", "allocator-api2", ] inline-more = [] nightly = [ "allocator-api2?/nightly", "bumpalo/allocator_api", ] raw = [] rustc-dep-of-std = [ "nightly", "core", "compiler_builtins", "alloc", "rustc-internal-api", ] rustc-internal-api = [] hashbrown-0.14.5/Cargo.toml.orig000064400000000000000000000043071046102023000146010ustar 00000000000000[package] name = "hashbrown" version = "0.14.5" authors = ["Amanieu d'Antras "] description = "A Rust port of Google's SwissTable hash map" license = "MIT OR Apache-2.0" repository = "https://github.com/rust-lang/hashbrown" readme = "README.md" keywords = ["hash", "no_std", "hashmap", "swisstable"] categories = ["data-structures", "no-std"] exclude = [".github", "/ci/*"] edition = "2021" rust-version = "1.63.0" [dependencies] # For the default hasher ahash = { version = "0.8.7", default-features = false, optional = true } # For external trait impls rayon = { version = "1.0", optional = true } serde = { version = "1.0.25", default-features = false, optional = true } rkyv = { version = "0.7.42", optional = true, default-features = false, features = [ "alloc", ] } # When built as part of libstd core = { version = "1.0.0", optional = true, package = "rustc-std-workspace-core" } compiler_builtins = { version = "0.1.2", optional = true } alloc = { version = "1.0.0", optional = true, package = "rustc-std-workspace-alloc" } # Support for allocators that use allocator-api2 allocator-api2 = { version = "0.2.9", optional = true, default-features = false, features = [ "alloc", ] } # Equivalent trait which can be shared with other hash table implementations. equivalent = { version = "1.0", optional = true, default-features = false } [dev-dependencies] lazy_static = "1.4" rand = { version = "0.8.3", features = ["small_rng"] } rayon = "1.0" fnv = "1.0.7" serde_test = "1.0" doc-comment = "0.3.1" bumpalo = { version = "3.13.0", features = ["allocator-api2"] } rkyv = { version = "0.7.42", features = ["validation"] } [features] default = ["ahash", "inline-more", "allocator-api2"] nightly = ["allocator-api2?/nightly", "bumpalo/allocator_api"] rustc-internal-api = [] rustc-dep-of-std = [ "nightly", "core", "compiler_builtins", "alloc", "rustc-internal-api", ] raw = [] # Enables usage of `#[inline]` on far more functions than by default in this # crate. This may lead to a performance increase but often comes at a compile # time cost. inline-more = [] [package.metadata.docs.rs] features = ["nightly", "rayon", "serde", "raw"] rustdoc-args = ["--generate-link-to-definition"] hashbrown-0.14.5/LICENSE-APACHE000064400000000000000000000251371046102023000136420ustar 00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. hashbrown-0.14.5/LICENSE-MIT000064400000000000000000000020441046102023000133420ustar 00000000000000Copyright (c) 2016 Amanieu d'Antras Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. hashbrown-0.14.5/README.md000064400000000000000000000157001046102023000131700ustar 00000000000000hashbrown ========= [![Build Status](https://github.com/rust-lang/hashbrown/actions/workflows/rust.yml/badge.svg)](https://github.com/rust-lang/hashbrown/actions) [![Crates.io](https://img.shields.io/crates/v/hashbrown.svg)](https://crates.io/crates/hashbrown) [![Documentation](https://docs.rs/hashbrown/badge.svg)](https://docs.rs/hashbrown) [![Rust](https://img.shields.io/badge/rust-1.63.0%2B-blue.svg?maxAge=3600)](https://github.com/rust-lang/hashbrown) This crate is a Rust port of Google's high-performance [SwissTable] hash map, adapted to make it a drop-in replacement for Rust's standard `HashMap` and `HashSet` types. The original C++ version of SwissTable can be found [here], and this [CppCon talk] gives an overview of how the algorithm works. Since Rust 1.36, this is now the `HashMap` implementation for the Rust standard library. However you may still want to use this crate instead since it works in environments without `std`, such as embedded systems and kernels. [SwissTable]: https://abseil.io/blog/20180927-swisstables [here]: https://github.com/abseil/abseil-cpp/blob/master/absl/container/internal/raw_hash_set.h [CppCon talk]: https://www.youtube.com/watch?v=ncHmEUmJZf4 ## [Change log](CHANGELOG.md) ## Features - Drop-in replacement for the standard library `HashMap` and `HashSet` types. - Uses [AHash](https://github.com/tkaitchuck/aHash) as the default hasher, which is much faster than SipHash. However, AHash does *not provide the same level of HashDoS resistance* as SipHash, so if that is important to you, you might want to consider using a different hasher. - Around 2x faster than the previous standard library `HashMap`. - Lower memory usage: only 1 byte of overhead per entry instead of 8. - Compatible with `#[no_std]` (but requires a global allocator with the `alloc` crate). - Empty hash maps do not allocate any memory. - SIMD lookups to scan multiple hash entries in parallel. ## Performance Compared to the previous implementation of `std::collections::HashMap` (Rust 1.35). With the hashbrown default AHash hasher: | name | oldstdhash ns/iter | hashbrown ns/iter | diff ns/iter | diff % | speedup | | :-------------------------- | :----------------: | ----------------: | :----------: | ------: | ------- | | insert_ahash_highbits | 18,865 | 8,020 | -10,845 | -57.49% | x 2.35 | | insert_ahash_random | 19,711 | 8,019 | -11,692 | -59.32% | x 2.46 | | insert_ahash_serial | 19,365 | 6,463 | -12,902 | -66.63% | x 3.00 | | insert_erase_ahash_highbits | 51,136 | 17,916 | -33,220 | -64.96% | x 2.85 | | insert_erase_ahash_random | 51,157 | 17,688 | -33,469 | -65.42% | x 2.89 | | insert_erase_ahash_serial | 45,479 | 14,895 | -30,584 | -67.25% | x 3.05 | | iter_ahash_highbits | 1,399 | 1,092 | -307 | -21.94% | x 1.28 | | iter_ahash_random | 1,586 | 1,059 | -527 | -33.23% | x 1.50 | | iter_ahash_serial | 3,168 | 1,079 | -2,089 | -65.94% | x 2.94 | | lookup_ahash_highbits | 32,351 | 4,792 | -27,559 | -85.19% | x 6.75 | | lookup_ahash_random | 17,419 | 4,817 | -12,602 | -72.35% | x 3.62 | | lookup_ahash_serial | 15,254 | 3,606 | -11,648 | -76.36% | x 4.23 | | lookup_fail_ahash_highbits | 21,187 | 4,369 | -16,818 | -79.38% | x 4.85 | | lookup_fail_ahash_random | 21,550 | 4,395 | -17,155 | -79.61% | x 4.90 | | lookup_fail_ahash_serial | 19,450 | 3,176 | -16,274 | -83.67% | x 6.12 | With the libstd default SipHash hasher: | name | oldstdhash ns/iter | hashbrown ns/iter | diff ns/iter | diff % | speedup | | :------------------------ | :----------------: | ----------------: | :----------: | ------: | ------- | | insert_std_highbits | 19,216 | 16,885 | -2,331 | -12.13% | x 1.14 | | insert_std_random | 19,179 | 17,034 | -2,145 | -11.18% | x 1.13 | | insert_std_serial | 19,462 | 17,493 | -1,969 | -10.12% | x 1.11 | | insert_erase_std_highbits | 50,825 | 35,847 | -14,978 | -29.47% | x 1.42 | | insert_erase_std_random | 51,448 | 35,392 | -16,056 | -31.21% | x 1.45 | | insert_erase_std_serial | 87,711 | 38,091 | -49,620 | -56.57% | x 2.30 | | iter_std_highbits | 1,378 | 1,159 | -219 | -15.89% | x 1.19 | | iter_std_random | 1,395 | 1,132 | -263 | -18.85% | x 1.23 | | iter_std_serial | 1,704 | 1,105 | -599 | -35.15% | x 1.54 | | lookup_std_highbits | 17,195 | 13,642 | -3,553 | -20.66% | x 1.26 | | lookup_std_random | 17,181 | 13,773 | -3,408 | -19.84% | x 1.25 | | lookup_std_serial | 15,483 | 13,651 | -1,832 | -11.83% | x 1.13 | | lookup_fail_std_highbits | 20,926 | 13,474 | -7,452 | -35.61% | x 1.55 | | lookup_fail_std_random | 21,766 | 13,505 | -8,261 | -37.95% | x 1.61 | | lookup_fail_std_serial | 19,336 | 13,519 | -5,817 | -30.08% | x 1.43 | ## Usage Add this to your `Cargo.toml`: ```toml [dependencies] hashbrown = "0.14" ``` Then: ```rust use hashbrown::HashMap; let mut map = HashMap::new(); map.insert(1, "one"); ``` ## Flags This crate has the following Cargo features: - `nightly`: Enables nightly-only features including: `#[may_dangle]`. - `serde`: Enables serde serialization support. - `rkyv`: Enables rkyv serialization support. - `rayon`: Enables rayon parallel iterator support. - `raw`: Enables access to the experimental and unsafe `RawTable` API. - `inline-more`: Adds inline hints to most functions, improving run-time performance at the cost of compilation time. (enabled by default) - `ahash`: Compiles with ahash as default hasher. (enabled by default) - `allocator-api2`: Enables support for allocators that support `allocator-api2`. (enabled by default) ## License Licensed under either of: * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) * MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) at your option. ### Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. hashbrown-0.14.5/benches/bench.rs000064400000000000000000000204071046102023000147450ustar 00000000000000// This benchmark suite contains some benchmarks along a set of dimensions: // Hasher: std default (SipHash) and crate default (AHash). // Int key distribution: low bit heavy, top bit heavy, and random. // Task: basic functionality: insert, insert_erase, lookup, lookup_fail, iter #![feature(test)] extern crate test; use test::{black_box, Bencher}; use hashbrown::hash_map::DefaultHashBuilder; use hashbrown::{HashMap, HashSet}; use std::{ collections::hash_map::RandomState, sync::atomic::{self, AtomicUsize}, }; const SIZE: usize = 1000; // The default hashmap when using this crate directly. type AHashMap = HashMap; // This uses the hashmap from this crate with the default hasher of the stdlib. type StdHashMap = HashMap; // A random key iterator. #[derive(Clone, Copy)] struct RandomKeys { state: usize, } impl RandomKeys { fn new() -> Self { RandomKeys { state: 0 } } } impl Iterator for RandomKeys { type Item = usize; fn next(&mut self) -> Option { // Add 1 then multiply by some 32 bit prime. self.state = self.state.wrapping_add(1).wrapping_mul(3_787_392_781); Some(self.state) } } // Just an arbitrary side effect to make the maps not shortcircuit to the non-dropping path // when dropping maps/entries (most real world usages likely have drop in the key or value) lazy_static::lazy_static! { static ref SIDE_EFFECT: AtomicUsize = AtomicUsize::new(0); } #[derive(Clone)] struct DropType(usize); impl Drop for DropType { fn drop(&mut self) { SIDE_EFFECT.fetch_add(self.0, atomic::Ordering::SeqCst); } } macro_rules! bench_suite { ($bench_macro:ident, $bench_ahash_serial:ident, $bench_std_serial:ident, $bench_ahash_highbits:ident, $bench_std_highbits:ident, $bench_ahash_random:ident, $bench_std_random:ident) => { $bench_macro!($bench_ahash_serial, AHashMap, 0..); $bench_macro!($bench_std_serial, StdHashMap, 0..); $bench_macro!( $bench_ahash_highbits, AHashMap, (0..).map(usize::swap_bytes) ); $bench_macro!( $bench_std_highbits, StdHashMap, (0..).map(usize::swap_bytes) ); $bench_macro!($bench_ahash_random, AHashMap, RandomKeys::new()); $bench_macro!($bench_std_random, StdHashMap, RandomKeys::new()); }; } macro_rules! bench_insert { ($name:ident, $maptype:ident, $keydist:expr) => { #[bench] fn $name(b: &mut Bencher) { let mut m = $maptype::with_capacity_and_hasher(SIZE, Default::default()); b.iter(|| { m.clear(); for i in ($keydist).take(SIZE) { m.insert(i, (DropType(i), [i; 20])); } black_box(&mut m); }); eprintln!("{}", SIDE_EFFECT.load(atomic::Ordering::SeqCst)); } }; } bench_suite!( bench_insert, insert_ahash_serial, insert_std_serial, insert_ahash_highbits, insert_std_highbits, insert_ahash_random, insert_std_random ); macro_rules! bench_grow_insert { ($name:ident, $maptype:ident, $keydist:expr) => { #[bench] fn $name(b: &mut Bencher) { b.iter(|| { let mut m = $maptype::default(); for i in ($keydist).take(SIZE) { m.insert(i, DropType(i)); } black_box(&mut m); }) } }; } bench_suite!( bench_grow_insert, grow_insert_ahash_serial, grow_insert_std_serial, grow_insert_ahash_highbits, grow_insert_std_highbits, grow_insert_ahash_random, grow_insert_std_random ); macro_rules! bench_insert_erase { ($name:ident, $maptype:ident, $keydist:expr) => { #[bench] fn $name(b: &mut Bencher) { let mut base = $maptype::default(); for i in ($keydist).take(SIZE) { base.insert(i, DropType(i)); } let skip = $keydist.skip(SIZE); b.iter(|| { let mut m = base.clone(); let mut add_iter = skip.clone(); let mut remove_iter = $keydist; // While keeping the size constant, // replace the first keydist with the second. for (add, remove) in (&mut add_iter).zip(&mut remove_iter).take(SIZE) { m.insert(add, DropType(add)); black_box(m.remove(&remove)); } black_box(m); }); eprintln!("{}", SIDE_EFFECT.load(atomic::Ordering::SeqCst)); } }; } bench_suite!( bench_insert_erase, insert_erase_ahash_serial, insert_erase_std_serial, insert_erase_ahash_highbits, insert_erase_std_highbits, insert_erase_ahash_random, insert_erase_std_random ); macro_rules! bench_lookup { ($name:ident, $maptype:ident, $keydist:expr) => { #[bench] fn $name(b: &mut Bencher) { let mut m = $maptype::default(); for i in $keydist.take(SIZE) { m.insert(i, DropType(i)); } b.iter(|| { for i in $keydist.take(SIZE) { black_box(m.get(&i)); } }); eprintln!("{}", SIDE_EFFECT.load(atomic::Ordering::SeqCst)); } }; } bench_suite!( bench_lookup, lookup_ahash_serial, lookup_std_serial, lookup_ahash_highbits, lookup_std_highbits, lookup_ahash_random, lookup_std_random ); macro_rules! bench_lookup_fail { ($name:ident, $maptype:ident, $keydist:expr) => { #[bench] fn $name(b: &mut Bencher) { let mut m = $maptype::default(); let mut iter = $keydist; for i in (&mut iter).take(SIZE) { m.insert(i, DropType(i)); } b.iter(|| { for i in (&mut iter).take(SIZE) { black_box(m.get(&i)); } }) } }; } bench_suite!( bench_lookup_fail, lookup_fail_ahash_serial, lookup_fail_std_serial, lookup_fail_ahash_highbits, lookup_fail_std_highbits, lookup_fail_ahash_random, lookup_fail_std_random ); macro_rules! bench_iter { ($name:ident, $maptype:ident, $keydist:expr) => { #[bench] fn $name(b: &mut Bencher) { let mut m = $maptype::default(); for i in ($keydist).take(SIZE) { m.insert(i, DropType(i)); } b.iter(|| { for i in &m { black_box(i); } }) } }; } bench_suite!( bench_iter, iter_ahash_serial, iter_std_serial, iter_ahash_highbits, iter_std_highbits, iter_ahash_random, iter_std_random ); #[bench] fn clone_small(b: &mut Bencher) { let mut m = HashMap::new(); for i in 0..10 { m.insert(i, DropType(i)); } b.iter(|| { black_box(m.clone()); }) } #[bench] fn clone_from_small(b: &mut Bencher) { let mut m = HashMap::new(); let mut m2 = HashMap::new(); for i in 0..10 { m.insert(i, DropType(i)); } b.iter(|| { m2.clone_from(&m); black_box(&mut m2); }) } #[bench] fn clone_large(b: &mut Bencher) { let mut m = HashMap::new(); for i in 0..1000 { m.insert(i, DropType(i)); } b.iter(|| { black_box(m.clone()); }) } #[bench] fn clone_from_large(b: &mut Bencher) { let mut m = HashMap::new(); let mut m2 = HashMap::new(); for i in 0..1000 { m.insert(i, DropType(i)); } b.iter(|| { m2.clone_from(&m); black_box(&mut m2); }) } #[bench] fn rehash_in_place(b: &mut Bencher) { b.iter(|| { let mut set = HashSet::new(); // Each loop triggers one rehash for _ in 0..10 { for i in 0..223 { set.insert(i); } assert_eq!( set.capacity(), 224, "The set must be at or close to capacity to trigger a re hashing" ); for i in 100..1400 { set.remove(&(i - 100)); set.insert(i); } set.clear(); } }); } hashbrown-0.14.5/benches/insert_unique_unchecked.rs000064400000000000000000000013361046102023000205710ustar 00000000000000//! Compare `insert` and `insert_unique_unchecked` operations performance. #![feature(test)] extern crate test; use hashbrown::HashMap; use test::Bencher; #[bench] fn insert(b: &mut Bencher) { let keys: Vec = (0..1000).map(|i| format!("xxxx{}yyyy", i)).collect(); b.iter(|| { let mut m = HashMap::with_capacity(1000); for k in &keys { m.insert(k, k); } m }); } #[bench] fn insert_unique_unchecked(b: &mut Bencher) { let keys: Vec = (0..1000).map(|i| format!("xxxx{}yyyy", i)).collect(); b.iter(|| { let mut m = HashMap::with_capacity(1000); for k in &keys { m.insert_unique_unchecked(k, k); } m }); } hashbrown-0.14.5/clippy.toml000064400000000000000000000001041046102023000140760ustar 00000000000000doc-valid-idents = [ "CppCon", "SwissTable", "SipHash", "HashDoS" ] hashbrown-0.14.5/src/external_trait_impls/mod.rs000064400000000000000000000001701046102023000200510ustar 00000000000000#[cfg(feature = "rayon")] pub(crate) mod rayon; #[cfg(feature = "rkyv")] mod rkyv; #[cfg(feature = "serde")] mod serde; hashbrown-0.14.5/src/external_trait_impls/rayon/helpers.rs000064400000000000000000000014721046102023000220720ustar 00000000000000use alloc::collections::LinkedList; use alloc::vec::Vec; use rayon::iter::{IntoParallelIterator, ParallelIterator}; /// Helper for collecting parallel iterators to an intermediary #[allow(clippy::linkedlist)] // yes, we need linked list here for efficient appending! pub(super) fn collect(iter: I) -> (LinkedList>, usize) { let list = iter .into_par_iter() .fold(Vec::new, |mut vec, elem| { vec.push(elem); vec }) .map(|vec| { let mut list = LinkedList::new(); list.push_back(vec); list }) .reduce(LinkedList::new, |mut list1, mut list2| { list1.append(&mut list2); list1 }); let len = list.iter().map(Vec::len).sum(); (list, len) } hashbrown-0.14.5/src/external_trait_impls/rayon/map.rs000064400000000000000000000516121046102023000212060ustar 00000000000000//! Rayon extensions for `HashMap`. use super::raw::{RawIntoParIter, RawParDrain, RawParIter}; use crate::hash_map::HashMap; use crate::raw::{Allocator, Global}; use core::fmt; use core::hash::{BuildHasher, Hash}; use core::marker::PhantomData; use rayon::iter::plumbing::UnindexedConsumer; use rayon::iter::{FromParallelIterator, IntoParallelIterator, ParallelExtend, ParallelIterator}; /// Parallel iterator over shared references to entries in a map. /// /// This iterator is created by the [`par_iter`] method on [`HashMap`] /// (provided by the [`IntoParallelRefIterator`] trait). /// See its documentation for more. /// /// [`par_iter`]: /hashbrown/struct.HashMap.html#method.par_iter /// [`HashMap`]: /hashbrown/struct.HashMap.html /// [`IntoParallelRefIterator`]: https://docs.rs/rayon/1.0/rayon/iter/trait.IntoParallelRefIterator.html pub struct ParIter<'a, K, V> { inner: RawParIter<(K, V)>, marker: PhantomData<(&'a K, &'a V)>, } impl<'a, K: Sync, V: Sync> ParallelIterator for ParIter<'a, K, V> { type Item = (&'a K, &'a V); #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner .map(|x| unsafe { let r = x.as_ref(); (&r.0, &r.1) }) .drive_unindexed(consumer) } } impl Clone for ParIter<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Self { inner: self.inner.clone(), marker: PhantomData, } } } impl fmt::Debug for ParIter<'_, K, V> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let iter = unsafe { self.inner.iter() }.map(|x| unsafe { let r = x.as_ref(); (&r.0, &r.1) }); f.debug_list().entries(iter).finish() } } /// Parallel iterator over shared references to keys in a map. /// /// This iterator is created by the [`par_keys`] method on [`HashMap`]. /// See its documentation for more. /// /// [`par_keys`]: /hashbrown/struct.HashMap.html#method.par_keys /// [`HashMap`]: /hashbrown/struct.HashMap.html pub struct ParKeys<'a, K, V> { inner: RawParIter<(K, V)>, marker: PhantomData<(&'a K, &'a V)>, } impl<'a, K: Sync, V: Sync> ParallelIterator for ParKeys<'a, K, V> { type Item = &'a K; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner .map(|x| unsafe { &x.as_ref().0 }) .drive_unindexed(consumer) } } impl Clone for ParKeys<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Self { inner: self.inner.clone(), marker: PhantomData, } } } impl fmt::Debug for ParKeys<'_, K, V> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let iter = unsafe { self.inner.iter() }.map(|x| unsafe { &x.as_ref().0 }); f.debug_list().entries(iter).finish() } } /// Parallel iterator over shared references to values in a map. /// /// This iterator is created by the [`par_values`] method on [`HashMap`]. /// See its documentation for more. /// /// [`par_values`]: /hashbrown/struct.HashMap.html#method.par_values /// [`HashMap`]: /hashbrown/struct.HashMap.html pub struct ParValues<'a, K, V> { inner: RawParIter<(K, V)>, marker: PhantomData<(&'a K, &'a V)>, } impl<'a, K: Sync, V: Sync> ParallelIterator for ParValues<'a, K, V> { type Item = &'a V; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner .map(|x| unsafe { &x.as_ref().1 }) .drive_unindexed(consumer) } } impl Clone for ParValues<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Self { inner: self.inner.clone(), marker: PhantomData, } } } impl fmt::Debug for ParValues<'_, K, V> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let iter = unsafe { self.inner.iter() }.map(|x| unsafe { &x.as_ref().1 }); f.debug_list().entries(iter).finish() } } /// Parallel iterator over mutable references to entries in a map. /// /// This iterator is created by the [`par_iter_mut`] method on [`HashMap`] /// (provided by the [`IntoParallelRefMutIterator`] trait). /// See its documentation for more. /// /// [`par_iter_mut`]: /hashbrown/struct.HashMap.html#method.par_iter_mut /// [`HashMap`]: /hashbrown/struct.HashMap.html /// [`IntoParallelRefMutIterator`]: https://docs.rs/rayon/1.0/rayon/iter/trait.IntoParallelRefMutIterator.html pub struct ParIterMut<'a, K, V> { inner: RawParIter<(K, V)>, marker: PhantomData<(&'a K, &'a mut V)>, } impl<'a, K: Sync, V: Send> ParallelIterator for ParIterMut<'a, K, V> { type Item = (&'a K, &'a mut V); #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner .map(|x| unsafe { let r = x.as_mut(); (&r.0, &mut r.1) }) .drive_unindexed(consumer) } } impl fmt::Debug for ParIterMut<'_, K, V> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { ParIter { inner: self.inner.clone(), marker: PhantomData, } .fmt(f) } } /// Parallel iterator over mutable references to values in a map. /// /// This iterator is created by the [`par_values_mut`] method on [`HashMap`]. /// See its documentation for more. /// /// [`par_values_mut`]: /hashbrown/struct.HashMap.html#method.par_values_mut /// [`HashMap`]: /hashbrown/struct.HashMap.html pub struct ParValuesMut<'a, K, V> { inner: RawParIter<(K, V)>, marker: PhantomData<(&'a K, &'a mut V)>, } impl<'a, K: Sync, V: Send> ParallelIterator for ParValuesMut<'a, K, V> { type Item = &'a mut V; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner .map(|x| unsafe { &mut x.as_mut().1 }) .drive_unindexed(consumer) } } impl fmt::Debug for ParValuesMut<'_, K, V> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { ParValues { inner: self.inner.clone(), marker: PhantomData, } .fmt(f) } } /// Parallel iterator over entries of a consumed map. /// /// This iterator is created by the [`into_par_iter`] method on [`HashMap`] /// (provided by the [`IntoParallelIterator`] trait). /// See its documentation for more. /// /// [`into_par_iter`]: /hashbrown/struct.HashMap.html#method.into_par_iter /// [`HashMap`]: /hashbrown/struct.HashMap.html /// [`IntoParallelIterator`]: https://docs.rs/rayon/1.0/rayon/iter/trait.IntoParallelIterator.html pub struct IntoParIter { inner: RawIntoParIter<(K, V), A>, } impl ParallelIterator for IntoParIter { type Item = (K, V); #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner.drive_unindexed(consumer) } } impl fmt::Debug for IntoParIter { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { ParIter { inner: unsafe { self.inner.par_iter() }, marker: PhantomData, } .fmt(f) } } /// Parallel draining iterator over entries of a map. /// /// This iterator is created by the [`par_drain`] method on [`HashMap`]. /// See its documentation for more. /// /// [`par_drain`]: /hashbrown/struct.HashMap.html#method.par_drain /// [`HashMap`]: /hashbrown/struct.HashMap.html pub struct ParDrain<'a, K, V, A: Allocator = Global> { inner: RawParDrain<'a, (K, V), A>, } impl ParallelIterator for ParDrain<'_, K, V, A> { type Item = (K, V); #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner.drive_unindexed(consumer) } } impl fmt::Debug for ParDrain<'_, K, V, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { ParIter { inner: unsafe { self.inner.par_iter() }, marker: PhantomData, } .fmt(f) } } impl HashMap { /// Visits (potentially in parallel) immutably borrowed keys in an arbitrary order. #[cfg_attr(feature = "inline-more", inline)] pub fn par_keys(&self) -> ParKeys<'_, K, V> { ParKeys { inner: unsafe { self.table.par_iter() }, marker: PhantomData, } } /// Visits (potentially in parallel) immutably borrowed values in an arbitrary order. #[cfg_attr(feature = "inline-more", inline)] pub fn par_values(&self) -> ParValues<'_, K, V> { ParValues { inner: unsafe { self.table.par_iter() }, marker: PhantomData, } } } impl HashMap { /// Visits (potentially in parallel) mutably borrowed values in an arbitrary order. #[cfg_attr(feature = "inline-more", inline)] pub fn par_values_mut(&mut self) -> ParValuesMut<'_, K, V> { ParValuesMut { inner: unsafe { self.table.par_iter() }, marker: PhantomData, } } /// Consumes (potentially in parallel) all values in an arbitrary order, /// while preserving the map's allocated memory for reuse. #[cfg_attr(feature = "inline-more", inline)] pub fn par_drain(&mut self) -> ParDrain<'_, K, V, A> { ParDrain { inner: self.table.par_drain(), } } } impl HashMap where K: Eq + Hash + Sync, V: PartialEq + Sync, S: BuildHasher + Sync, A: Allocator + Sync, { /// Returns `true` if the map is equal to another, /// i.e. both maps contain the same keys mapped to the same values. /// /// This method runs in a potentially parallel fashion. pub fn par_eq(&self, other: &Self) -> bool { self.len() == other.len() && self .into_par_iter() .all(|(key, value)| other.get(key).map_or(false, |v| *value == *v)) } } impl IntoParallelIterator for HashMap { type Item = (K, V); type Iter = IntoParIter; #[cfg_attr(feature = "inline-more", inline)] fn into_par_iter(self) -> Self::Iter { IntoParIter { inner: self.table.into_par_iter(), } } } impl<'a, K: Sync, V: Sync, S, A: Allocator> IntoParallelIterator for &'a HashMap { type Item = (&'a K, &'a V); type Iter = ParIter<'a, K, V>; #[cfg_attr(feature = "inline-more", inline)] fn into_par_iter(self) -> Self::Iter { ParIter { inner: unsafe { self.table.par_iter() }, marker: PhantomData, } } } impl<'a, K: Sync, V: Send, S, A: Allocator> IntoParallelIterator for &'a mut HashMap { type Item = (&'a K, &'a mut V); type Iter = ParIterMut<'a, K, V>; #[cfg_attr(feature = "inline-more", inline)] fn into_par_iter(self) -> Self::Iter { ParIterMut { inner: unsafe { self.table.par_iter() }, marker: PhantomData, } } } /// Collect (key, value) pairs from a parallel iterator into a /// hashmap. If multiple pairs correspond to the same key, then the /// ones produced earlier in the parallel iterator will be /// overwritten, just as with a sequential iterator. impl FromParallelIterator<(K, V)> for HashMap where K: Eq + Hash + Send, V: Send, S: BuildHasher + Default, { fn from_par_iter

(par_iter: P) -> Self where P: IntoParallelIterator, { let mut map = HashMap::default(); map.par_extend(par_iter); map } } /// Extend a hash map with items from a parallel iterator. impl ParallelExtend<(K, V)> for HashMap where K: Eq + Hash + Send, V: Send, S: BuildHasher, A: Allocator, { fn par_extend(&mut self, par_iter: I) where I: IntoParallelIterator, { extend(self, par_iter); } } /// Extend a hash map with copied items from a parallel iterator. impl<'a, K, V, S, A> ParallelExtend<(&'a K, &'a V)> for HashMap where K: Copy + Eq + Hash + Sync, V: Copy + Sync, S: BuildHasher, A: Allocator, { fn par_extend(&mut self, par_iter: I) where I: IntoParallelIterator, { extend(self, par_iter); } } // This is equal to the normal `HashMap` -- no custom advantage. fn extend(map: &mut HashMap, par_iter: I) where K: Eq + Hash, S: BuildHasher, I: IntoParallelIterator, A: Allocator, HashMap: Extend, { let (list, len) = super::helpers::collect(par_iter); // Keys may be already present or show multiple times in the iterator. // Reserve the entire length if the map is empty. // Otherwise reserve half the length (rounded up), so the map // will only resize twice in the worst case. let reserve = if map.is_empty() { len } else { (len + 1) / 2 }; map.reserve(reserve); for vec in list { map.extend(vec); } } #[cfg(test)] mod test_par_map { use alloc::vec::Vec; use core::hash::{Hash, Hasher}; use core::sync::atomic::{AtomicUsize, Ordering}; use rayon::prelude::*; use crate::hash_map::HashMap; struct Dropable<'a> { k: usize, counter: &'a AtomicUsize, } impl Dropable<'_> { fn new(k: usize, counter: &AtomicUsize) -> Dropable<'_> { counter.fetch_add(1, Ordering::Relaxed); Dropable { k, counter } } } impl Drop for Dropable<'_> { fn drop(&mut self) { self.counter.fetch_sub(1, Ordering::Relaxed); } } impl Clone for Dropable<'_> { fn clone(&self) -> Self { Dropable::new(self.k, self.counter) } } impl Hash for Dropable<'_> { fn hash(&self, state: &mut H) where H: Hasher, { self.k.hash(state); } } impl PartialEq for Dropable<'_> { fn eq(&self, other: &Self) -> bool { self.k == other.k } } impl Eq for Dropable<'_> {} #[test] fn test_into_iter_drops() { let key = AtomicUsize::new(0); let value = AtomicUsize::new(0); let hm = { let mut hm = HashMap::new(); assert_eq!(key.load(Ordering::Relaxed), 0); assert_eq!(value.load(Ordering::Relaxed), 0); for i in 0..100 { let d1 = Dropable::new(i, &key); let d2 = Dropable::new(i + 100, &value); hm.insert(d1, d2); } assert_eq!(key.load(Ordering::Relaxed), 100); assert_eq!(value.load(Ordering::Relaxed), 100); hm }; // By the way, ensure that cloning doesn't screw up the dropping. drop(hm.clone()); assert_eq!(key.load(Ordering::Relaxed), 100); assert_eq!(value.load(Ordering::Relaxed), 100); // Ensure that dropping the iterator does not leak anything. drop(hm.clone().into_par_iter()); { assert_eq!(key.load(Ordering::Relaxed), 100); assert_eq!(value.load(Ordering::Relaxed), 100); // retain only half let _v: Vec<_> = hm.into_par_iter().filter(|(key, _)| key.k < 50).collect(); assert_eq!(key.load(Ordering::Relaxed), 50); assert_eq!(value.load(Ordering::Relaxed), 50); }; assert_eq!(key.load(Ordering::Relaxed), 0); assert_eq!(value.load(Ordering::Relaxed), 0); } #[test] fn test_drain_drops() { let key = AtomicUsize::new(0); let value = AtomicUsize::new(0); let mut hm = { let mut hm = HashMap::new(); assert_eq!(key.load(Ordering::Relaxed), 0); assert_eq!(value.load(Ordering::Relaxed), 0); for i in 0..100 { let d1 = Dropable::new(i, &key); let d2 = Dropable::new(i + 100, &value); hm.insert(d1, d2); } assert_eq!(key.load(Ordering::Relaxed), 100); assert_eq!(value.load(Ordering::Relaxed), 100); hm }; // By the way, ensure that cloning doesn't screw up the dropping. drop(hm.clone()); assert_eq!(key.load(Ordering::Relaxed), 100); assert_eq!(value.load(Ordering::Relaxed), 100); // Ensure that dropping the drain iterator does not leak anything. drop(hm.clone().par_drain()); { assert_eq!(key.load(Ordering::Relaxed), 100); assert_eq!(value.load(Ordering::Relaxed), 100); // retain only half let _v: Vec<_> = hm.drain().filter(|(key, _)| key.k < 50).collect(); assert!(hm.is_empty()); assert_eq!(key.load(Ordering::Relaxed), 50); assert_eq!(value.load(Ordering::Relaxed), 50); }; assert_eq!(key.load(Ordering::Relaxed), 0); assert_eq!(value.load(Ordering::Relaxed), 0); } #[test] fn test_empty_iter() { let mut m: HashMap = HashMap::new(); assert_eq!(m.par_drain().count(), 0); assert_eq!(m.par_keys().count(), 0); assert_eq!(m.par_values().count(), 0); assert_eq!(m.par_values_mut().count(), 0); assert_eq!(m.par_iter().count(), 0); assert_eq!(m.par_iter_mut().count(), 0); assert_eq!(m.len(), 0); assert!(m.is_empty()); assert_eq!(m.into_par_iter().count(), 0); } #[test] fn test_iterate() { let mut m = HashMap::with_capacity(4); for i in 0..32 { assert!(m.insert(i, i * 2).is_none()); } assert_eq!(m.len(), 32); let observed = AtomicUsize::new(0); m.par_iter().for_each(|(k, v)| { assert_eq!(*v, *k * 2); observed.fetch_or(1 << *k, Ordering::Relaxed); }); assert_eq!(observed.into_inner(), 0xFFFF_FFFF); } #[test] fn test_keys() { let vec = vec![(1, 'a'), (2, 'b'), (3, 'c')]; let map: HashMap<_, _> = vec.into_par_iter().collect(); let keys: Vec<_> = map.par_keys().cloned().collect(); assert_eq!(keys.len(), 3); assert!(keys.contains(&1)); assert!(keys.contains(&2)); assert!(keys.contains(&3)); } #[test] fn test_values() { let vec = vec![(1, 'a'), (2, 'b'), (3, 'c')]; let map: HashMap<_, _> = vec.into_par_iter().collect(); let values: Vec<_> = map.par_values().cloned().collect(); assert_eq!(values.len(), 3); assert!(values.contains(&'a')); assert!(values.contains(&'b')); assert!(values.contains(&'c')); } #[test] fn test_values_mut() { let vec = vec![(1, 1), (2, 2), (3, 3)]; let mut map: HashMap<_, _> = vec.into_par_iter().collect(); map.par_values_mut().for_each(|value| *value *= 2); let values: Vec<_> = map.par_values().cloned().collect(); assert_eq!(values.len(), 3); assert!(values.contains(&2)); assert!(values.contains(&4)); assert!(values.contains(&6)); } #[test] fn test_eq() { let mut m1 = HashMap::new(); m1.insert(1, 2); m1.insert(2, 3); m1.insert(3, 4); let mut m2 = HashMap::new(); m2.insert(1, 2); m2.insert(2, 3); assert!(!m1.par_eq(&m2)); m2.insert(3, 4); assert!(m1.par_eq(&m2)); } #[test] fn test_from_iter() { let xs = [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; let map: HashMap<_, _> = xs.par_iter().cloned().collect(); for &(k, v) in &xs { assert_eq!(map.get(&k), Some(&v)); } } #[test] fn test_extend_ref() { let mut a = HashMap::new(); a.insert(1, "one"); let mut b = HashMap::new(); b.insert(2, "two"); b.insert(3, "three"); a.par_extend(&b); assert_eq!(a.len(), 3); assert_eq!(a[&1], "one"); assert_eq!(a[&2], "two"); assert_eq!(a[&3], "three"); } } hashbrown-0.14.5/src/external_trait_impls/rayon/mod.rs000064400000000000000000000001371046102023000212040ustar 00000000000000mod helpers; pub(crate) mod map; pub(crate) mod raw; pub(crate) mod set; pub(crate) mod table; hashbrown-0.14.5/src/external_trait_impls/rayon/raw.rs000064400000000000000000000151211046102023000212150ustar 00000000000000use crate::raw::Bucket; use crate::raw::{Allocator, Global, RawIter, RawIterRange, RawTable}; use crate::scopeguard::guard; use core::marker::PhantomData; use core::mem; use core::ptr::NonNull; use rayon::iter::{ plumbing::{self, Folder, UnindexedConsumer, UnindexedProducer}, ParallelIterator, }; /// Parallel iterator which returns a raw pointer to every full bucket in the table. pub struct RawParIter { iter: RawIterRange, } impl RawParIter { #[cfg_attr(feature = "inline-more", inline)] pub(super) unsafe fn iter(&self) -> RawIterRange { self.iter.clone() } } impl Clone for RawParIter { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Self { iter: self.iter.clone(), } } } impl From> for RawParIter { fn from(it: RawIter) -> Self { RawParIter { iter: it.iter } } } impl ParallelIterator for RawParIter { type Item = Bucket; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { let producer = ParIterProducer { iter: self.iter }; plumbing::bridge_unindexed(producer, consumer) } } /// Producer which returns a `Bucket` for every element. struct ParIterProducer { iter: RawIterRange, } impl UnindexedProducer for ParIterProducer { type Item = Bucket; #[cfg_attr(feature = "inline-more", inline)] fn split(self) -> (Self, Option) { let (left, right) = self.iter.split(); let left = ParIterProducer { iter: left }; let right = right.map(|right| ParIterProducer { iter: right }); (left, right) } #[cfg_attr(feature = "inline-more", inline)] fn fold_with(self, folder: F) -> F where F: Folder, { folder.consume_iter(self.iter) } } /// Parallel iterator which consumes a table and returns elements. pub struct RawIntoParIter { table: RawTable, } impl RawIntoParIter { #[cfg_attr(feature = "inline-more", inline)] pub(super) unsafe fn par_iter(&self) -> RawParIter { self.table.par_iter() } } impl ParallelIterator for RawIntoParIter { type Item = T; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { let iter = unsafe { self.table.iter().iter }; let _guard = guard(self.table.into_allocation(), |alloc| { if let Some((ptr, layout, ref alloc)) = *alloc { unsafe { alloc.deallocate(ptr, layout); } } }); let producer = ParDrainProducer { iter }; plumbing::bridge_unindexed(producer, consumer) } } /// Parallel iterator which consumes elements without freeing the table storage. pub struct RawParDrain<'a, T, A: Allocator = Global> { // We don't use a &'a mut RawTable because we want RawParDrain to be // covariant over T. table: NonNull>, marker: PhantomData<&'a RawTable>, } unsafe impl Send for RawParDrain<'_, T, A> {} impl RawParDrain<'_, T, A> { #[cfg_attr(feature = "inline-more", inline)] pub(super) unsafe fn par_iter(&self) -> RawParIter { self.table.as_ref().par_iter() } } impl ParallelIterator for RawParDrain<'_, T, A> { type Item = T; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { let _guard = guard(self.table, |table| unsafe { table.as_mut().clear_no_drop(); }); let iter = unsafe { self.table.as_ref().iter().iter }; mem::forget(self); let producer = ParDrainProducer { iter }; plumbing::bridge_unindexed(producer, consumer) } } impl Drop for RawParDrain<'_, T, A> { fn drop(&mut self) { // If drive_unindexed is not called then simply clear the table. unsafe { self.table.as_mut().clear(); } } } /// Producer which will consume all elements in the range, even if it is dropped /// halfway through. struct ParDrainProducer { iter: RawIterRange, } impl UnindexedProducer for ParDrainProducer { type Item = T; #[cfg_attr(feature = "inline-more", inline)] fn split(self) -> (Self, Option) { let (left, right) = self.iter.clone().split(); mem::forget(self); let left = ParDrainProducer { iter: left }; let right = right.map(|right| ParDrainProducer { iter: right }); (left, right) } #[cfg_attr(feature = "inline-more", inline)] fn fold_with(mut self, mut folder: F) -> F where F: Folder, { // Make sure to modify the iterator in-place so that any remaining // elements are processed in our Drop impl. for item in &mut self.iter { folder = folder.consume(unsafe { item.read() }); if folder.full() { return folder; } } // If we processed all elements then we don't need to run the drop. mem::forget(self); folder } } impl Drop for ParDrainProducer { #[cfg_attr(feature = "inline-more", inline)] fn drop(&mut self) { // Drop all remaining elements if mem::needs_drop::() { for item in &mut self.iter { unsafe { item.drop(); } } } } } impl RawTable { /// Returns a parallel iterator over the elements in a `RawTable`. #[cfg_attr(feature = "inline-more", inline)] pub unsafe fn par_iter(&self) -> RawParIter { RawParIter { iter: self.iter().iter, } } /// Returns a parallel iterator over the elements in a `RawTable`. #[cfg_attr(feature = "inline-more", inline)] pub fn into_par_iter(self) -> RawIntoParIter { RawIntoParIter { table: self } } /// Returns a parallel iterator which consumes all elements of a `RawTable` /// without freeing its memory allocation. #[cfg_attr(feature = "inline-more", inline)] pub fn par_drain(&mut self) -> RawParDrain<'_, T, A> { RawParDrain { table: NonNull::from(self), marker: PhantomData, } } } hashbrown-0.14.5/src/external_trait_impls/rayon/set.rs000064400000000000000000000444011046102023000212220ustar 00000000000000//! Rayon extensions for `HashSet`. use super::map; use crate::hash_set::HashSet; use crate::raw::{Allocator, Global}; use core::hash::{BuildHasher, Hash}; use rayon::iter::plumbing::UnindexedConsumer; use rayon::iter::{FromParallelIterator, IntoParallelIterator, ParallelExtend, ParallelIterator}; /// Parallel iterator over elements of a consumed set. /// /// This iterator is created by the [`into_par_iter`] method on [`HashSet`] /// (provided by the [`IntoParallelIterator`] trait). /// See its documentation for more. /// /// [`into_par_iter`]: /hashbrown/struct.HashSet.html#method.into_par_iter /// [`HashSet`]: /hashbrown/struct.HashSet.html /// [`IntoParallelIterator`]: https://docs.rs/rayon/1.0/rayon/iter/trait.IntoParallelIterator.html pub struct IntoParIter { inner: map::IntoParIter, } impl ParallelIterator for IntoParIter { type Item = T; fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner.map(|(k, _)| k).drive_unindexed(consumer) } } /// Parallel draining iterator over entries of a set. /// /// This iterator is created by the [`par_drain`] method on [`HashSet`]. /// See its documentation for more. /// /// [`par_drain`]: /hashbrown/struct.HashSet.html#method.par_drain /// [`HashSet`]: /hashbrown/struct.HashSet.html pub struct ParDrain<'a, T, A: Allocator = Global> { inner: map::ParDrain<'a, T, (), A>, } impl ParallelIterator for ParDrain<'_, T, A> { type Item = T; fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner.map(|(k, _)| k).drive_unindexed(consumer) } } /// Parallel iterator over shared references to elements in a set. /// /// This iterator is created by the [`par_iter`] method on [`HashSet`] /// (provided by the [`IntoParallelRefIterator`] trait). /// See its documentation for more. /// /// [`par_iter`]: /hashbrown/struct.HashSet.html#method.par_iter /// [`HashSet`]: /hashbrown/struct.HashSet.html /// [`IntoParallelRefIterator`]: https://docs.rs/rayon/1.0/rayon/iter/trait.IntoParallelRefIterator.html pub struct ParIter<'a, T> { inner: map::ParKeys<'a, T, ()>, } impl<'a, T: Sync> ParallelIterator for ParIter<'a, T> { type Item = &'a T; fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner.drive_unindexed(consumer) } } /// Parallel iterator over shared references to elements in the difference of /// sets. /// /// This iterator is created by the [`par_difference`] method on [`HashSet`]. /// See its documentation for more. /// /// [`par_difference`]: /hashbrown/struct.HashSet.html#method.par_difference /// [`HashSet`]: /hashbrown/struct.HashSet.html pub struct ParDifference<'a, T, S, A: Allocator = Global> { a: &'a HashSet, b: &'a HashSet, } impl<'a, T, S, A> ParallelIterator for ParDifference<'a, T, S, A> where T: Eq + Hash + Sync, S: BuildHasher + Sync, A: Allocator + Sync, { type Item = &'a T; fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.a .into_par_iter() .filter(|&x| !self.b.contains(x)) .drive_unindexed(consumer) } } /// Parallel iterator over shared references to elements in the symmetric /// difference of sets. /// /// This iterator is created by the [`par_symmetric_difference`] method on /// [`HashSet`]. /// See its documentation for more. /// /// [`par_symmetric_difference`]: /hashbrown/struct.HashSet.html#method.par_symmetric_difference /// [`HashSet`]: /hashbrown/struct.HashSet.html pub struct ParSymmetricDifference<'a, T, S, A: Allocator = Global> { a: &'a HashSet, b: &'a HashSet, } impl<'a, T, S, A> ParallelIterator for ParSymmetricDifference<'a, T, S, A> where T: Eq + Hash + Sync, S: BuildHasher + Sync, A: Allocator + Sync, { type Item = &'a T; fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.a .par_difference(self.b) .chain(self.b.par_difference(self.a)) .drive_unindexed(consumer) } } /// Parallel iterator over shared references to elements in the intersection of /// sets. /// /// This iterator is created by the [`par_intersection`] method on [`HashSet`]. /// See its documentation for more. /// /// [`par_intersection`]: /hashbrown/struct.HashSet.html#method.par_intersection /// [`HashSet`]: /hashbrown/struct.HashSet.html pub struct ParIntersection<'a, T, S, A: Allocator = Global> { a: &'a HashSet, b: &'a HashSet, } impl<'a, T, S, A> ParallelIterator for ParIntersection<'a, T, S, A> where T: Eq + Hash + Sync, S: BuildHasher + Sync, A: Allocator + Sync, { type Item = &'a T; fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.a .into_par_iter() .filter(|&x| self.b.contains(x)) .drive_unindexed(consumer) } } /// Parallel iterator over shared references to elements in the union of sets. /// /// This iterator is created by the [`par_union`] method on [`HashSet`]. /// See its documentation for more. /// /// [`par_union`]: /hashbrown/struct.HashSet.html#method.par_union /// [`HashSet`]: /hashbrown/struct.HashSet.html pub struct ParUnion<'a, T, S, A: Allocator = Global> { a: &'a HashSet, b: &'a HashSet, } impl<'a, T, S, A> ParallelIterator for ParUnion<'a, T, S, A> where T: Eq + Hash + Sync, S: BuildHasher + Sync, A: Allocator + Sync, { type Item = &'a T; fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { // We'll iterate one set in full, and only the remaining difference from the other. // Use the smaller set for the difference in order to reduce hash lookups. let (smaller, larger) = if self.a.len() <= self.b.len() { (self.a, self.b) } else { (self.b, self.a) }; larger .into_par_iter() .chain(smaller.par_difference(larger)) .drive_unindexed(consumer) } } impl HashSet where T: Eq + Hash + Sync, S: BuildHasher + Sync, A: Allocator + Sync, { /// Visits (potentially in parallel) the values representing the union, /// i.e. all the values in `self` or `other`, without duplicates. #[cfg_attr(feature = "inline-more", inline)] pub fn par_union<'a>(&'a self, other: &'a Self) -> ParUnion<'a, T, S, A> { ParUnion { a: self, b: other } } /// Visits (potentially in parallel) the values representing the difference, /// i.e. the values that are in `self` but not in `other`. #[cfg_attr(feature = "inline-more", inline)] pub fn par_difference<'a>(&'a self, other: &'a Self) -> ParDifference<'a, T, S, A> { ParDifference { a: self, b: other } } /// Visits (potentially in parallel) the values representing the symmetric /// difference, i.e. the values that are in `self` or in `other` but not in both. #[cfg_attr(feature = "inline-more", inline)] pub fn par_symmetric_difference<'a>( &'a self, other: &'a Self, ) -> ParSymmetricDifference<'a, T, S, A> { ParSymmetricDifference { a: self, b: other } } /// Visits (potentially in parallel) the values representing the /// intersection, i.e. the values that are both in `self` and `other`. #[cfg_attr(feature = "inline-more", inline)] pub fn par_intersection<'a>(&'a self, other: &'a Self) -> ParIntersection<'a, T, S, A> { ParIntersection { a: self, b: other } } /// Returns `true` if `self` has no elements in common with `other`. /// This is equivalent to checking for an empty intersection. /// /// This method runs in a potentially parallel fashion. pub fn par_is_disjoint(&self, other: &Self) -> bool { self.into_par_iter().all(|x| !other.contains(x)) } /// Returns `true` if the set is a subset of another, /// i.e. `other` contains at least all the values in `self`. /// /// This method runs in a potentially parallel fashion. pub fn par_is_subset(&self, other: &Self) -> bool { if self.len() <= other.len() { self.into_par_iter().all(|x| other.contains(x)) } else { false } } /// Returns `true` if the set is a superset of another, /// i.e. `self` contains at least all the values in `other`. /// /// This method runs in a potentially parallel fashion. pub fn par_is_superset(&self, other: &Self) -> bool { other.par_is_subset(self) } /// Returns `true` if the set is equal to another, /// i.e. both sets contain the same values. /// /// This method runs in a potentially parallel fashion. pub fn par_eq(&self, other: &Self) -> bool { self.len() == other.len() && self.par_is_subset(other) } } impl HashSet where T: Eq + Hash + Send, A: Allocator + Send, { /// Consumes (potentially in parallel) all values in an arbitrary order, /// while preserving the set's allocated memory for reuse. #[cfg_attr(feature = "inline-more", inline)] pub fn par_drain(&mut self) -> ParDrain<'_, T, A> { ParDrain { inner: self.map.par_drain(), } } } impl IntoParallelIterator for HashSet { type Item = T; type Iter = IntoParIter; #[cfg_attr(feature = "inline-more", inline)] fn into_par_iter(self) -> Self::Iter { IntoParIter { inner: self.map.into_par_iter(), } } } impl<'a, T: Sync, S, A: Allocator> IntoParallelIterator for &'a HashSet { type Item = &'a T; type Iter = ParIter<'a, T>; #[cfg_attr(feature = "inline-more", inline)] fn into_par_iter(self) -> Self::Iter { ParIter { inner: self.map.par_keys(), } } } /// Collect values from a parallel iterator into a hashset. impl FromParallelIterator for HashSet where T: Eq + Hash + Send, S: BuildHasher + Default, { fn from_par_iter

(par_iter: P) -> Self where P: IntoParallelIterator, { let mut set = HashSet::default(); set.par_extend(par_iter); set } } /// Extend a hash set with items from a parallel iterator. impl ParallelExtend for HashSet where T: Eq + Hash + Send, S: BuildHasher, { fn par_extend(&mut self, par_iter: I) where I: IntoParallelIterator, { extend(self, par_iter); } } /// Extend a hash set with copied items from a parallel iterator. impl<'a, T, S> ParallelExtend<&'a T> for HashSet where T: 'a + Copy + Eq + Hash + Sync, S: BuildHasher, { fn par_extend(&mut self, par_iter: I) where I: IntoParallelIterator, { extend(self, par_iter); } } // This is equal to the normal `HashSet` -- no custom advantage. fn extend(set: &mut HashSet, par_iter: I) where T: Eq + Hash, S: BuildHasher, A: Allocator, I: IntoParallelIterator, HashSet: Extend, { let (list, len) = super::helpers::collect(par_iter); // Values may be already present or show multiple times in the iterator. // Reserve the entire length if the set is empty. // Otherwise reserve half the length (rounded up), so the set // will only resize twice in the worst case. let reserve = if set.is_empty() { len } else { (len + 1) / 2 }; set.reserve(reserve); for vec in list { set.extend(vec); } } #[cfg(test)] mod test_par_set { use alloc::vec::Vec; use core::sync::atomic::{AtomicUsize, Ordering}; use rayon::prelude::*; use crate::hash_set::HashSet; #[test] fn test_disjoint() { let mut xs = HashSet::new(); let mut ys = HashSet::new(); assert!(xs.par_is_disjoint(&ys)); assert!(ys.par_is_disjoint(&xs)); assert!(xs.insert(5)); assert!(ys.insert(11)); assert!(xs.par_is_disjoint(&ys)); assert!(ys.par_is_disjoint(&xs)); assert!(xs.insert(7)); assert!(xs.insert(19)); assert!(xs.insert(4)); assert!(ys.insert(2)); assert!(ys.insert(-11)); assert!(xs.par_is_disjoint(&ys)); assert!(ys.par_is_disjoint(&xs)); assert!(ys.insert(7)); assert!(!xs.par_is_disjoint(&ys)); assert!(!ys.par_is_disjoint(&xs)); } #[test] fn test_subset_and_superset() { let mut a = HashSet::new(); assert!(a.insert(0)); assert!(a.insert(5)); assert!(a.insert(11)); assert!(a.insert(7)); let mut b = HashSet::new(); assert!(b.insert(0)); assert!(b.insert(7)); assert!(b.insert(19)); assert!(b.insert(250)); assert!(b.insert(11)); assert!(b.insert(200)); assert!(!a.par_is_subset(&b)); assert!(!a.par_is_superset(&b)); assert!(!b.par_is_subset(&a)); assert!(!b.par_is_superset(&a)); assert!(b.insert(5)); assert!(a.par_is_subset(&b)); assert!(!a.par_is_superset(&b)); assert!(!b.par_is_subset(&a)); assert!(b.par_is_superset(&a)); } #[test] fn test_iterate() { let mut a = HashSet::new(); for i in 0..32 { assert!(a.insert(i)); } let observed = AtomicUsize::new(0); a.par_iter().for_each(|k| { observed.fetch_or(1 << *k, Ordering::Relaxed); }); assert_eq!(observed.into_inner(), 0xFFFF_FFFF); } #[test] fn test_intersection() { let mut a = HashSet::new(); let mut b = HashSet::new(); assert!(a.insert(11)); assert!(a.insert(1)); assert!(a.insert(3)); assert!(a.insert(77)); assert!(a.insert(103)); assert!(a.insert(5)); assert!(a.insert(-5)); assert!(b.insert(2)); assert!(b.insert(11)); assert!(b.insert(77)); assert!(b.insert(-9)); assert!(b.insert(-42)); assert!(b.insert(5)); assert!(b.insert(3)); let expected = [3, 5, 11, 77]; let i = a .par_intersection(&b) .map(|x| { assert!(expected.contains(x)); 1 }) .sum::(); assert_eq!(i, expected.len()); } #[test] fn test_difference() { let mut a = HashSet::new(); let mut b = HashSet::new(); assert!(a.insert(1)); assert!(a.insert(3)); assert!(a.insert(5)); assert!(a.insert(9)); assert!(a.insert(11)); assert!(b.insert(3)); assert!(b.insert(9)); let expected = [1, 5, 11]; let i = a .par_difference(&b) .map(|x| { assert!(expected.contains(x)); 1 }) .sum::(); assert_eq!(i, expected.len()); } #[test] fn test_symmetric_difference() { let mut a = HashSet::new(); let mut b = HashSet::new(); assert!(a.insert(1)); assert!(a.insert(3)); assert!(a.insert(5)); assert!(a.insert(9)); assert!(a.insert(11)); assert!(b.insert(-2)); assert!(b.insert(3)); assert!(b.insert(9)); assert!(b.insert(14)); assert!(b.insert(22)); let expected = [-2, 1, 5, 11, 14, 22]; let i = a .par_symmetric_difference(&b) .map(|x| { assert!(expected.contains(x)); 1 }) .sum::(); assert_eq!(i, expected.len()); } #[test] fn test_union() { let mut a = HashSet::new(); let mut b = HashSet::new(); assert!(a.insert(1)); assert!(a.insert(3)); assert!(a.insert(5)); assert!(a.insert(9)); assert!(a.insert(11)); assert!(a.insert(16)); assert!(a.insert(19)); assert!(a.insert(24)); assert!(b.insert(-2)); assert!(b.insert(1)); assert!(b.insert(5)); assert!(b.insert(9)); assert!(b.insert(13)); assert!(b.insert(19)); let expected = [-2, 1, 3, 5, 9, 11, 13, 16, 19, 24]; let i = a .par_union(&b) .map(|x| { assert!(expected.contains(x)); 1 }) .sum::(); assert_eq!(i, expected.len()); } #[test] fn test_from_iter() { let xs = [1, 2, 3, 4, 5, 6, 7, 8, 9]; let set: HashSet<_> = xs.par_iter().cloned().collect(); for x in &xs { assert!(set.contains(x)); } } #[test] fn test_move_iter() { let hs = { let mut hs = HashSet::new(); hs.insert('a'); hs.insert('b'); hs }; let v = hs.into_par_iter().collect::>(); assert!(v == ['a', 'b'] || v == ['b', 'a']); } #[test] fn test_eq() { // These constants once happened to expose a bug in insert(). // I'm keeping them around to prevent a regression. let mut s1 = HashSet::new(); s1.insert(1); s1.insert(2); s1.insert(3); let mut s2 = HashSet::new(); s2.insert(1); s2.insert(2); assert!(!s1.par_eq(&s2)); s2.insert(3); assert!(s1.par_eq(&s2)); } #[test] fn test_extend_ref() { let mut a = HashSet::new(); a.insert(1); a.par_extend(&[2, 3, 4][..]); assert_eq!(a.len(), 4); assert!(a.contains(&1)); assert!(a.contains(&2)); assert!(a.contains(&3)); assert!(a.contains(&4)); let mut b = HashSet::new(); b.insert(5); b.insert(6); a.par_extend(&b); assert_eq!(a.len(), 6); assert!(a.contains(&1)); assert!(a.contains(&2)); assert!(a.contains(&3)); assert!(a.contains(&4)); assert!(a.contains(&5)); assert!(a.contains(&6)); } } hashbrown-0.14.5/src/external_trait_impls/rayon/table.rs000064400000000000000000000166141046102023000215230ustar 00000000000000//! Rayon extensions for `HashTable`. use super::raw::{RawIntoParIter, RawParDrain, RawParIter}; use crate::hash_table::HashTable; use crate::raw::{Allocator, Global}; use core::fmt; use core::marker::PhantomData; use rayon::iter::plumbing::UnindexedConsumer; use rayon::iter::{IntoParallelIterator, ParallelIterator}; /// Parallel iterator over shared references to entries in a map. /// /// This iterator is created by the [`par_iter`] method on [`HashTable`] /// (provided by the [`IntoParallelRefIterator`] trait). /// See its documentation for more. /// /// [`par_iter`]: /hashbrown/struct.HashTable.html#method.par_iter /// [`HashTable`]: /hashbrown/struct.HashTable.html /// [`IntoParallelRefIterator`]: https://docs.rs/rayon/1.0/rayon/iter/trait.IntoParallelRefIterator.html pub struct ParIter<'a, T> { inner: RawParIter, marker: PhantomData<&'a T>, } impl<'a, T: Sync> ParallelIterator for ParIter<'a, T> { type Item = &'a T; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner .map(|x| unsafe { x.as_ref() }) .drive_unindexed(consumer) } } impl Clone for ParIter<'_, T> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Self { inner: self.inner.clone(), marker: PhantomData, } } } impl fmt::Debug for ParIter<'_, T> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let iter = unsafe { self.inner.iter() }.map(|x| unsafe { x.as_ref() }); f.debug_list().entries(iter).finish() } } /// Parallel iterator over mutable references to entries in a map. /// /// This iterator is created by the [`par_iter_mut`] method on [`HashTable`] /// (provided by the [`IntoParallelRefMutIterator`] trait). /// See its documentation for more. /// /// [`par_iter_mut`]: /hashbrown/struct.HashTable.html#method.par_iter_mut /// [`HashTable`]: /hashbrown/struct.HashTable.html /// [`IntoParallelRefMutIterator`]: https://docs.rs/rayon/1.0/rayon/iter/trait.IntoParallelRefMutIterator.html pub struct ParIterMut<'a, T> { inner: RawParIter, marker: PhantomData<&'a mut T>, } impl<'a, T: Send> ParallelIterator for ParIterMut<'a, T> { type Item = &'a mut T; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner .map(|x| unsafe { x.as_mut() }) .drive_unindexed(consumer) } } impl fmt::Debug for ParIterMut<'_, T> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { ParIter { inner: self.inner.clone(), marker: PhantomData, } .fmt(f) } } /// Parallel iterator over entries of a consumed map. /// /// This iterator is created by the [`into_par_iter`] method on [`HashTable`] /// (provided by the [`IntoParallelIterator`] trait). /// See its documentation for more. /// /// [`into_par_iter`]: /hashbrown/struct.HashTable.html#method.into_par_iter /// [`HashTable`]: /hashbrown/struct.HashTable.html /// [`IntoParallelIterator`]: https://docs.rs/rayon/1.0/rayon/iter/trait.IntoParallelIterator.html pub struct IntoParIter { inner: RawIntoParIter, } impl ParallelIterator for IntoParIter { type Item = T; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner.drive_unindexed(consumer) } } impl fmt::Debug for IntoParIter { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { ParIter { inner: unsafe { self.inner.par_iter() }, marker: PhantomData, } .fmt(f) } } /// Parallel draining iterator over entries of a map. /// /// This iterator is created by the [`par_drain`] method on [`HashTable`]. /// See its documentation for more. /// /// [`par_drain`]: /hashbrown/struct.HashTable.html#method.par_drain /// [`HashTable`]: /hashbrown/struct.HashTable.html pub struct ParDrain<'a, T, A: Allocator = Global> { inner: RawParDrain<'a, T, A>, } impl ParallelIterator for ParDrain<'_, T, A> { type Item = T; #[cfg_attr(feature = "inline-more", inline)] fn drive_unindexed(self, consumer: C) -> C::Result where C: UnindexedConsumer, { self.inner.drive_unindexed(consumer) } } impl fmt::Debug for ParDrain<'_, T, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { ParIter { inner: unsafe { self.inner.par_iter() }, marker: PhantomData, } .fmt(f) } } impl HashTable { /// Consumes (potentially in parallel) all values in an arbitrary order, /// while preserving the map's allocated memory for reuse. #[cfg_attr(feature = "inline-more", inline)] pub fn par_drain(&mut self) -> ParDrain<'_, T, A> { ParDrain { inner: self.raw.par_drain(), } } } impl IntoParallelIterator for HashTable { type Item = T; type Iter = IntoParIter; #[cfg_attr(feature = "inline-more", inline)] fn into_par_iter(self) -> Self::Iter { IntoParIter { inner: self.raw.into_par_iter(), } } } impl<'a, T: Sync, A: Allocator> IntoParallelIterator for &'a HashTable { type Item = &'a T; type Iter = ParIter<'a, T>; #[cfg_attr(feature = "inline-more", inline)] fn into_par_iter(self) -> Self::Iter { ParIter { inner: unsafe { self.raw.par_iter() }, marker: PhantomData, } } } impl<'a, T: Send, A: Allocator> IntoParallelIterator for &'a mut HashTable { type Item = &'a mut T; type Iter = ParIterMut<'a, T>; #[cfg_attr(feature = "inline-more", inline)] fn into_par_iter(self) -> Self::Iter { ParIterMut { inner: unsafe { self.raw.par_iter() }, marker: PhantomData, } } } #[cfg(test)] mod test_par_table { use alloc::vec::Vec; use core::sync::atomic::{AtomicUsize, Ordering}; use rayon::prelude::*; use crate::{ hash_map::{make_hash, DefaultHashBuilder}, hash_table::HashTable, }; #[test] fn test_iterate() { let hasher = DefaultHashBuilder::default(); let mut a = HashTable::new(); for i in 0..32 { a.insert_unique(make_hash(&hasher, &i), i, |x| make_hash(&hasher, x)); } let observed = AtomicUsize::new(0); a.par_iter().for_each(|k| { observed.fetch_or(1 << *k, Ordering::Relaxed); }); assert_eq!(observed.into_inner(), 0xFFFF_FFFF); } #[test] fn test_move_iter() { let hasher = DefaultHashBuilder::default(); let hs = { let mut hs = HashTable::new(); hs.insert_unique(make_hash(&hasher, &'a'), 'a', |x| make_hash(&hasher, x)); hs.insert_unique(make_hash(&hasher, &'b'), 'b', |x| make_hash(&hasher, x)); hs }; let v = hs.into_par_iter().collect::>(); assert!(v == ['a', 'b'] || v == ['b', 'a']); } } hashbrown-0.14.5/src/external_trait_impls/rkyv/hash_map.rs000064400000000000000000000077121046102023000220560ustar 00000000000000use crate::HashMap; use core::{ borrow::Borrow, hash::{BuildHasher, Hash}, }; use rkyv::{ collections::hash_map::{ArchivedHashMap, HashMapResolver}, ser::{ScratchSpace, Serializer}, Archive, Deserialize, Fallible, Serialize, }; impl Archive for HashMap where K::Archived: Hash + Eq, { type Archived = ArchivedHashMap; type Resolver = HashMapResolver; #[inline] unsafe fn resolve(&self, pos: usize, resolver: Self::Resolver, out: *mut Self::Archived) { ArchivedHashMap::resolve_from_len(self.len(), pos, resolver, out); } } impl Serialize for HashMap where K: Serialize + Hash + Eq, K::Archived: Hash + Eq, V: Serialize, S: Serializer + ScratchSpace + ?Sized, { #[inline] fn serialize(&self, serializer: &mut S) -> Result { unsafe { ArchivedHashMap::serialize_from_iter(self.iter(), serializer) } } } impl Deserialize, D> for ArchivedHashMap where K::Archived: Deserialize + Hash + Eq, V::Archived: Deserialize, { #[inline] fn deserialize(&self, deserializer: &mut D) -> Result, D::Error> { let mut result = HashMap::with_capacity_and_hasher(self.len(), S::default()); for (k, v) in self.iter() { result.insert(k.deserialize(deserializer)?, v.deserialize(deserializer)?); } Ok(result) } } impl, V, AK: Hash + Eq, AV: PartialEq, S: BuildHasher> PartialEq> for ArchivedHashMap { #[inline] fn eq(&self, other: &HashMap) -> bool { if self.len() != other.len() { false } else { self.iter() .all(|(key, value)| other.get(key).map_or(false, |v| value.eq(v))) } } } impl, V, AK: Hash + Eq, AV: PartialEq> PartialEq> for HashMap { #[inline] fn eq(&self, other: &ArchivedHashMap) -> bool { other.eq(self) } } #[cfg(test)] mod tests { use crate::HashMap; use alloc::string::String; use rkyv::{ archived_root, check_archived_root, ser::{serializers::AllocSerializer, Serializer}, Deserialize, Infallible, }; #[test] fn index_map() { let mut value = HashMap::new(); value.insert(String::from("foo"), 10); value.insert(String::from("bar"), 20); value.insert(String::from("baz"), 40); value.insert(String::from("bat"), 80); let mut serializer = AllocSerializer::<4096>::default(); serializer.serialize_value(&value).unwrap(); let result = serializer.into_serializer().into_inner(); let archived = unsafe { archived_root::>(result.as_ref()) }; assert_eq!(value.len(), archived.len()); for (k, v) in value.iter() { let (ak, av) = archived.get_key_value(k.as_str()).unwrap(); assert_eq!(k, ak); assert_eq!(v, av); } let deserialized: HashMap = archived.deserialize(&mut Infallible).unwrap(); assert_eq!(value, deserialized); } #[test] fn validate_index_map() { let mut value = HashMap::new(); value.insert(String::from("foo"), 10); value.insert(String::from("bar"), 20); value.insert(String::from("baz"), 40); value.insert(String::from("bat"), 80); let mut serializer = AllocSerializer::<4096>::default(); serializer.serialize_value(&value).unwrap(); let result = serializer.into_serializer().into_inner(); check_archived_root::>(result.as_ref()) .expect("failed to validate archived index map"); } } hashbrown-0.14.5/src/external_trait_impls/rkyv/hash_set.rs000064400000000000000000000071441046102023000220730ustar 00000000000000use crate::HashSet; use core::{ borrow::Borrow, hash::{BuildHasher, Hash}, }; use rkyv::{ collections::hash_set::{ArchivedHashSet, HashSetResolver}, ser::{ScratchSpace, Serializer}, Archive, Deserialize, Fallible, Serialize, }; impl Archive for HashSet where K::Archived: Hash + Eq, { type Archived = ArchivedHashSet; type Resolver = HashSetResolver; #[inline] unsafe fn resolve(&self, pos: usize, resolver: Self::Resolver, out: *mut Self::Archived) { ArchivedHashSet::::resolve_from_len(self.len(), pos, resolver, out); } } impl Serialize for HashSet where K::Archived: Hash + Eq, K: Serialize + Hash + Eq, S: ScratchSpace + Serializer + ?Sized, { #[inline] fn serialize(&self, serializer: &mut S) -> Result { unsafe { ArchivedHashSet::serialize_from_iter(self.iter(), serializer) } } } impl Deserialize, D> for ArchivedHashSet where K: Archive + Hash + Eq, K::Archived: Deserialize + Hash + Eq, D: Fallible + ?Sized, S: Default + BuildHasher, { #[inline] fn deserialize(&self, deserializer: &mut D) -> Result, D::Error> { let mut result = HashSet::with_hasher(S::default()); for k in self.iter() { result.insert(k.deserialize(deserializer)?); } Ok(result) } } impl, AK: Hash + Eq, S: BuildHasher> PartialEq> for ArchivedHashSet { #[inline] fn eq(&self, other: &HashSet) -> bool { if self.len() != other.len() { false } else { self.iter().all(|key| other.get(key).is_some()) } } } impl, AK: Hash + Eq, S: BuildHasher> PartialEq> for HashSet { #[inline] fn eq(&self, other: &ArchivedHashSet) -> bool { other.eq(self) } } #[cfg(test)] mod tests { use crate::HashSet; use alloc::string::String; use rkyv::{ archived_root, check_archived_root, ser::{serializers::AllocSerializer, Serializer}, Deserialize, Infallible, }; #[test] fn index_set() { let mut value = HashSet::new(); value.insert(String::from("foo")); value.insert(String::from("bar")); value.insert(String::from("baz")); value.insert(String::from("bat")); let mut serializer = AllocSerializer::<4096>::default(); serializer.serialize_value(&value).unwrap(); let result = serializer.into_serializer().into_inner(); let archived = unsafe { archived_root::>(result.as_ref()) }; assert_eq!(value.len(), archived.len()); for k in value.iter() { let ak = archived.get(k.as_str()).unwrap(); assert_eq!(k, ak); } let deserialized: HashSet = archived.deserialize(&mut Infallible).unwrap(); assert_eq!(value, deserialized); } #[test] fn validate_index_set() { let mut value = HashSet::new(); value.insert(String::from("foo")); value.insert(String::from("bar")); value.insert(String::from("baz")); value.insert(String::from("bat")); let mut serializer = AllocSerializer::<4096>::default(); serializer.serialize_value(&value).unwrap(); let result = serializer.into_serializer().into_inner(); check_archived_root::>(result.as_ref()) .expect("failed to validate archived index set"); } } hashbrown-0.14.5/src/external_trait_impls/rkyv/mod.rs000064400000000000000000000000341046102023000210430ustar 00000000000000mod hash_map; mod hash_set; hashbrown-0.14.5/src/external_trait_impls/serde.rs000064400000000000000000000150501046102023000203770ustar 00000000000000mod size_hint { use core::cmp; /// This presumably exists to prevent denial of service attacks. /// /// Original discussion: https://github.com/serde-rs/serde/issues/1114. #[cfg_attr(feature = "inline-more", inline)] pub(super) fn cautious(hint: Option) -> usize { cmp::min(hint.unwrap_or(0), 4096) } } mod map { use crate::raw::Allocator; use core::fmt; use core::hash::{BuildHasher, Hash}; use core::marker::PhantomData; use serde::de::{Deserialize, Deserializer, MapAccess, Visitor}; use serde::ser::{Serialize, Serializer}; use crate::hash_map::HashMap; use super::size_hint; impl Serialize for HashMap where K: Serialize + Eq + Hash, V: Serialize, H: BuildHasher, A: Allocator, { #[cfg_attr(feature = "inline-more", inline)] fn serialize(&self, serializer: S) -> Result where S: Serializer, { serializer.collect_map(self) } } impl<'de, K, V, S, A> Deserialize<'de> for HashMap where K: Deserialize<'de> + Eq + Hash, V: Deserialize<'de>, S: BuildHasher + Default, A: Allocator + Default, { fn deserialize(deserializer: D) -> Result where D: Deserializer<'de>, { struct MapVisitor where A: Allocator, { marker: PhantomData>, } impl<'de, K, V, S, A> Visitor<'de> for MapVisitor where K: Deserialize<'de> + Eq + Hash, V: Deserialize<'de>, S: BuildHasher + Default, A: Allocator + Default, { type Value = HashMap; fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { formatter.write_str("a map") } #[cfg_attr(feature = "inline-more", inline)] fn visit_map(self, mut map: M) -> Result where M: MapAccess<'de>, { let mut values = HashMap::with_capacity_and_hasher_in( size_hint::cautious(map.size_hint()), S::default(), A::default(), ); while let Some((key, value)) = map.next_entry()? { values.insert(key, value); } Ok(values) } } let visitor = MapVisitor { marker: PhantomData, }; deserializer.deserialize_map(visitor) } } } mod set { use crate::raw::Allocator; use core::fmt; use core::hash::{BuildHasher, Hash}; use core::marker::PhantomData; use serde::de::{Deserialize, Deserializer, SeqAccess, Visitor}; use serde::ser::{Serialize, Serializer}; use crate::hash_set::HashSet; use super::size_hint; impl Serialize for HashSet where T: Serialize + Eq + Hash, H: BuildHasher, A: Allocator, { #[cfg_attr(feature = "inline-more", inline)] fn serialize(&self, serializer: S) -> Result where S: Serializer, { serializer.collect_seq(self) } } impl<'de, T, S, A> Deserialize<'de> for HashSet where T: Deserialize<'de> + Eq + Hash, S: BuildHasher + Default, A: Allocator + Default, { fn deserialize(deserializer: D) -> Result where D: Deserializer<'de>, { struct SeqVisitor where A: Allocator, { marker: PhantomData>, } impl<'de, T, S, A> Visitor<'de> for SeqVisitor where T: Deserialize<'de> + Eq + Hash, S: BuildHasher + Default, A: Allocator + Default, { type Value = HashSet; fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { formatter.write_str("a sequence") } #[cfg_attr(feature = "inline-more", inline)] fn visit_seq(self, mut seq: M) -> Result where M: SeqAccess<'de>, { let mut values = HashSet::with_capacity_and_hasher_in( size_hint::cautious(seq.size_hint()), S::default(), A::default(), ); while let Some(value) = seq.next_element()? { values.insert(value); } Ok(values) } } let visitor = SeqVisitor { marker: PhantomData, }; deserializer.deserialize_seq(visitor) } #[allow(clippy::missing_errors_doc)] fn deserialize_in_place(deserializer: D, place: &mut Self) -> Result<(), D::Error> where D: Deserializer<'de>, { struct SeqInPlaceVisitor<'a, T, S, A>(&'a mut HashSet) where A: Allocator; impl<'a, 'de, T, S, A> Visitor<'de> for SeqInPlaceVisitor<'a, T, S, A> where T: Deserialize<'de> + Eq + Hash, S: BuildHasher + Default, A: Allocator, { type Value = (); fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { formatter.write_str("a sequence") } #[cfg_attr(feature = "inline-more", inline)] fn visit_seq(self, mut seq: M) -> Result where M: SeqAccess<'de>, { self.0.clear(); self.0.reserve(size_hint::cautious(seq.size_hint())); while let Some(value) = seq.next_element()? { self.0.insert(value); } Ok(()) } } deserializer.deserialize_seq(SeqInPlaceVisitor(place)) } } } hashbrown-0.14.5/src/lib.rs000064400000000000000000000126111046102023000136120ustar 00000000000000//! This crate is a Rust port of Google's high-performance [SwissTable] hash //! map, adapted to make it a drop-in replacement for Rust's standard `HashMap` //! and `HashSet` types. //! //! The original C++ version of [SwissTable] can be found [here], and this //! [CppCon talk] gives an overview of how the algorithm works. //! //! [SwissTable]: https://abseil.io/blog/20180927-swisstables //! [here]: https://github.com/abseil/abseil-cpp/blob/master/absl/container/internal/raw_hash_set.h //! [CppCon talk]: https://www.youtube.com/watch?v=ncHmEUmJZf4 #![no_std] #![cfg_attr( feature = "nightly", feature( test, core_intrinsics, dropck_eyepatch, min_specialization, extend_one, allocator_api, slice_ptr_get, maybe_uninit_array_assume_init, strict_provenance ) )] #![allow( clippy::doc_markdown, clippy::module_name_repetitions, clippy::must_use_candidate, clippy::option_if_let_else, clippy::redundant_else, clippy::manual_map, clippy::missing_safety_doc, clippy::missing_errors_doc )] #![warn(missing_docs)] #![warn(rust_2018_idioms)] #![cfg_attr(feature = "nightly", warn(fuzzy_provenance_casts))] #![cfg_attr(feature = "nightly", allow(internal_features))] #[cfg(test)] #[macro_use] extern crate std; #[cfg_attr(test, macro_use)] extern crate alloc; #[cfg(feature = "nightly")] #[cfg(doctest)] doc_comment::doctest!("../README.md"); #[macro_use] mod macros; #[cfg(feature = "raw")] /// Experimental and unsafe `RawTable` API. This module is only available if the /// `raw` feature is enabled. pub mod raw { // The RawTable API is still experimental and is not properly documented yet. #[allow(missing_docs)] #[path = "mod.rs"] mod inner; pub use inner::*; #[cfg(feature = "rayon")] /// [rayon]-based parallel iterator types for hash maps. /// You will rarely need to interact with it directly unless you have need /// to name one of the iterator types. /// /// [rayon]: https://docs.rs/rayon/1.0/rayon pub mod rayon { pub use crate::external_trait_impls::rayon::raw::*; } } #[cfg(not(feature = "raw"))] mod raw; mod external_trait_impls; mod map; #[cfg(feature = "rustc-internal-api")] mod rustc_entry; mod scopeguard; mod set; mod table; pub mod hash_map { //! A hash map implemented with quadratic probing and SIMD lookup. pub use crate::map::*; #[cfg(feature = "rustc-internal-api")] pub use crate::rustc_entry::*; #[cfg(feature = "rayon")] /// [rayon]-based parallel iterator types for hash maps. /// You will rarely need to interact with it directly unless you have need /// to name one of the iterator types. /// /// [rayon]: https://docs.rs/rayon/1.0/rayon pub mod rayon { pub use crate::external_trait_impls::rayon::map::*; } } pub mod hash_set { //! A hash set implemented as a `HashMap` where the value is `()`. pub use crate::set::*; #[cfg(feature = "rayon")] /// [rayon]-based parallel iterator types for hash sets. /// You will rarely need to interact with it directly unless you have need /// to name one of the iterator types. /// /// [rayon]: https://docs.rs/rayon/1.0/rayon pub mod rayon { pub use crate::external_trait_impls::rayon::set::*; } } pub mod hash_table { //! A hash table implemented with quadratic probing and SIMD lookup. pub use crate::table::*; #[cfg(feature = "rayon")] /// [rayon]-based parallel iterator types for hash tables. /// You will rarely need to interact with it directly unless you have need /// to name one of the iterator types. /// /// [rayon]: https://docs.rs/rayon/1.0/rayon pub mod rayon { pub use crate::external_trait_impls::rayon::table::*; } } pub use crate::map::HashMap; pub use crate::set::HashSet; pub use crate::table::HashTable; #[cfg(feature = "equivalent")] pub use equivalent::Equivalent; // This is only used as a fallback when building as part of `std`. #[cfg(not(feature = "equivalent"))] /// Key equivalence trait. /// /// This trait defines the function used to compare the input value with the /// map keys (or set values) during a lookup operation such as [`HashMap::get`] /// or [`HashSet::contains`]. /// It is provided with a blanket implementation based on the /// [`Borrow`](core::borrow::Borrow) trait. /// /// # Correctness /// /// Equivalent values must hash to the same value. pub trait Equivalent { /// Checks if this value is equivalent to the given key. /// /// Returns `true` if both values are equivalent, and `false` otherwise. /// /// # Correctness /// /// When this function returns `true`, both `self` and `key` must hash to /// the same value. fn equivalent(&self, key: &K) -> bool; } #[cfg(not(feature = "equivalent"))] impl Equivalent for Q where Q: Eq, K: core::borrow::Borrow, { fn equivalent(&self, key: &K) -> bool { self == key.borrow() } } /// The error type for `try_reserve` methods. #[derive(Clone, PartialEq, Eq, Debug)] pub enum TryReserveError { /// Error due to the computed capacity exceeding the collection's maximum /// (usually `isize::MAX` bytes). CapacityOverflow, /// The memory allocator returned an error AllocError { /// The layout of the allocation request that failed. layout: alloc::alloc::Layout, }, } hashbrown-0.14.5/src/macros.rs000064400000000000000000000042061046102023000143310ustar 00000000000000// See the cfg-if crate. #[allow(unused_macro_rules)] macro_rules! cfg_if { // match if/else chains with a final `else` ($( if #[cfg($($meta:meta),*)] { $($it:item)* } ) else * else { $($it2:item)* }) => { cfg_if! { @__items () ; $( ( ($($meta),*) ($($it)*) ), )* ( () ($($it2)*) ), } }; // match if/else chains lacking a final `else` ( if #[cfg($($i_met:meta),*)] { $($i_it:item)* } $( else if #[cfg($($e_met:meta),*)] { $($e_it:item)* } )* ) => { cfg_if! { @__items () ; ( ($($i_met),*) ($($i_it)*) ), $( ( ($($e_met),*) ($($e_it)*) ), )* ( () () ), } }; // Internal and recursive macro to emit all the items // // Collects all the negated cfgs in a list at the beginning and after the // semicolon is all the remaining items (@__items ($($not:meta,)*) ; ) => {}; (@__items ($($not:meta,)*) ; ( ($($m:meta),*) ($($it:item)*) ), $($rest:tt)*) => { // Emit all items within one block, applying an appropriate #[cfg]. The // #[cfg] will require all `$m` matchers specified and must also negate // all previous matchers. cfg_if! { @__apply cfg(all($($m,)* not(any($($not),*)))), $($it)* } // Recurse to emit all other items in `$rest`, and when we do so add all // our `$m` matchers to the list of `$not` matchers as future emissions // will have to negate everything we just matched as well. cfg_if! { @__items ($($not,)* $($m,)*) ; $($rest)* } }; // Internal macro to Apply a cfg attribute to a list of items (@__apply $m:meta, $($it:item)*) => { $(#[$m] $it)* }; } // Helper macro for specialization. This also helps avoid parse errors if the // default fn syntax for specialization changes in the future. #[cfg(feature = "nightly")] macro_rules! default_fn { (#[$($a:tt)*] $($tt:tt)*) => { #[$($a)*] default $($tt)* } } #[cfg(not(feature = "nightly"))] macro_rules! default_fn { ($($tt:tt)*) => { $($tt)* } } hashbrown-0.14.5/src/map.rs000064400000000000000000010437131046102023000136310ustar 00000000000000use crate::raw::{ Allocator, Bucket, Global, RawDrain, RawExtractIf, RawIntoIter, RawIter, RawTable, }; use crate::{Equivalent, TryReserveError}; use core::borrow::Borrow; use core::fmt::{self, Debug}; use core::hash::{BuildHasher, Hash}; use core::iter::FusedIterator; use core::marker::PhantomData; use core::mem; use core::ops::Index; /// Default hasher for `HashMap`. #[cfg(feature = "ahash")] pub type DefaultHashBuilder = core::hash::BuildHasherDefault; /// Dummy default hasher for `HashMap`. #[cfg(not(feature = "ahash"))] pub enum DefaultHashBuilder {} /// A hash map implemented with quadratic probing and SIMD lookup. /// /// The default hashing algorithm is currently [`AHash`], though this is /// subject to change at any point in the future. This hash function is very /// fast for all types of keys, but this algorithm will typically *not* protect /// against attacks such as HashDoS. /// /// The hashing algorithm can be replaced on a per-`HashMap` basis using the /// [`default`], [`with_hasher`], and [`with_capacity_and_hasher`] methods. Many /// alternative algorithms are available on crates.io, such as the [`fnv`] crate. /// /// It is required that the keys implement the [`Eq`] and [`Hash`] traits, although /// this can frequently be achieved by using `#[derive(PartialEq, Eq, Hash)]`. /// If you implement these yourself, it is important that the following /// property holds: /// /// ```text /// k1 == k2 -> hash(k1) == hash(k2) /// ``` /// /// In other words, if two keys are equal, their hashes must be equal. /// /// It is a logic error for a key to be modified in such a way that the key's /// hash, as determined by the [`Hash`] trait, or its equality, as determined by /// the [`Eq`] trait, changes while it is in the map. This is normally only /// possible through [`Cell`], [`RefCell`], global state, I/O, or unsafe code. /// /// It is also a logic error for the [`Hash`] implementation of a key to panic. /// This is generally only possible if the trait is implemented manually. If a /// panic does occur then the contents of the `HashMap` may become corrupted and /// some items may be dropped from the table. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// // Type inference lets us omit an explicit type signature (which /// // would be `HashMap` in this example). /// let mut book_reviews = HashMap::new(); /// /// // Review some books. /// book_reviews.insert( /// "Adventures of Huckleberry Finn".to_string(), /// "My favorite book.".to_string(), /// ); /// book_reviews.insert( /// "Grimms' Fairy Tales".to_string(), /// "Masterpiece.".to_string(), /// ); /// book_reviews.insert( /// "Pride and Prejudice".to_string(), /// "Very enjoyable.".to_string(), /// ); /// book_reviews.insert( /// "The Adventures of Sherlock Holmes".to_string(), /// "Eye lyked it alot.".to_string(), /// ); /// /// // Check for a specific one. /// // When collections store owned values (String), they can still be /// // queried using references (&str). /// if !book_reviews.contains_key("Les Misérables") { /// println!("We've got {} reviews, but Les Misérables ain't one.", /// book_reviews.len()); /// } /// /// // oops, this review has a lot of spelling mistakes, let's delete it. /// book_reviews.remove("The Adventures of Sherlock Holmes"); /// /// // Look up the values associated with some keys. /// let to_find = ["Pride and Prejudice", "Alice's Adventure in Wonderland"]; /// for &book in &to_find { /// match book_reviews.get(book) { /// Some(review) => println!("{}: {}", book, review), /// None => println!("{} is unreviewed.", book) /// } /// } /// /// // Look up the value for a key (will panic if the key is not found). /// println!("Review for Jane: {}", book_reviews["Pride and Prejudice"]); /// /// // Iterate over everything. /// for (book, review) in &book_reviews { /// println!("{}: \"{}\"", book, review); /// } /// ``` /// /// `HashMap` also implements an [`Entry API`](#method.entry), which allows /// for more complex methods of getting, setting, updating and removing keys and /// their values: /// /// ``` /// use hashbrown::HashMap; /// /// // type inference lets us omit an explicit type signature (which /// // would be `HashMap<&str, u8>` in this example). /// let mut player_stats = HashMap::new(); /// /// fn random_stat_buff() -> u8 { /// // could actually return some random value here - let's just return /// // some fixed value for now /// 42 /// } /// /// // insert a key only if it doesn't already exist /// player_stats.entry("health").or_insert(100); /// /// // insert a key using a function that provides a new value only if it /// // doesn't already exist /// player_stats.entry("defence").or_insert_with(random_stat_buff); /// /// // update a key, guarding against the key possibly not being set /// let stat = player_stats.entry("attack").or_insert(100); /// *stat += random_stat_buff(); /// ``` /// /// The easiest way to use `HashMap` with a custom key type is to derive [`Eq`] and [`Hash`]. /// We must also derive [`PartialEq`]. /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// [`PartialEq`]: https://doc.rust-lang.org/std/cmp/trait.PartialEq.html /// [`RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.html /// [`Cell`]: https://doc.rust-lang.org/std/cell/struct.Cell.html /// [`default`]: #method.default /// [`with_hasher`]: #method.with_hasher /// [`with_capacity_and_hasher`]: #method.with_capacity_and_hasher /// [`fnv`]: https://crates.io/crates/fnv /// [`AHash`]: https://crates.io/crates/ahash /// /// ``` /// use hashbrown::HashMap; /// /// #[derive(Hash, Eq, PartialEq, Debug)] /// struct Viking { /// name: String, /// country: String, /// } /// /// impl Viking { /// /// Creates a new Viking. /// fn new(name: &str, country: &str) -> Viking { /// Viking { name: name.to_string(), country: country.to_string() } /// } /// } /// /// // Use a HashMap to store the vikings' health points. /// let mut vikings = HashMap::new(); /// /// vikings.insert(Viking::new("Einar", "Norway"), 25); /// vikings.insert(Viking::new("Olaf", "Denmark"), 24); /// vikings.insert(Viking::new("Harald", "Iceland"), 12); /// /// // Use derived implementation to print the status of the vikings. /// for (viking, health) in &vikings { /// println!("{:?} has {} hp", viking, health); /// } /// ``` /// /// A `HashMap` with fixed list of elements can be initialized from an array: /// /// ``` /// use hashbrown::HashMap; /// /// let timber_resources: HashMap<&str, i32> = [("Norway", 100), ("Denmark", 50), ("Iceland", 10)] /// .into_iter().collect(); /// // use the values stored in map /// ``` pub struct HashMap { pub(crate) hash_builder: S, pub(crate) table: RawTable<(K, V), A>, } impl Clone for HashMap { fn clone(&self) -> Self { HashMap { hash_builder: self.hash_builder.clone(), table: self.table.clone(), } } fn clone_from(&mut self, source: &Self) { self.table.clone_from(&source.table); // Update hash_builder only if we successfully cloned all elements. self.hash_builder.clone_from(&source.hash_builder); } } /// Ensures that a single closure type across uses of this which, in turn prevents multiple /// instances of any functions like RawTable::reserve from being generated #[cfg_attr(feature = "inline-more", inline)] pub(crate) fn make_hasher(hash_builder: &S) -> impl Fn(&(Q, V)) -> u64 + '_ where Q: Hash, S: BuildHasher, { move |val| make_hash::(hash_builder, &val.0) } /// Ensures that a single closure type across uses of this which, in turn prevents multiple /// instances of any functions like RawTable::reserve from being generated #[cfg_attr(feature = "inline-more", inline)] fn equivalent_key(k: &Q) -> impl Fn(&(K, V)) -> bool + '_ where Q: ?Sized + Equivalent, { move |x| k.equivalent(&x.0) } /// Ensures that a single closure type across uses of this which, in turn prevents multiple /// instances of any functions like RawTable::reserve from being generated #[cfg_attr(feature = "inline-more", inline)] fn equivalent(k: &Q) -> impl Fn(&K) -> bool + '_ where Q: ?Sized + Equivalent, { move |x| k.equivalent(x) } #[cfg(not(feature = "nightly"))] #[cfg_attr(feature = "inline-more", inline)] pub(crate) fn make_hash(hash_builder: &S, val: &Q) -> u64 where Q: Hash + ?Sized, S: BuildHasher, { use core::hash::Hasher; let mut state = hash_builder.build_hasher(); val.hash(&mut state); state.finish() } #[cfg(feature = "nightly")] #[cfg_attr(feature = "inline-more", inline)] pub(crate) fn make_hash(hash_builder: &S, val: &Q) -> u64 where Q: Hash + ?Sized, S: BuildHasher, { hash_builder.hash_one(val) } #[cfg(feature = "ahash")] impl HashMap { /// Creates an empty `HashMap`. /// /// The hash map is initially created with a capacity of 0, so it will not allocate until it /// is first inserted into. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashMap` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashMap`], for example with /// [`with_hasher`](HashMap::with_hasher) method. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// let mut map: HashMap<&str, i32> = HashMap::new(); /// assert_eq!(map.len(), 0); /// assert_eq!(map.capacity(), 0); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn new() -> Self { Self::default() } /// Creates an empty `HashMap` with the specified capacity. /// /// The hash map will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash map will not allocate. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashMap` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashMap`], for example with /// [`with_capacity_and_hasher`](HashMap::with_capacity_and_hasher) method. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// let mut map: HashMap<&str, i32> = HashMap::with_capacity(10); /// assert_eq!(map.len(), 0); /// assert!(map.capacity() >= 10); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn with_capacity(capacity: usize) -> Self { Self::with_capacity_and_hasher(capacity, DefaultHashBuilder::default()) } } #[cfg(feature = "ahash")] impl HashMap { /// Creates an empty `HashMap` using the given allocator. /// /// The hash map is initially created with a capacity of 0, so it will not allocate until it /// is first inserted into. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashMap` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashMap`], for example with /// [`with_hasher_in`](HashMap::with_hasher_in) method. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use bumpalo::Bump; /// /// let bump = Bump::new(); /// let mut map = HashMap::new_in(&bump); /// /// // The created HashMap holds none elements /// assert_eq!(map.len(), 0); /// /// // The created HashMap also doesn't allocate memory /// assert_eq!(map.capacity(), 0); /// /// // Now we insert element inside created HashMap /// map.insert("One", 1); /// // We can see that the HashMap holds 1 element /// assert_eq!(map.len(), 1); /// // And it also allocates some capacity /// assert!(map.capacity() > 1); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn new_in(alloc: A) -> Self { Self::with_hasher_in(DefaultHashBuilder::default(), alloc) } /// Creates an empty `HashMap` with the specified capacity using the given allocator. /// /// The hash map will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash map will not allocate. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashMap` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashMap`], for example with /// [`with_capacity_and_hasher_in`](HashMap::with_capacity_and_hasher_in) method. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use bumpalo::Bump; /// /// let bump = Bump::new(); /// let mut map = HashMap::with_capacity_in(5, &bump); /// /// // The created HashMap holds none elements /// assert_eq!(map.len(), 0); /// // But it can hold at least 5 elements without reallocating /// let empty_map_capacity = map.capacity(); /// assert!(empty_map_capacity >= 5); /// /// // Now we insert some 5 elements inside created HashMap /// map.insert("One", 1); /// map.insert("Two", 2); /// map.insert("Three", 3); /// map.insert("Four", 4); /// map.insert("Five", 5); /// /// // We can see that the HashMap holds 5 elements /// assert_eq!(map.len(), 5); /// // But its capacity isn't changed /// assert_eq!(map.capacity(), empty_map_capacity) /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn with_capacity_in(capacity: usize, alloc: A) -> Self { Self::with_capacity_and_hasher_in(capacity, DefaultHashBuilder::default(), alloc) } } impl HashMap { /// Creates an empty `HashMap` which will use the given hash builder to hash /// keys. /// /// The hash map is initially created with a capacity of 0, so it will not /// allocate until it is first inserted into. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashMap` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashMap`]. /// /// The `hash_builder` passed should implement the [`BuildHasher`] trait for /// the HashMap to be useful, see its documentation for details. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// [`BuildHasher`]: https://doc.rust-lang.org/std/hash/trait.BuildHasher.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let s = DefaultHashBuilder::default(); /// let mut map = HashMap::with_hasher(s); /// assert_eq!(map.len(), 0); /// assert_eq!(map.capacity(), 0); /// /// map.insert(1, 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub const fn with_hasher(hash_builder: S) -> Self { Self { hash_builder, table: RawTable::new(), } } /// Creates an empty `HashMap` with the specified capacity, using `hash_builder` /// to hash the keys. /// /// The hash map will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash map will not allocate. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashMap` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashMap`]. /// /// The `hash_builder` passed should implement the [`BuildHasher`] trait for /// the HashMap to be useful, see its documentation for details. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// [`BuildHasher`]: https://doc.rust-lang.org/std/hash/trait.BuildHasher.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let s = DefaultHashBuilder::default(); /// let mut map = HashMap::with_capacity_and_hasher(10, s); /// assert_eq!(map.len(), 0); /// assert!(map.capacity() >= 10); /// /// map.insert(1, 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn with_capacity_and_hasher(capacity: usize, hash_builder: S) -> Self { Self { hash_builder, table: RawTable::with_capacity(capacity), } } } impl HashMap { /// Returns a reference to the underlying allocator. #[inline] pub fn allocator(&self) -> &A { self.table.allocator() } /// Creates an empty `HashMap` which will use the given hash builder to hash /// keys. It will be allocated with the given allocator. /// /// The hash map is initially created with a capacity of 0, so it will not allocate until it /// is first inserted into. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashMap` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashMap`]. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let s = DefaultHashBuilder::default(); /// let mut map = HashMap::with_hasher(s); /// map.insert(1, 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub const fn with_hasher_in(hash_builder: S, alloc: A) -> Self { Self { hash_builder, table: RawTable::new_in(alloc), } } /// Creates an empty `HashMap` with the specified capacity, using `hash_builder` /// to hash the keys. It will be allocated with the given allocator. /// /// The hash map will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash map will not allocate. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashMap` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashMap`]. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let s = DefaultHashBuilder::default(); /// let mut map = HashMap::with_capacity_and_hasher(10, s); /// map.insert(1, 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn with_capacity_and_hasher_in(capacity: usize, hash_builder: S, alloc: A) -> Self { Self { hash_builder, table: RawTable::with_capacity_in(capacity, alloc), } } /// Returns a reference to the map's [`BuildHasher`]. /// /// [`BuildHasher`]: https://doc.rust-lang.org/std/hash/trait.BuildHasher.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let hasher = DefaultHashBuilder::default(); /// let map: HashMap = HashMap::with_hasher(hasher); /// let hasher: &DefaultHashBuilder = map.hasher(); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn hasher(&self) -> &S { &self.hash_builder } /// Returns the number of elements the map can hold without reallocating. /// /// This number is a lower bound; the `HashMap` might be able to hold /// more, but is guaranteed to be able to hold at least this many. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// let map: HashMap = HashMap::with_capacity(100); /// assert_eq!(map.len(), 0); /// assert!(map.capacity() >= 100); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn capacity(&self) -> usize { self.table.capacity() } /// An iterator visiting all keys in arbitrary order. /// The iterator element type is `&'a K`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert("a", 1); /// map.insert("b", 2); /// map.insert("c", 3); /// assert_eq!(map.len(), 3); /// let mut vec: Vec<&str> = Vec::new(); /// /// for key in map.keys() { /// println!("{}", key); /// vec.push(*key); /// } /// /// // The `Keys` iterator produces keys in arbitrary order, so the /// // keys must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, ["a", "b", "c"]); /// /// assert_eq!(map.len(), 3); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn keys(&self) -> Keys<'_, K, V> { Keys { inner: self.iter() } } /// An iterator visiting all values in arbitrary order. /// The iterator element type is `&'a V`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert("a", 1); /// map.insert("b", 2); /// map.insert("c", 3); /// assert_eq!(map.len(), 3); /// let mut vec: Vec = Vec::new(); /// /// for val in map.values() { /// println!("{}", val); /// vec.push(*val); /// } /// /// // The `Values` iterator produces values in arbitrary order, so the /// // values must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [1, 2, 3]); /// /// assert_eq!(map.len(), 3); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn values(&self) -> Values<'_, K, V> { Values { inner: self.iter() } } /// An iterator visiting all values mutably in arbitrary order. /// The iterator element type is `&'a mut V`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// /// map.insert("a", 1); /// map.insert("b", 2); /// map.insert("c", 3); /// /// for val in map.values_mut() { /// *val = *val + 10; /// } /// /// assert_eq!(map.len(), 3); /// let mut vec: Vec = Vec::new(); /// /// for val in map.values() { /// println!("{}", val); /// vec.push(*val); /// } /// /// // The `Values` iterator produces values in arbitrary order, so the /// // values must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [11, 12, 13]); /// /// assert_eq!(map.len(), 3); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn values_mut(&mut self) -> ValuesMut<'_, K, V> { ValuesMut { inner: self.iter_mut(), } } /// An iterator visiting all key-value pairs in arbitrary order. /// The iterator element type is `(&'a K, &'a V)`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert("a", 1); /// map.insert("b", 2); /// map.insert("c", 3); /// assert_eq!(map.len(), 3); /// let mut vec: Vec<(&str, i32)> = Vec::new(); /// /// for (key, val) in map.iter() { /// println!("key: {} val: {}", key, val); /// vec.push((*key, *val)); /// } /// /// // The `Iter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [("a", 1), ("b", 2), ("c", 3)]); /// /// assert_eq!(map.len(), 3); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn iter(&self) -> Iter<'_, K, V> { // Here we tie the lifetime of self to the iter. unsafe { Iter { inner: self.table.iter(), marker: PhantomData, } } } /// An iterator visiting all key-value pairs in arbitrary order, /// with mutable references to the values. /// The iterator element type is `(&'a K, &'a mut V)`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert("a", 1); /// map.insert("b", 2); /// map.insert("c", 3); /// /// // Update all values /// for (_, val) in map.iter_mut() { /// *val *= 2; /// } /// /// assert_eq!(map.len(), 3); /// let mut vec: Vec<(&str, i32)> = Vec::new(); /// /// for (key, val) in &map { /// println!("key: {} val: {}", key, val); /// vec.push((*key, *val)); /// } /// /// // The `Iter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [("a", 2), ("b", 4), ("c", 6)]); /// /// assert_eq!(map.len(), 3); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn iter_mut(&mut self) -> IterMut<'_, K, V> { // Here we tie the lifetime of self to the iter. unsafe { IterMut { inner: self.table.iter(), marker: PhantomData, } } } #[cfg(test)] #[cfg_attr(feature = "inline-more", inline)] fn raw_capacity(&self) -> usize { self.table.buckets() } /// Returns the number of elements in the map. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut a = HashMap::new(); /// assert_eq!(a.len(), 0); /// a.insert(1, "a"); /// assert_eq!(a.len(), 1); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn len(&self) -> usize { self.table.len() } /// Returns `true` if the map contains no elements. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut a = HashMap::new(); /// assert!(a.is_empty()); /// a.insert(1, "a"); /// assert!(!a.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn is_empty(&self) -> bool { self.len() == 0 } /// Clears the map, returning all key-value pairs as an iterator. Keeps the /// allocated memory for reuse. /// /// If the returned iterator is dropped before being fully consumed, it /// drops the remaining key-value pairs. The returned iterator keeps a /// mutable borrow on the vector to optimize its implementation. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut a = HashMap::new(); /// a.insert(1, "a"); /// a.insert(2, "b"); /// let capacity_before_drain = a.capacity(); /// /// for (k, v) in a.drain().take(1) { /// assert!(k == 1 || k == 2); /// assert!(v == "a" || v == "b"); /// } /// /// // As we can see, the map is empty and contains no element. /// assert!(a.is_empty() && a.len() == 0); /// // But map capacity is equal to old one. /// assert_eq!(a.capacity(), capacity_before_drain); /// /// let mut a = HashMap::new(); /// a.insert(1, "a"); /// a.insert(2, "b"); /// /// { // Iterator is dropped without being consumed. /// let d = a.drain(); /// } /// /// // But the map is empty even if we do not use Drain iterator. /// assert!(a.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn drain(&mut self) -> Drain<'_, K, V, A> { Drain { inner: self.table.drain(), } } /// Retains only the elements specified by the predicate. Keeps the /// allocated memory for reuse. /// /// In other words, remove all pairs `(k, v)` such that `f(&k, &mut v)` returns `false`. /// The elements are visited in unsorted (and unspecified) order. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = (0..8).map(|x|(x, x*10)).collect(); /// assert_eq!(map.len(), 8); /// /// map.retain(|&k, _| k % 2 == 0); /// /// // We can see, that the number of elements inside map is changed. /// assert_eq!(map.len(), 4); /// /// let mut vec: Vec<(i32, i32)> = map.iter().map(|(&k, &v)| (k, v)).collect(); /// vec.sort_unstable(); /// assert_eq!(vec, [(0, 0), (2, 20), (4, 40), (6, 60)]); /// ``` pub fn retain(&mut self, mut f: F) where F: FnMut(&K, &mut V) -> bool, { // Here we only use `iter` as a temporary, preventing use-after-free unsafe { for item in self.table.iter() { let &mut (ref key, ref mut value) = item.as_mut(); if !f(key, value) { self.table.erase(item); } } } } /// Drains elements which are true under the given predicate, /// and returns an iterator over the removed items. /// /// In other words, move all pairs `(k, v)` such that `f(&k, &mut v)` returns `true` out /// into another iterator. /// /// Note that `extract_if` lets you mutate every value in the filter closure, regardless of /// whether you choose to keep or remove it. /// /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating /// or the iteration short-circuits, then the remaining elements will be retained. /// Use [`retain()`] with a negated predicate if you do not need the returned iterator. /// /// Keeps the allocated memory for reuse. /// /// [`retain()`]: HashMap::retain /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = (0..8).map(|x| (x, x)).collect(); /// /// let drained: HashMap = map.extract_if(|k, _v| k % 2 == 0).collect(); /// /// let mut evens = drained.keys().cloned().collect::>(); /// let mut odds = map.keys().cloned().collect::>(); /// evens.sort(); /// odds.sort(); /// /// assert_eq!(evens, vec![0, 2, 4, 6]); /// assert_eq!(odds, vec![1, 3, 5, 7]); /// /// let mut map: HashMap = (0..8).map(|x| (x, x)).collect(); /// /// { // Iterator is dropped without being consumed. /// let d = map.extract_if(|k, _v| k % 2 != 0); /// } /// /// // ExtractIf was not exhausted, therefore no elements were drained. /// assert_eq!(map.len(), 8); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn extract_if(&mut self, f: F) -> ExtractIf<'_, K, V, F, A> where F: FnMut(&K, &mut V) -> bool, { ExtractIf { f, inner: RawExtractIf { iter: unsafe { self.table.iter() }, table: &mut self.table, }, } } /// Clears the map, removing all key-value pairs. Keeps the allocated memory /// for reuse. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut a = HashMap::new(); /// a.insert(1, "a"); /// let capacity_before_clear = a.capacity(); /// /// a.clear(); /// /// // Map is empty. /// assert!(a.is_empty()); /// // But map capacity is equal to old one. /// assert_eq!(a.capacity(), capacity_before_clear); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn clear(&mut self) { self.table.clear(); } /// Creates a consuming iterator visiting all the keys in arbitrary order. /// The map cannot be used after calling this. /// The iterator element type is `K`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert("a", 1); /// map.insert("b", 2); /// map.insert("c", 3); /// /// let mut vec: Vec<&str> = map.into_keys().collect(); /// /// // The `IntoKeys` iterator produces keys in arbitrary order, so the /// // keys must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, ["a", "b", "c"]); /// ``` #[inline] pub fn into_keys(self) -> IntoKeys { IntoKeys { inner: self.into_iter(), } } /// Creates a consuming iterator visiting all the values in arbitrary order. /// The map cannot be used after calling this. /// The iterator element type is `V`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert("a", 1); /// map.insert("b", 2); /// map.insert("c", 3); /// /// let mut vec: Vec = map.into_values().collect(); /// /// // The `IntoValues` iterator produces values in arbitrary order, so /// // the values must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [1, 2, 3]); /// ``` #[inline] pub fn into_values(self) -> IntoValues { IntoValues { inner: self.into_iter(), } } } impl HashMap where K: Eq + Hash, S: BuildHasher, A: Allocator, { /// Reserves capacity for at least `additional` more elements to be inserted /// in the `HashMap`. The collection may reserve more space to avoid /// frequent reallocations. /// /// # Panics /// /// Panics if the new capacity exceeds [`isize::MAX`] bytes and [`abort`] the program /// in case of allocation error. Use [`try_reserve`](HashMap::try_reserve) instead /// if you want to handle memory allocation failure. /// /// [`isize::MAX`]: https://doc.rust-lang.org/std/primitive.isize.html /// [`abort`]: https://doc.rust-lang.org/alloc/alloc/fn.handle_alloc_error.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// let mut map: HashMap<&str, i32> = HashMap::new(); /// // Map is empty and doesn't allocate memory /// assert_eq!(map.capacity(), 0); /// /// map.reserve(10); /// /// // And now map can hold at least 10 elements /// assert!(map.capacity() >= 10); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn reserve(&mut self, additional: usize) { self.table .reserve(additional, make_hasher::<_, V, S>(&self.hash_builder)); } /// Tries to reserve capacity for at least `additional` more elements to be inserted /// in the given `HashMap`. The collection may reserve more space to avoid /// frequent reallocations. /// /// # Errors /// /// If the capacity overflows, or the allocator reports a failure, then an error /// is returned. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, isize> = HashMap::new(); /// // Map is empty and doesn't allocate memory /// assert_eq!(map.capacity(), 0); /// /// map.try_reserve(10).expect("why is the test harness OOMing on 10 bytes?"); /// /// // And now map can hold at least 10 elements /// assert!(map.capacity() >= 10); /// ``` /// If the capacity overflows, or the allocator reports a failure, then an error /// is returned: /// ``` /// # fn test() { /// use hashbrown::HashMap; /// use hashbrown::TryReserveError; /// let mut map: HashMap = HashMap::new(); /// /// match map.try_reserve(usize::MAX) { /// Err(error) => match error { /// TryReserveError::CapacityOverflow => {} /// _ => panic!("TryReserveError::AllocError ?"), /// }, /// _ => panic!(), /// } /// # } /// # fn main() { /// # #[cfg(not(miri))] /// # test() /// # } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { self.table .try_reserve(additional, make_hasher::<_, V, S>(&self.hash_builder)) } /// Shrinks the capacity of the map as much as possible. It will drop /// down as much as possible while maintaining the internal rules /// and possibly leaving some space in accordance with the resize policy. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = HashMap::with_capacity(100); /// map.insert(1, 2); /// map.insert(3, 4); /// assert!(map.capacity() >= 100); /// map.shrink_to_fit(); /// assert!(map.capacity() >= 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn shrink_to_fit(&mut self) { self.table .shrink_to(0, make_hasher::<_, V, S>(&self.hash_builder)); } /// Shrinks the capacity of the map with a lower limit. It will drop /// down no lower than the supplied limit while maintaining the internal rules /// and possibly leaving some space in accordance with the resize policy. /// /// This function does nothing if the current capacity is smaller than the /// supplied minimum capacity. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = HashMap::with_capacity(100); /// map.insert(1, 2); /// map.insert(3, 4); /// assert!(map.capacity() >= 100); /// map.shrink_to(10); /// assert!(map.capacity() >= 10); /// map.shrink_to(0); /// assert!(map.capacity() >= 2); /// map.shrink_to(10); /// assert!(map.capacity() >= 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn shrink_to(&mut self, min_capacity: usize) { self.table .shrink_to(min_capacity, make_hasher::<_, V, S>(&self.hash_builder)); } /// Gets the given key's corresponding entry in the map for in-place manipulation. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut letters = HashMap::new(); /// /// for ch in "a short treatise on fungi".chars() { /// let counter = letters.entry(ch).or_insert(0); /// *counter += 1; /// } /// /// assert_eq!(letters[&'s'], 2); /// assert_eq!(letters[&'t'], 3); /// assert_eq!(letters[&'u'], 1); /// assert_eq!(letters.get(&'y'), None); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn entry(&mut self, key: K) -> Entry<'_, K, V, S, A> { let hash = make_hash::(&self.hash_builder, &key); if let Some(elem) = self.table.find(hash, equivalent_key(&key)) { Entry::Occupied(OccupiedEntry { hash, key: Some(key), elem, table: self, }) } else { Entry::Vacant(VacantEntry { hash, key, table: self, }) } } /// Gets the given key's corresponding entry by reference in the map for in-place manipulation. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut words: HashMap = HashMap::new(); /// let source = ["poneyland", "horseyland", "poneyland", "poneyland"]; /// for (i, &s) in source.iter().enumerate() { /// let counter = words.entry_ref(s).or_insert(0); /// *counter += 1; /// } /// /// assert_eq!(words["poneyland"], 3); /// assert_eq!(words["horseyland"], 1); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn entry_ref<'a, 'b, Q: ?Sized>(&'a mut self, key: &'b Q) -> EntryRef<'a, 'b, K, Q, V, S, A> where Q: Hash + Equivalent, { let hash = make_hash::(&self.hash_builder, key); if let Some(elem) = self.table.find(hash, equivalent_key(key)) { EntryRef::Occupied(OccupiedEntryRef { hash, key: Some(KeyOrRef::Borrowed(key)), elem, table: self, }) } else { EntryRef::Vacant(VacantEntryRef { hash, key: KeyOrRef::Borrowed(key), table: self, }) } } /// Returns a reference to the value corresponding to the key. /// /// The key may be any borrowed form of the map's key type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the key type. /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert(1, "a"); /// assert_eq!(map.get(&1), Some(&"a")); /// assert_eq!(map.get(&2), None); /// ``` #[inline] pub fn get(&self, k: &Q) -> Option<&V> where Q: Hash + Equivalent, { // Avoid `Option::map` because it bloats LLVM IR. match self.get_inner(k) { Some((_, v)) => Some(v), None => None, } } /// Returns the key-value pair corresponding to the supplied key. /// /// The supplied key may be any borrowed form of the map's key type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the key type. /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert(1, "a"); /// assert_eq!(map.get_key_value(&1), Some((&1, &"a"))); /// assert_eq!(map.get_key_value(&2), None); /// ``` #[inline] pub fn get_key_value(&self, k: &Q) -> Option<(&K, &V)> where Q: Hash + Equivalent, { // Avoid `Option::map` because it bloats LLVM IR. match self.get_inner(k) { Some((key, value)) => Some((key, value)), None => None, } } #[inline] fn get_inner(&self, k: &Q) -> Option<&(K, V)> where Q: Hash + Equivalent, { if self.table.is_empty() { None } else { let hash = make_hash::(&self.hash_builder, k); self.table.get(hash, equivalent_key(k)) } } /// Returns the key-value pair corresponding to the supplied key, with a mutable reference to value. /// /// The supplied key may be any borrowed form of the map's key type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the key type. /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert(1, "a"); /// let (k, v) = map.get_key_value_mut(&1).unwrap(); /// assert_eq!(k, &1); /// assert_eq!(v, &mut "a"); /// *v = "b"; /// assert_eq!(map.get_key_value_mut(&1), Some((&1, &mut "b"))); /// assert_eq!(map.get_key_value_mut(&2), None); /// ``` #[inline] pub fn get_key_value_mut(&mut self, k: &Q) -> Option<(&K, &mut V)> where Q: Hash + Equivalent, { // Avoid `Option::map` because it bloats LLVM IR. match self.get_inner_mut(k) { Some(&mut (ref key, ref mut value)) => Some((key, value)), None => None, } } /// Returns `true` if the map contains a value for the specified key. /// /// The key may be any borrowed form of the map's key type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the key type. /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert(1, "a"); /// assert_eq!(map.contains_key(&1), true); /// assert_eq!(map.contains_key(&2), false); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn contains_key(&self, k: &Q) -> bool where Q: Hash + Equivalent, { self.get_inner(k).is_some() } /// Returns a mutable reference to the value corresponding to the key. /// /// The key may be any borrowed form of the map's key type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the key type. /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.insert(1, "a"); /// if let Some(x) = map.get_mut(&1) { /// *x = "b"; /// } /// assert_eq!(map[&1], "b"); /// /// assert_eq!(map.get_mut(&2), None); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get_mut(&mut self, k: &Q) -> Option<&mut V> where Q: Hash + Equivalent, { // Avoid `Option::map` because it bloats LLVM IR. match self.get_inner_mut(k) { Some(&mut (_, ref mut v)) => Some(v), None => None, } } #[inline] fn get_inner_mut(&mut self, k: &Q) -> Option<&mut (K, V)> where Q: Hash + Equivalent, { if self.table.is_empty() { None } else { let hash = make_hash::(&self.hash_builder, k); self.table.get_mut(hash, equivalent_key(k)) } } /// Attempts to get mutable references to `N` values in the map at once. /// /// Returns an array of length `N` with the results of each query. For soundness, at most one /// mutable reference will be returned to any value. `None` will be returned if any of the /// keys are duplicates or missing. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut libraries = HashMap::new(); /// libraries.insert("Bodleian Library".to_string(), 1602); /// libraries.insert("Athenæum".to_string(), 1807); /// libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691); /// libraries.insert("Library of Congress".to_string(), 1800); /// /// let got = libraries.get_many_mut([ /// "Athenæum", /// "Library of Congress", /// ]); /// assert_eq!( /// got, /// Some([ /// &mut 1807, /// &mut 1800, /// ]), /// ); /// /// // Missing keys result in None /// let got = libraries.get_many_mut([ /// "Athenæum", /// "New York Public Library", /// ]); /// assert_eq!(got, None); /// /// // Duplicate keys result in None /// let got = libraries.get_many_mut([ /// "Athenæum", /// "Athenæum", /// ]); /// assert_eq!(got, None); /// ``` pub fn get_many_mut(&mut self, ks: [&Q; N]) -> Option<[&'_ mut V; N]> where Q: Hash + Equivalent, { self.get_many_mut_inner(ks).map(|res| res.map(|(_, v)| v)) } /// Attempts to get mutable references to `N` values in the map at once, without validating that /// the values are unique. /// /// Returns an array of length `N` with the results of each query. `None` will be returned if /// any of the keys are missing. /// /// For a safe alternative see [`get_many_mut`](`HashMap::get_many_mut`). /// /// # Safety /// /// Calling this method with overlapping keys is *[undefined behavior]* even if the resulting /// references are not used. /// /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut libraries = HashMap::new(); /// libraries.insert("Bodleian Library".to_string(), 1602); /// libraries.insert("Athenæum".to_string(), 1807); /// libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691); /// libraries.insert("Library of Congress".to_string(), 1800); /// /// let got = libraries.get_many_mut([ /// "Athenæum", /// "Library of Congress", /// ]); /// assert_eq!( /// got, /// Some([ /// &mut 1807, /// &mut 1800, /// ]), /// ); /// /// // Missing keys result in None /// let got = libraries.get_many_mut([ /// "Athenæum", /// "New York Public Library", /// ]); /// assert_eq!(got, None); /// ``` pub unsafe fn get_many_unchecked_mut( &mut self, ks: [&Q; N], ) -> Option<[&'_ mut V; N]> where Q: Hash + Equivalent, { self.get_many_unchecked_mut_inner(ks) .map(|res| res.map(|(_, v)| v)) } /// Attempts to get mutable references to `N` values in the map at once, with immutable /// references to the corresponding keys. /// /// Returns an array of length `N` with the results of each query. For soundness, at most one /// mutable reference will be returned to any value. `None` will be returned if any of the keys /// are duplicates or missing. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut libraries = HashMap::new(); /// libraries.insert("Bodleian Library".to_string(), 1602); /// libraries.insert("Athenæum".to_string(), 1807); /// libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691); /// libraries.insert("Library of Congress".to_string(), 1800); /// /// let got = libraries.get_many_key_value_mut([ /// "Bodleian Library", /// "Herzogin-Anna-Amalia-Bibliothek", /// ]); /// assert_eq!( /// got, /// Some([ /// (&"Bodleian Library".to_string(), &mut 1602), /// (&"Herzogin-Anna-Amalia-Bibliothek".to_string(), &mut 1691), /// ]), /// ); /// // Missing keys result in None /// let got = libraries.get_many_key_value_mut([ /// "Bodleian Library", /// "Gewandhaus", /// ]); /// assert_eq!(got, None); /// /// // Duplicate keys result in None /// let got = libraries.get_many_key_value_mut([ /// "Bodleian Library", /// "Herzogin-Anna-Amalia-Bibliothek", /// "Herzogin-Anna-Amalia-Bibliothek", /// ]); /// assert_eq!(got, None); /// ``` pub fn get_many_key_value_mut( &mut self, ks: [&Q; N], ) -> Option<[(&'_ K, &'_ mut V); N]> where Q: Hash + Equivalent, { self.get_many_mut_inner(ks) .map(|res| res.map(|(k, v)| (&*k, v))) } /// Attempts to get mutable references to `N` values in the map at once, with immutable /// references to the corresponding keys, without validating that the values are unique. /// /// Returns an array of length `N` with the results of each query. `None` will be returned if /// any of the keys are missing. /// /// For a safe alternative see [`get_many_key_value_mut`](`HashMap::get_many_key_value_mut`). /// /// # Safety /// /// Calling this method with overlapping keys is *[undefined behavior]* even if the resulting /// references are not used. /// /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut libraries = HashMap::new(); /// libraries.insert("Bodleian Library".to_string(), 1602); /// libraries.insert("Athenæum".to_string(), 1807); /// libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691); /// libraries.insert("Library of Congress".to_string(), 1800); /// /// let got = libraries.get_many_key_value_mut([ /// "Bodleian Library", /// "Herzogin-Anna-Amalia-Bibliothek", /// ]); /// assert_eq!( /// got, /// Some([ /// (&"Bodleian Library".to_string(), &mut 1602), /// (&"Herzogin-Anna-Amalia-Bibliothek".to_string(), &mut 1691), /// ]), /// ); /// // Missing keys result in None /// let got = libraries.get_many_key_value_mut([ /// "Bodleian Library", /// "Gewandhaus", /// ]); /// assert_eq!(got, None); /// ``` pub unsafe fn get_many_key_value_unchecked_mut( &mut self, ks: [&Q; N], ) -> Option<[(&'_ K, &'_ mut V); N]> where Q: Hash + Equivalent, { self.get_many_unchecked_mut_inner(ks) .map(|res| res.map(|(k, v)| (&*k, v))) } fn get_many_mut_inner( &mut self, ks: [&Q; N], ) -> Option<[&'_ mut (K, V); N]> where Q: Hash + Equivalent, { let hashes = self.build_hashes_inner(ks); self.table .get_many_mut(hashes, |i, (k, _)| ks[i].equivalent(k)) } unsafe fn get_many_unchecked_mut_inner( &mut self, ks: [&Q; N], ) -> Option<[&'_ mut (K, V); N]> where Q: Hash + Equivalent, { let hashes = self.build_hashes_inner(ks); self.table .get_many_unchecked_mut(hashes, |i, (k, _)| ks[i].equivalent(k)) } fn build_hashes_inner(&self, ks: [&Q; N]) -> [u64; N] where Q: Hash + Equivalent, { let mut hashes = [0_u64; N]; for i in 0..N { hashes[i] = make_hash::(&self.hash_builder, ks[i]); } hashes } /// Inserts a key-value pair into the map. /// /// If the map did not have this key present, [`None`] is returned. /// /// If the map did have this key present, the value is updated, and the old /// value is returned. The key is not updated, though; this matters for /// types that can be `==` without being identical. See the [`std::collections`] /// [module-level documentation] for more. /// /// [`None`]: https://doc.rust-lang.org/std/option/enum.Option.html#variant.None /// [`std::collections`]: https://doc.rust-lang.org/std/collections/index.html /// [module-level documentation]: https://doc.rust-lang.org/std/collections/index.html#insert-and-complex-keys /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// assert_eq!(map.insert(37, "a"), None); /// assert_eq!(map.is_empty(), false); /// /// map.insert(37, "b"); /// assert_eq!(map.insert(37, "c"), Some("b")); /// assert_eq!(map[&37], "c"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(&mut self, k: K, v: V) -> Option { let hash = make_hash::(&self.hash_builder, &k); let hasher = make_hasher::<_, V, S>(&self.hash_builder); match self .table .find_or_find_insert_slot(hash, equivalent_key(&k), hasher) { Ok(bucket) => Some(mem::replace(unsafe { &mut bucket.as_mut().1 }, v)), Err(slot) => { unsafe { self.table.insert_in_slot(hash, slot, (k, v)); } None } } } /// Insert a key-value pair into the map without checking /// if the key already exists in the map. /// /// Returns a reference to the key and value just inserted. /// /// This operation is safe if a key does not exist in the map. /// /// However, if a key exists in the map already, the behavior is unspecified: /// this operation may panic, loop forever, or any following operation with the map /// may panic, loop forever or return arbitrary result. /// /// That said, this operation (and following operations) are guaranteed to /// not violate memory safety. /// /// This operation is faster than regular insert, because it does not perform /// lookup before insertion. /// /// This operation is useful during initial population of the map. /// For example, when constructing a map from another map, we know /// that keys are unique. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map1 = HashMap::new(); /// assert_eq!(map1.insert(1, "a"), None); /// assert_eq!(map1.insert(2, "b"), None); /// assert_eq!(map1.insert(3, "c"), None); /// assert_eq!(map1.len(), 3); /// /// let mut map2 = HashMap::new(); /// /// for (key, value) in map1.into_iter() { /// map2.insert_unique_unchecked(key, value); /// } /// /// let (key, value) = map2.insert_unique_unchecked(4, "d"); /// assert_eq!(key, &4); /// assert_eq!(value, &mut "d"); /// *value = "e"; /// /// assert_eq!(map2[&1], "a"); /// assert_eq!(map2[&2], "b"); /// assert_eq!(map2[&3], "c"); /// assert_eq!(map2[&4], "e"); /// assert_eq!(map2.len(), 4); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert_unique_unchecked(&mut self, k: K, v: V) -> (&K, &mut V) { let hash = make_hash::(&self.hash_builder, &k); let bucket = self .table .insert(hash, (k, v), make_hasher::<_, V, S>(&self.hash_builder)); let (k_ref, v_ref) = unsafe { bucket.as_mut() }; (k_ref, v_ref) } /// Tries to insert a key-value pair into the map, and returns /// a mutable reference to the value in the entry. /// /// # Errors /// /// If the map already had this key present, nothing is updated, and /// an error containing the occupied entry and the value is returned. /// /// # Examples /// /// Basic usage: /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::OccupiedError; /// /// let mut map = HashMap::new(); /// assert_eq!(map.try_insert(37, "a").unwrap(), &"a"); /// /// match map.try_insert(37, "b") { /// Err(OccupiedError { entry, value }) => { /// assert_eq!(entry.key(), &37); /// assert_eq!(entry.get(), &"a"); /// assert_eq!(value, "b"); /// } /// _ => panic!() /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn try_insert( &mut self, key: K, value: V, ) -> Result<&mut V, OccupiedError<'_, K, V, S, A>> { match self.entry(key) { Entry::Occupied(entry) => Err(OccupiedError { entry, value }), Entry::Vacant(entry) => Ok(entry.insert(value)), } } /// Removes a key from the map, returning the value at the key if the key /// was previously in the map. Keeps the allocated memory for reuse. /// /// The key may be any borrowed form of the map's key type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the key type. /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// // The map is empty /// assert!(map.is_empty() && map.capacity() == 0); /// /// map.insert(1, "a"); /// /// assert_eq!(map.remove(&1), Some("a")); /// assert_eq!(map.remove(&1), None); /// /// // Now map holds none elements /// assert!(map.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove(&mut self, k: &Q) -> Option where Q: Hash + Equivalent, { // Avoid `Option::map` because it bloats LLVM IR. match self.remove_entry(k) { Some((_, v)) => Some(v), None => None, } } /// Removes a key from the map, returning the stored key and value if the /// key was previously in the map. Keeps the allocated memory for reuse. /// /// The key may be any borrowed form of the map's key type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the key type. /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// // The map is empty /// assert!(map.is_empty() && map.capacity() == 0); /// /// map.insert(1, "a"); /// /// assert_eq!(map.remove_entry(&1), Some((1, "a"))); /// assert_eq!(map.remove(&1), None); /// /// // Now map hold none elements /// assert!(map.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove_entry(&mut self, k: &Q) -> Option<(K, V)> where Q: Hash + Equivalent, { let hash = make_hash::(&self.hash_builder, k); self.table.remove_entry(hash, equivalent_key(k)) } } impl HashMap { /// Creates a raw entry builder for the HashMap. /// /// Raw entries provide the lowest level of control for searching and /// manipulating a map. They must be manually initialized with a hash and /// then manually searched. After this, insertions into a vacant entry /// still require an owned key to be provided. /// /// Raw entries are useful for such exotic situations as: /// /// * Hash memoization /// * Deferring the creation of an owned key until it is known to be required /// * Using a search key that doesn't work with the Borrow trait /// * Using custom comparison logic without newtype wrappers /// /// Because raw entries provide much more low-level control, it's much easier /// to put the HashMap into an inconsistent state which, while memory-safe, /// will cause the map to produce seemingly random results. Higher-level and /// more foolproof APIs like `entry` should be preferred when possible. /// /// In particular, the hash used to initialized the raw entry must still be /// consistent with the hash of the key that is ultimately stored in the entry. /// This is because implementations of HashMap may need to recompute hashes /// when resizing, at which point only the keys are available. /// /// Raw entries give mutable access to the keys. This must not be used /// to modify how the key would compare or hash, as the map will not re-evaluate /// where the key should go, meaning the keys may become "lost" if their /// location does not reflect their state. For instance, if you change a key /// so that the map now contains keys which compare equal, search may start /// acting erratically, with two keys randomly masking each other. Implementations /// are free to assume this doesn't happen (within the limits of memory-safety). /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map = HashMap::new(); /// map.extend([("a", 100), ("b", 200), ("c", 300)]); /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// // Existing key (insert and update) /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => unreachable!(), /// RawEntryMut::Occupied(mut view) => { /// assert_eq!(view.get(), &100); /// let v = view.get_mut(); /// let new_v = (*v) * 10; /// *v = new_v; /// assert_eq!(view.insert(1111), 1000); /// } /// } /// /// assert_eq!(map[&"a"], 1111); /// assert_eq!(map.len(), 3); /// /// // Existing key (take) /// let hash = compute_hash(map.hasher(), &"c"); /// match map.raw_entry_mut().from_key_hashed_nocheck(hash, &"c") { /// RawEntryMut::Vacant(_) => unreachable!(), /// RawEntryMut::Occupied(view) => { /// assert_eq!(view.remove_entry(), ("c", 300)); /// } /// } /// assert_eq!(map.raw_entry().from_key(&"c"), None); /// assert_eq!(map.len(), 2); /// /// // Nonexistent key (insert and update) /// let key = "d"; /// let hash = compute_hash(map.hasher(), &key); /// match map.raw_entry_mut().from_hash(hash, |q| *q == key) { /// RawEntryMut::Occupied(_) => unreachable!(), /// RawEntryMut::Vacant(view) => { /// let (k, value) = view.insert("d", 4000); /// assert_eq!((*k, *value), ("d", 4000)); /// *value = 40000; /// } /// } /// assert_eq!(map[&"d"], 40000); /// assert_eq!(map.len(), 3); /// /// match map.raw_entry_mut().from_hash(hash, |q| *q == key) { /// RawEntryMut::Vacant(_) => unreachable!(), /// RawEntryMut::Occupied(view) => { /// assert_eq!(view.remove_entry(), ("d", 40000)); /// } /// } /// assert_eq!(map.get(&"d"), None); /// assert_eq!(map.len(), 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn raw_entry_mut(&mut self) -> RawEntryBuilderMut<'_, K, V, S, A> { RawEntryBuilderMut { map: self } } /// Creates a raw immutable entry builder for the HashMap. /// /// Raw entries provide the lowest level of control for searching and /// manipulating a map. They must be manually initialized with a hash and /// then manually searched. /// /// This is useful for /// * Hash memoization /// * Using a search key that doesn't work with the Borrow trait /// * Using custom comparison logic without newtype wrappers /// /// Unless you are in such a situation, higher-level and more foolproof APIs like /// `get` should be preferred. /// /// Immutable raw entries have very limited use; you might instead want `raw_entry_mut`. /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.extend([("a", 100), ("b", 200), ("c", 300)]); /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// for k in ["a", "b", "c", "d", "e", "f"] { /// let hash = compute_hash(map.hasher(), k); /// let v = map.get(&k).cloned(); /// let kv = v.as_ref().map(|v| (&k, v)); /// /// println!("Key: {} and value: {:?}", k, v); /// /// assert_eq!(map.raw_entry().from_key(&k), kv); /// assert_eq!(map.raw_entry().from_hash(hash, |q| *q == k), kv); /// assert_eq!(map.raw_entry().from_key_hashed_nocheck(hash, &k), kv); /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn raw_entry(&self) -> RawEntryBuilder<'_, K, V, S, A> { RawEntryBuilder { map: self } } /// Returns a reference to the [`RawTable`] used underneath [`HashMap`]. /// This function is only available if the `raw` feature of the crate is enabled. /// /// See [`raw_table_mut`] for more. /// /// [`raw_table_mut`]: Self::raw_table_mut #[cfg(feature = "raw")] #[cfg_attr(feature = "inline-more", inline)] pub fn raw_table(&self) -> &RawTable<(K, V), A> { &self.table } /// Returns a mutable reference to the [`RawTable`] used underneath [`HashMap`]. /// This function is only available if the `raw` feature of the crate is enabled. /// /// # Note /// /// Calling this function is safe, but using the raw hash table API may require /// unsafe functions or blocks. /// /// `RawTable` API gives the lowest level of control under the map that can be useful /// for extending the HashMap's API, but may lead to *[undefined behavior]*. /// /// [`HashMap`]: struct.HashMap.html /// [`RawTable`]: crate::raw::RawTable /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::HashMap; /// /// let mut map = HashMap::new(); /// map.extend([("a", 10), ("b", 20), ("c", 30)]); /// assert_eq!(map.len(), 3); /// /// // Let's imagine that we have a value and a hash of the key, but not the key itself. /// // However, if you want to remove the value from the map by hash and value, and you /// // know exactly that the value is unique, then you can create a function like this: /// fn remove_by_hash( /// map: &mut HashMap, /// hash: u64, /// is_match: F, /// ) -> Option<(K, V)> /// where /// F: Fn(&(K, V)) -> bool, /// { /// let raw_table = map.raw_table_mut(); /// match raw_table.find(hash, is_match) { /// Some(bucket) => Some(unsafe { raw_table.remove(bucket).0 }), /// None => None, /// } /// } /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let hash = compute_hash(map.hasher(), "a"); /// assert_eq!(remove_by_hash(&mut map, hash, |(_, v)| *v == 10), Some(("a", 10))); /// assert_eq!(map.get(&"a"), None); /// assert_eq!(map.len(), 2); /// ``` #[cfg(feature = "raw")] #[cfg_attr(feature = "inline-more", inline)] pub fn raw_table_mut(&mut self) -> &mut RawTable<(K, V), A> { &mut self.table } } impl PartialEq for HashMap where K: Eq + Hash, V: PartialEq, S: BuildHasher, A: Allocator, { fn eq(&self, other: &Self) -> bool { if self.len() != other.len() { return false; } self.iter() .all(|(key, value)| other.get(key).map_or(false, |v| *value == *v)) } } impl Eq for HashMap where K: Eq + Hash, V: Eq, S: BuildHasher, A: Allocator, { } impl Debug for HashMap where K: Debug, V: Debug, A: Allocator, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_map().entries(self.iter()).finish() } } impl Default for HashMap where S: Default, A: Default + Allocator, { /// Creates an empty `HashMap`, with the `Default` value for the hasher and allocator. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use std::collections::hash_map::RandomState; /// /// // You can specify all types of HashMap, including hasher and allocator. /// // Created map is empty and don't allocate memory /// let map: HashMap = Default::default(); /// assert_eq!(map.capacity(), 0); /// let map: HashMap = HashMap::default(); /// assert_eq!(map.capacity(), 0); /// ``` #[cfg_attr(feature = "inline-more", inline)] fn default() -> Self { Self::with_hasher_in(Default::default(), Default::default()) } } impl Index<&Q> for HashMap where K: Eq + Hash, Q: Hash + Equivalent, S: BuildHasher, A: Allocator, { type Output = V; /// Returns a reference to the value corresponding to the supplied key. /// /// # Panics /// /// Panics if the key is not present in the `HashMap`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map: HashMap<_, _> = [("a", "One"), ("b", "Two")].into(); /// /// assert_eq!(map[&"a"], "One"); /// assert_eq!(map[&"b"], "Two"); /// ``` #[cfg_attr(feature = "inline-more", inline)] fn index(&self, key: &Q) -> &V { self.get(key).expect("no entry found for key") } } // The default hasher is used to match the std implementation signature #[cfg(feature = "ahash")] impl From<[(K, V); N]> for HashMap where K: Eq + Hash, A: Default + Allocator, { /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map1 = HashMap::from([(1, 2), (3, 4)]); /// let map2: HashMap<_, _> = [(1, 2), (3, 4)].into(); /// assert_eq!(map1, map2); /// ``` fn from(arr: [(K, V); N]) -> Self { arr.into_iter().collect() } } /// An iterator over the entries of a `HashMap` in arbitrary order. /// The iterator element type is `(&'a K, &'a V)`. /// /// This `struct` is created by the [`iter`] method on [`HashMap`]. See its /// documentation for more. /// /// [`iter`]: struct.HashMap.html#method.iter /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map: HashMap<_, _> = [(1, "a"), (2, "b"), (3, "c")].into(); /// /// let mut iter = map.iter(); /// let mut vec = vec![iter.next(), iter.next(), iter.next()]; /// /// // The `Iter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [Some((&1, &"a")), Some((&2, &"b")), Some((&3, &"c"))]); /// /// // It is fused iterator /// assert_eq!(iter.next(), None); /// assert_eq!(iter.next(), None); /// ``` pub struct Iter<'a, K, V> { inner: RawIter<(K, V)>, marker: PhantomData<(&'a K, &'a V)>, } // FIXME(#26925) Remove in favor of `#[derive(Clone)]` impl Clone for Iter<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Iter { inner: self.inner.clone(), marker: PhantomData, } } } impl fmt::Debug for Iter<'_, K, V> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.clone()).finish() } } /// A mutable iterator over the entries of a `HashMap` in arbitrary order. /// The iterator element type is `(&'a K, &'a mut V)`. /// /// This `struct` is created by the [`iter_mut`] method on [`HashMap`]. See its /// documentation for more. /// /// [`iter_mut`]: struct.HashMap.html#method.iter_mut /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<_, _> = [(1, "One".to_owned()), (2, "Two".into())].into(); /// /// let mut iter = map.iter_mut(); /// iter.next().map(|(_, v)| v.push_str(" Mississippi")); /// iter.next().map(|(_, v)| v.push_str(" Mississippi")); /// /// // It is fused iterator /// assert_eq!(iter.next(), None); /// assert_eq!(iter.next(), None); /// /// assert_eq!(map.get(&1).unwrap(), &"One Mississippi".to_owned()); /// assert_eq!(map.get(&2).unwrap(), &"Two Mississippi".to_owned()); /// ``` pub struct IterMut<'a, K, V> { inner: RawIter<(K, V)>, // To ensure invariance with respect to V marker: PhantomData<(&'a K, &'a mut V)>, } // We override the default Send impl which has K: Sync instead of K: Send. Both // are correct, but this one is more general since it allows keys which // implement Send but not Sync. unsafe impl Send for IterMut<'_, K, V> {} impl IterMut<'_, K, V> { /// Returns a iterator of references over the remaining items. #[cfg_attr(feature = "inline-more", inline)] pub(super) fn iter(&self) -> Iter<'_, K, V> { Iter { inner: self.inner.clone(), marker: PhantomData, } } } /// An owning iterator over the entries of a `HashMap` in arbitrary order. /// The iterator element type is `(K, V)`. /// /// This `struct` is created by the [`into_iter`] method on [`HashMap`] /// (provided by the [`IntoIterator`] trait). See its documentation for more. /// The map cannot be used after calling that method. /// /// [`into_iter`]: struct.HashMap.html#method.into_iter /// [`HashMap`]: struct.HashMap.html /// [`IntoIterator`]: https://doc.rust-lang.org/core/iter/trait.IntoIterator.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map: HashMap<_, _> = [(1, "a"), (2, "b"), (3, "c")].into(); /// /// let mut iter = map.into_iter(); /// let mut vec = vec![iter.next(), iter.next(), iter.next()]; /// /// // The `IntoIter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [Some((1, "a")), Some((2, "b")), Some((3, "c"))]); /// /// // It is fused iterator /// assert_eq!(iter.next(), None); /// assert_eq!(iter.next(), None); /// ``` pub struct IntoIter { inner: RawIntoIter<(K, V), A>, } impl IntoIter { /// Returns a iterator of references over the remaining items. #[cfg_attr(feature = "inline-more", inline)] pub(super) fn iter(&self) -> Iter<'_, K, V> { Iter { inner: self.inner.iter(), marker: PhantomData, } } } /// An owning iterator over the keys of a `HashMap` in arbitrary order. /// The iterator element type is `K`. /// /// This `struct` is created by the [`into_keys`] method on [`HashMap`]. /// See its documentation for more. /// The map cannot be used after calling that method. /// /// [`into_keys`]: struct.HashMap.html#method.into_keys /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map: HashMap<_, _> = [(1, "a"), (2, "b"), (3, "c")].into(); /// /// let mut keys = map.into_keys(); /// let mut vec = vec![keys.next(), keys.next(), keys.next()]; /// /// // The `IntoKeys` iterator produces keys in arbitrary order, so the /// // keys must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [Some(1), Some(2), Some(3)]); /// /// // It is fused iterator /// assert_eq!(keys.next(), None); /// assert_eq!(keys.next(), None); /// ``` pub struct IntoKeys { inner: IntoIter, } impl Iterator for IntoKeys { type Item = K; #[inline] fn next(&mut self) -> Option { self.inner.next().map(|(k, _)| k) } #[inline] fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } #[inline] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, |acc, (k, _)| f(acc, k)) } } impl ExactSizeIterator for IntoKeys { #[inline] fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for IntoKeys {} impl fmt::Debug for IntoKeys { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list() .entries(self.inner.iter().map(|(k, _)| k)) .finish() } } /// An owning iterator over the values of a `HashMap` in arbitrary order. /// The iterator element type is `V`. /// /// This `struct` is created by the [`into_values`] method on [`HashMap`]. /// See its documentation for more. The map cannot be used after calling that method. /// /// [`into_values`]: struct.HashMap.html#method.into_values /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map: HashMap<_, _> = [(1, "a"), (2, "b"), (3, "c")].into(); /// /// let mut values = map.into_values(); /// let mut vec = vec![values.next(), values.next(), values.next()]; /// /// // The `IntoValues` iterator produces values in arbitrary order, so /// // the values must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [Some("a"), Some("b"), Some("c")]); /// /// // It is fused iterator /// assert_eq!(values.next(), None); /// assert_eq!(values.next(), None); /// ``` pub struct IntoValues { inner: IntoIter, } impl Iterator for IntoValues { type Item = V; #[inline] fn next(&mut self) -> Option { self.inner.next().map(|(_, v)| v) } #[inline] fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } #[inline] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, |acc, (_, v)| f(acc, v)) } } impl ExactSizeIterator for IntoValues { #[inline] fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for IntoValues {} impl fmt::Debug for IntoValues { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list() .entries(self.inner.iter().map(|(_, v)| v)) .finish() } } /// An iterator over the keys of a `HashMap` in arbitrary order. /// The iterator element type is `&'a K`. /// /// This `struct` is created by the [`keys`] method on [`HashMap`]. See its /// documentation for more. /// /// [`keys`]: struct.HashMap.html#method.keys /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map: HashMap<_, _> = [(1, "a"), (2, "b"), (3, "c")].into(); /// /// let mut keys = map.keys(); /// let mut vec = vec![keys.next(), keys.next(), keys.next()]; /// /// // The `Keys` iterator produces keys in arbitrary order, so the /// // keys must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [Some(&1), Some(&2), Some(&3)]); /// /// // It is fused iterator /// assert_eq!(keys.next(), None); /// assert_eq!(keys.next(), None); /// ``` pub struct Keys<'a, K, V> { inner: Iter<'a, K, V>, } // FIXME(#26925) Remove in favor of `#[derive(Clone)]` impl Clone for Keys<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Keys { inner: self.inner.clone(), } } } impl fmt::Debug for Keys<'_, K, V> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.clone()).finish() } } /// An iterator over the values of a `HashMap` in arbitrary order. /// The iterator element type is `&'a V`. /// /// This `struct` is created by the [`values`] method on [`HashMap`]. See its /// documentation for more. /// /// [`values`]: struct.HashMap.html#method.values /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map: HashMap<_, _> = [(1, "a"), (2, "b"), (3, "c")].into(); /// /// let mut values = map.values(); /// let mut vec = vec![values.next(), values.next(), values.next()]; /// /// // The `Values` iterator produces values in arbitrary order, so the /// // values must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [Some(&"a"), Some(&"b"), Some(&"c")]); /// /// // It is fused iterator /// assert_eq!(values.next(), None); /// assert_eq!(values.next(), None); /// ``` pub struct Values<'a, K, V> { inner: Iter<'a, K, V>, } // FIXME(#26925) Remove in favor of `#[derive(Clone)]` impl Clone for Values<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Values { inner: self.inner.clone(), } } } impl fmt::Debug for Values<'_, K, V> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.clone()).finish() } } /// A draining iterator over the entries of a `HashMap` in arbitrary /// order. The iterator element type is `(K, V)`. /// /// This `struct` is created by the [`drain`] method on [`HashMap`]. See its /// documentation for more. /// /// [`drain`]: struct.HashMap.html#method.drain /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<_, _> = [(1, "a"), (2, "b"), (3, "c")].into(); /// /// let mut drain_iter = map.drain(); /// let mut vec = vec![drain_iter.next(), drain_iter.next(), drain_iter.next()]; /// /// // The `Drain` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [Some((1, "a")), Some((2, "b")), Some((3, "c"))]); /// /// // It is fused iterator /// assert_eq!(drain_iter.next(), None); /// assert_eq!(drain_iter.next(), None); /// ``` pub struct Drain<'a, K, V, A: Allocator = Global> { inner: RawDrain<'a, (K, V), A>, } impl Drain<'_, K, V, A> { /// Returns a iterator of references over the remaining items. #[cfg_attr(feature = "inline-more", inline)] pub(super) fn iter(&self) -> Iter<'_, K, V> { Iter { inner: self.inner.iter(), marker: PhantomData, } } } /// A draining iterator over entries of a `HashMap` which don't satisfy the predicate /// `f(&k, &mut v)` in arbitrary order. The iterator element type is `(K, V)`. /// /// This `struct` is created by the [`extract_if`] method on [`HashMap`]. See its /// documentation for more. /// /// [`extract_if`]: struct.HashMap.html#method.extract_if /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = [(1, "a"), (2, "b"), (3, "c")].into(); /// /// let mut extract_if = map.extract_if(|k, _v| k % 2 != 0); /// let mut vec = vec![extract_if.next(), extract_if.next()]; /// /// // The `ExtractIf` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [Some((1, "a")),Some((3, "c"))]); /// /// // It is fused iterator /// assert_eq!(extract_if.next(), None); /// assert_eq!(extract_if.next(), None); /// drop(extract_if); /// /// assert_eq!(map.len(), 1); /// ``` #[must_use = "Iterators are lazy unless consumed"] pub struct ExtractIf<'a, K, V, F, A: Allocator = Global> where F: FnMut(&K, &mut V) -> bool, { f: F, inner: RawExtractIf<'a, (K, V), A>, } impl Iterator for ExtractIf<'_, K, V, F, A> where F: FnMut(&K, &mut V) -> bool, A: Allocator, { type Item = (K, V); #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option { self.inner.next(|&mut (ref k, ref mut v)| (self.f)(k, v)) } #[inline] fn size_hint(&self) -> (usize, Option) { (0, self.inner.iter.size_hint().1) } } impl FusedIterator for ExtractIf<'_, K, V, F> where F: FnMut(&K, &mut V) -> bool {} /// A mutable iterator over the values of a `HashMap` in arbitrary order. /// The iterator element type is `&'a mut V`. /// /// This `struct` is created by the [`values_mut`] method on [`HashMap`]. See its /// documentation for more. /// /// [`values_mut`]: struct.HashMap.html#method.values_mut /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<_, _> = [(1, "One".to_owned()), (2, "Two".into())].into(); /// /// let mut values = map.values_mut(); /// values.next().map(|v| v.push_str(" Mississippi")); /// values.next().map(|v| v.push_str(" Mississippi")); /// /// // It is fused iterator /// assert_eq!(values.next(), None); /// assert_eq!(values.next(), None); /// /// assert_eq!(map.get(&1).unwrap(), &"One Mississippi".to_owned()); /// assert_eq!(map.get(&2).unwrap(), &"Two Mississippi".to_owned()); /// ``` pub struct ValuesMut<'a, K, V> { inner: IterMut<'a, K, V>, } /// A builder for computing where in a [`HashMap`] a key-value pair would be stored. /// /// See the [`HashMap::raw_entry_mut`] docs for usage examples. /// /// [`HashMap::raw_entry_mut`]: struct.HashMap.html#method.raw_entry_mut /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{RawEntryBuilderMut, RawEntryMut::Vacant, RawEntryMut::Occupied}; /// use hashbrown::HashMap; /// use core::hash::{BuildHasher, Hash}; /// /// let mut map = HashMap::new(); /// map.extend([(1, 11), (2, 12), (3, 13), (4, 14), (5, 15), (6, 16)]); /// assert_eq!(map.len(), 6); /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let builder: RawEntryBuilderMut<_, _, _> = map.raw_entry_mut(); /// /// // Existing key /// match builder.from_key(&6) { /// Vacant(_) => unreachable!(), /// Occupied(view) => assert_eq!(view.get(), &16), /// } /// /// for key in 0..12 { /// let hash = compute_hash(map.hasher(), &key); /// let value = map.get(&key).cloned(); /// let key_value = value.as_ref().map(|v| (&key, v)); /// /// println!("Key: {} and value: {:?}", key, value); /// /// match map.raw_entry_mut().from_key(&key) { /// Occupied(mut o) => assert_eq!(Some(o.get_key_value()), key_value), /// Vacant(_) => assert_eq!(value, None), /// } /// match map.raw_entry_mut().from_key_hashed_nocheck(hash, &key) { /// Occupied(mut o) => assert_eq!(Some(o.get_key_value()), key_value), /// Vacant(_) => assert_eq!(value, None), /// } /// match map.raw_entry_mut().from_hash(hash, |q| *q == key) { /// Occupied(mut o) => assert_eq!(Some(o.get_key_value()), key_value), /// Vacant(_) => assert_eq!(value, None), /// } /// } /// /// assert_eq!(map.len(), 6); /// ``` pub struct RawEntryBuilderMut<'a, K, V, S, A: Allocator = Global> { map: &'a mut HashMap, } /// A view into a single entry in a map, which may either be vacant or occupied. /// /// This is a lower-level version of [`Entry`]. /// /// This `enum` is constructed through the [`raw_entry_mut`] method on [`HashMap`], /// then calling one of the methods of that [`RawEntryBuilderMut`]. /// /// [`HashMap`]: struct.HashMap.html /// [`Entry`]: enum.Entry.html /// [`raw_entry_mut`]: struct.HashMap.html#method.raw_entry_mut /// [`RawEntryBuilderMut`]: struct.RawEntryBuilderMut.html /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::hash_map::{HashMap, RawEntryMut, RawOccupiedEntryMut}; /// /// let mut map = HashMap::new(); /// map.extend([('a', 1), ('b', 2), ('c', 3)]); /// assert_eq!(map.len(), 3); /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// // Existing key (insert) /// let raw: RawEntryMut<_, _, _> = map.raw_entry_mut().from_key(&'a'); /// let _raw_o: RawOccupiedEntryMut<_, _, _> = raw.insert('a', 10); /// assert_eq!(map.len(), 3); /// /// // Nonexistent key (insert) /// map.raw_entry_mut().from_key(&'d').insert('d', 40); /// assert_eq!(map.len(), 4); /// /// // Existing key (or_insert) /// let hash = compute_hash(map.hasher(), &'b'); /// let kv = map /// .raw_entry_mut() /// .from_key_hashed_nocheck(hash, &'b') /// .or_insert('b', 20); /// assert_eq!(kv, (&mut 'b', &mut 2)); /// *kv.1 = 20; /// assert_eq!(map.len(), 4); /// /// // Nonexistent key (or_insert) /// let hash = compute_hash(map.hasher(), &'e'); /// let kv = map /// .raw_entry_mut() /// .from_key_hashed_nocheck(hash, &'e') /// .or_insert('e', 50); /// assert_eq!(kv, (&mut 'e', &mut 50)); /// assert_eq!(map.len(), 5); /// /// // Existing key (or_insert_with) /// let hash = compute_hash(map.hasher(), &'c'); /// let kv = map /// .raw_entry_mut() /// .from_hash(hash, |q| q == &'c') /// .or_insert_with(|| ('c', 30)); /// assert_eq!(kv, (&mut 'c', &mut 3)); /// *kv.1 = 30; /// assert_eq!(map.len(), 5); /// /// // Nonexistent key (or_insert_with) /// let hash = compute_hash(map.hasher(), &'f'); /// let kv = map /// .raw_entry_mut() /// .from_hash(hash, |q| q == &'f') /// .or_insert_with(|| ('f', 60)); /// assert_eq!(kv, (&mut 'f', &mut 60)); /// assert_eq!(map.len(), 6); /// /// println!("Our HashMap: {:?}", map); /// /// let mut vec: Vec<_> = map.iter().map(|(&k, &v)| (k, v)).collect(); /// // The `Iter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [('a', 10), ('b', 20), ('c', 30), ('d', 40), ('e', 50), ('f', 60)]); /// ``` pub enum RawEntryMut<'a, K, V, S, A: Allocator = Global> { /// An occupied entry. /// /// # Examples /// /// ``` /// use hashbrown::{hash_map::RawEntryMut, HashMap}; /// let mut map: HashMap<_, _> = [("a", 100), ("b", 200)].into(); /// /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => unreachable!(), /// RawEntryMut::Occupied(_) => { } /// } /// ``` Occupied(RawOccupiedEntryMut<'a, K, V, S, A>), /// A vacant entry. /// /// # Examples /// /// ``` /// use hashbrown::{hash_map::RawEntryMut, HashMap}; /// let mut map: HashMap<&str, i32> = HashMap::new(); /// /// match map.raw_entry_mut().from_key("a") { /// RawEntryMut::Occupied(_) => unreachable!(), /// RawEntryMut::Vacant(_) => { } /// } /// ``` Vacant(RawVacantEntryMut<'a, K, V, S, A>), } /// A view into an occupied entry in a `HashMap`. /// It is part of the [`RawEntryMut`] enum. /// /// [`RawEntryMut`]: enum.RawEntryMut.html /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::hash_map::{HashMap, RawEntryMut, RawOccupiedEntryMut}; /// /// let mut map = HashMap::new(); /// map.extend([("a", 10), ("b", 20), ("c", 30)]); /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let _raw_o: RawOccupiedEntryMut<_, _, _> = map.raw_entry_mut().from_key(&"a").insert("a", 100); /// assert_eq!(map.len(), 3); /// /// // Existing key (insert and update) /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => unreachable!(), /// RawEntryMut::Occupied(mut view) => { /// assert_eq!(view.get(), &100); /// let v = view.get_mut(); /// let new_v = (*v) * 10; /// *v = new_v; /// assert_eq!(view.insert(1111), 1000); /// } /// } /// /// assert_eq!(map[&"a"], 1111); /// assert_eq!(map.len(), 3); /// /// // Existing key (take) /// let hash = compute_hash(map.hasher(), &"c"); /// match map.raw_entry_mut().from_key_hashed_nocheck(hash, &"c") { /// RawEntryMut::Vacant(_) => unreachable!(), /// RawEntryMut::Occupied(view) => { /// assert_eq!(view.remove_entry(), ("c", 30)); /// } /// } /// assert_eq!(map.raw_entry().from_key(&"c"), None); /// assert_eq!(map.len(), 2); /// /// let hash = compute_hash(map.hasher(), &"b"); /// match map.raw_entry_mut().from_hash(hash, |q| *q == "b") { /// RawEntryMut::Vacant(_) => unreachable!(), /// RawEntryMut::Occupied(view) => { /// assert_eq!(view.remove_entry(), ("b", 20)); /// } /// } /// assert_eq!(map.get(&"b"), None); /// assert_eq!(map.len(), 1); /// ``` pub struct RawOccupiedEntryMut<'a, K, V, S, A: Allocator = Global> { elem: Bucket<(K, V)>, table: &'a mut RawTable<(K, V), A>, hash_builder: &'a S, } unsafe impl Send for RawOccupiedEntryMut<'_, K, V, S, A> where K: Send, V: Send, S: Send, A: Send + Allocator, { } unsafe impl Sync for RawOccupiedEntryMut<'_, K, V, S, A> where K: Sync, V: Sync, S: Sync, A: Sync + Allocator, { } /// A view into a vacant entry in a `HashMap`. /// It is part of the [`RawEntryMut`] enum. /// /// [`RawEntryMut`]: enum.RawEntryMut.html /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::hash_map::{HashMap, RawEntryMut, RawVacantEntryMut}; /// /// let mut map = HashMap::<&str, i32>::new(); /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let raw_v: RawVacantEntryMut<_, _, _> = match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(view) => view, /// RawEntryMut::Occupied(_) => unreachable!(), /// }; /// raw_v.insert("a", 10); /// assert!(map[&"a"] == 10 && map.len() == 1); /// /// // Nonexistent key (insert and update) /// let hash = compute_hash(map.hasher(), &"b"); /// match map.raw_entry_mut().from_key_hashed_nocheck(hash, &"b") { /// RawEntryMut::Occupied(_) => unreachable!(), /// RawEntryMut::Vacant(view) => { /// let (k, value) = view.insert("b", 2); /// assert_eq!((*k, *value), ("b", 2)); /// *value = 20; /// } /// } /// assert!(map[&"b"] == 20 && map.len() == 2); /// /// let hash = compute_hash(map.hasher(), &"c"); /// match map.raw_entry_mut().from_hash(hash, |q| *q == "c") { /// RawEntryMut::Occupied(_) => unreachable!(), /// RawEntryMut::Vacant(view) => { /// assert_eq!(view.insert("c", 30), (&mut "c", &mut 30)); /// } /// } /// assert!(map[&"c"] == 30 && map.len() == 3); /// ``` pub struct RawVacantEntryMut<'a, K, V, S, A: Allocator = Global> { table: &'a mut RawTable<(K, V), A>, hash_builder: &'a S, } /// A builder for computing where in a [`HashMap`] a key-value pair would be stored. /// /// See the [`HashMap::raw_entry`] docs for usage examples. /// /// [`HashMap::raw_entry`]: struct.HashMap.html#method.raw_entry /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryBuilder}; /// use core::hash::{BuildHasher, Hash}; /// /// let mut map = HashMap::new(); /// map.extend([(1, 10), (2, 20), (3, 30)]); /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// for k in 0..6 { /// let hash = compute_hash(map.hasher(), &k); /// let v = map.get(&k).cloned(); /// let kv = v.as_ref().map(|v| (&k, v)); /// /// println!("Key: {} and value: {:?}", k, v); /// let builder: RawEntryBuilder<_, _, _> = map.raw_entry(); /// assert_eq!(builder.from_key(&k), kv); /// assert_eq!(map.raw_entry().from_hash(hash, |q| *q == k), kv); /// assert_eq!(map.raw_entry().from_key_hashed_nocheck(hash, &k), kv); /// } /// ``` pub struct RawEntryBuilder<'a, K, V, S, A: Allocator = Global> { map: &'a HashMap, } impl<'a, K, V, S, A: Allocator> RawEntryBuilderMut<'a, K, V, S, A> { /// Creates a `RawEntryMut` from the given key. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// let key = "a"; /// let entry: RawEntryMut<&str, u32, _> = map.raw_entry_mut().from_key(&key); /// entry.insert(key, 100); /// assert_eq!(map[&"a"], 100); /// ``` #[cfg_attr(feature = "inline-more", inline)] #[allow(clippy::wrong_self_convention)] pub fn from_key(self, k: &Q) -> RawEntryMut<'a, K, V, S, A> where S: BuildHasher, Q: Hash + Equivalent, { let hash = make_hash::(&self.map.hash_builder, k); self.from_key_hashed_nocheck(hash, k) } /// Creates a `RawEntryMut` from the given key and its hash. /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// let key = "a"; /// let hash = compute_hash(map.hasher(), &key); /// let entry: RawEntryMut<&str, u32, _> = map.raw_entry_mut().from_key_hashed_nocheck(hash, &key); /// entry.insert(key, 100); /// assert_eq!(map[&"a"], 100); /// ``` #[inline] #[allow(clippy::wrong_self_convention)] pub fn from_key_hashed_nocheck(self, hash: u64, k: &Q) -> RawEntryMut<'a, K, V, S, A> where Q: Equivalent, { self.from_hash(hash, equivalent(k)) } } impl<'a, K, V, S, A: Allocator> RawEntryBuilderMut<'a, K, V, S, A> { /// Creates a `RawEntryMut` from the given hash and matching function. /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// let key = "a"; /// let hash = compute_hash(map.hasher(), &key); /// let entry: RawEntryMut<&str, u32, _> = map.raw_entry_mut().from_hash(hash, |k| k == &key); /// entry.insert(key, 100); /// assert_eq!(map[&"a"], 100); /// ``` #[cfg_attr(feature = "inline-more", inline)] #[allow(clippy::wrong_self_convention)] pub fn from_hash(self, hash: u64, is_match: F) -> RawEntryMut<'a, K, V, S, A> where for<'b> F: FnMut(&'b K) -> bool, { self.search(hash, is_match) } #[cfg_attr(feature = "inline-more", inline)] fn search(self, hash: u64, mut is_match: F) -> RawEntryMut<'a, K, V, S, A> where for<'b> F: FnMut(&'b K) -> bool, { match self.map.table.find(hash, |(k, _)| is_match(k)) { Some(elem) => RawEntryMut::Occupied(RawOccupiedEntryMut { elem, table: &mut self.map.table, hash_builder: &self.map.hash_builder, }), None => RawEntryMut::Vacant(RawVacantEntryMut { table: &mut self.map.table, hash_builder: &self.map.hash_builder, }), } } } impl<'a, K, V, S, A: Allocator> RawEntryBuilder<'a, K, V, S, A> { /// Access an immutable entry by key. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// let key = "a"; /// assert_eq!(map.raw_entry().from_key(&key), Some((&"a", &100))); /// ``` #[cfg_attr(feature = "inline-more", inline)] #[allow(clippy::wrong_self_convention)] pub fn from_key(self, k: &Q) -> Option<(&'a K, &'a V)> where S: BuildHasher, Q: Hash + Equivalent, { let hash = make_hash::(&self.map.hash_builder, k); self.from_key_hashed_nocheck(hash, k) } /// Access an immutable entry by a key and its hash. /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::HashMap; /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// let key = "a"; /// let hash = compute_hash(map.hasher(), &key); /// assert_eq!(map.raw_entry().from_key_hashed_nocheck(hash, &key), Some((&"a", &100))); /// ``` #[cfg_attr(feature = "inline-more", inline)] #[allow(clippy::wrong_self_convention)] pub fn from_key_hashed_nocheck(self, hash: u64, k: &Q) -> Option<(&'a K, &'a V)> where Q: Equivalent, { self.from_hash(hash, equivalent(k)) } #[cfg_attr(feature = "inline-more", inline)] fn search(self, hash: u64, mut is_match: F) -> Option<(&'a K, &'a V)> where F: FnMut(&K) -> bool, { match self.map.table.get(hash, |(k, _)| is_match(k)) { Some((key, value)) => Some((key, value)), None => None, } } /// Access an immutable entry by hash and matching function. /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::HashMap; /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// let key = "a"; /// let hash = compute_hash(map.hasher(), &key); /// assert_eq!(map.raw_entry().from_hash(hash, |k| k == &key), Some((&"a", &100))); /// ``` #[cfg_attr(feature = "inline-more", inline)] #[allow(clippy::wrong_self_convention)] pub fn from_hash(self, hash: u64, is_match: F) -> Option<(&'a K, &'a V)> where F: FnMut(&K) -> bool, { self.search(hash, is_match) } } impl<'a, K, V, S, A: Allocator> RawEntryMut<'a, K, V, S, A> { /// Sets the value of the entry, and returns a RawOccupiedEntryMut. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// let entry = map.raw_entry_mut().from_key("horseyland").insert("horseyland", 37); /// /// assert_eq!(entry.remove_entry(), ("horseyland", 37)); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(self, key: K, value: V) -> RawOccupiedEntryMut<'a, K, V, S, A> where K: Hash, S: BuildHasher, { match self { RawEntryMut::Occupied(mut entry) => { entry.insert(value); entry } RawEntryMut::Vacant(entry) => entry.insert_entry(key, value), } } /// Ensures a value is in the entry by inserting the default if empty, and returns /// mutable references to the key and value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// map.raw_entry_mut().from_key("poneyland").or_insert("poneyland", 3); /// assert_eq!(map["poneyland"], 3); /// /// *map.raw_entry_mut().from_key("poneyland").or_insert("poneyland", 10).1 *= 2; /// assert_eq!(map["poneyland"], 6); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert(self, default_key: K, default_val: V) -> (&'a mut K, &'a mut V) where K: Hash, S: BuildHasher, { match self { RawEntryMut::Occupied(entry) => entry.into_key_value(), RawEntryMut::Vacant(entry) => entry.insert(default_key, default_val), } } /// Ensures a value is in the entry by inserting the result of the default function if empty, /// and returns mutable references to the key and value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, String> = HashMap::new(); /// /// map.raw_entry_mut().from_key("poneyland").or_insert_with(|| { /// ("poneyland", "hoho".to_string()) /// }); /// /// assert_eq!(map["poneyland"], "hoho".to_string()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert_with(self, default: F) -> (&'a mut K, &'a mut V) where F: FnOnce() -> (K, V), K: Hash, S: BuildHasher, { match self { RawEntryMut::Occupied(entry) => entry.into_key_value(), RawEntryMut::Vacant(entry) => { let (k, v) = default(); entry.insert(k, v) } } } /// Provides in-place mutable access to an occupied entry before any /// potential inserts into the map. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// map.raw_entry_mut() /// .from_key("poneyland") /// .and_modify(|_k, v| { *v += 1 }) /// .or_insert("poneyland", 42); /// assert_eq!(map["poneyland"], 42); /// /// map.raw_entry_mut() /// .from_key("poneyland") /// .and_modify(|_k, v| { *v += 1 }) /// .or_insert("poneyland", 0); /// assert_eq!(map["poneyland"], 43); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn and_modify(self, f: F) -> Self where F: FnOnce(&mut K, &mut V), { match self { RawEntryMut::Occupied(mut entry) => { { let (k, v) = entry.get_key_value_mut(); f(k, v); } RawEntryMut::Occupied(entry) } RawEntryMut::Vacant(entry) => RawEntryMut::Vacant(entry), } } /// Provides shared access to the key and owned access to the value of /// an occupied entry and allows to replace or remove it based on the /// value of the returned option. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RawEntryMut; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// let entry = map /// .raw_entry_mut() /// .from_key("poneyland") /// .and_replace_entry_with(|_k, _v| panic!()); /// /// match entry { /// RawEntryMut::Vacant(_) => {}, /// RawEntryMut::Occupied(_) => panic!(), /// } /// /// map.insert("poneyland", 42); /// /// let entry = map /// .raw_entry_mut() /// .from_key("poneyland") /// .and_replace_entry_with(|k, v| { /// assert_eq!(k, &"poneyland"); /// assert_eq!(v, 42); /// Some(v + 1) /// }); /// /// match entry { /// RawEntryMut::Occupied(e) => { /// assert_eq!(e.key(), &"poneyland"); /// assert_eq!(e.get(), &43); /// }, /// RawEntryMut::Vacant(_) => panic!(), /// } /// /// assert_eq!(map["poneyland"], 43); /// /// let entry = map /// .raw_entry_mut() /// .from_key("poneyland") /// .and_replace_entry_with(|_k, _v| None); /// /// match entry { /// RawEntryMut::Vacant(_) => {}, /// RawEntryMut::Occupied(_) => panic!(), /// } /// /// assert!(!map.contains_key("poneyland")); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn and_replace_entry_with(self, f: F) -> Self where F: FnOnce(&K, V) -> Option, { match self { RawEntryMut::Occupied(entry) => entry.replace_entry_with(f), RawEntryMut::Vacant(_) => self, } } } impl<'a, K, V, S, A: Allocator> RawOccupiedEntryMut<'a, K, V, S, A> { /// Gets a reference to the key in the entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => assert_eq!(o.key(), &"a") /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &K { unsafe { &self.elem.as_ref().0 } } /// Gets a mutable reference to the key in the entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// use std::rc::Rc; /// /// let key_one = Rc::new("a"); /// let key_two = Rc::new("a"); /// /// let mut map: HashMap, u32> = HashMap::new(); /// map.insert(key_one.clone(), 10); /// /// assert_eq!(map[&key_one], 10); /// assert!(Rc::strong_count(&key_one) == 2 && Rc::strong_count(&key_two) == 1); /// /// match map.raw_entry_mut().from_key(&key_one) { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(mut o) => { /// *o.key_mut() = key_two.clone(); /// } /// } /// assert_eq!(map[&key_two], 10); /// assert!(Rc::strong_count(&key_one) == 1 && Rc::strong_count(&key_two) == 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key_mut(&mut self) -> &mut K { unsafe { &mut self.elem.as_mut().0 } } /// Converts the entry into a mutable reference to the key in the entry /// with a lifetime bound to the map itself. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// use std::rc::Rc; /// /// let key_one = Rc::new("a"); /// let key_two = Rc::new("a"); /// /// let mut map: HashMap, u32> = HashMap::new(); /// map.insert(key_one.clone(), 10); /// /// assert_eq!(map[&key_one], 10); /// assert!(Rc::strong_count(&key_one) == 2 && Rc::strong_count(&key_two) == 1); /// /// let inside_key: &mut Rc<&str>; /// /// match map.raw_entry_mut().from_key(&key_one) { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => inside_key = o.into_key(), /// } /// *inside_key = key_two.clone(); /// /// assert_eq!(map[&key_two], 10); /// assert!(Rc::strong_count(&key_one) == 1 && Rc::strong_count(&key_two) == 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_key(self) -> &'a mut K { unsafe { &mut self.elem.as_mut().0 } } /// Gets a reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => assert_eq!(o.get(), &100), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get(&self) -> &V { unsafe { &self.elem.as_ref().1 } } /// Converts the OccupiedEntry into a mutable reference to the value in the entry /// with a lifetime bound to the map itself. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// let value: &mut u32; /// /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => value = o.into_mut(), /// } /// *value += 900; /// /// assert_eq!(map[&"a"], 1000); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_mut(self) -> &'a mut V { unsafe { &mut self.elem.as_mut().1 } } /// Gets a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(mut o) => *o.get_mut() += 900, /// } /// /// assert_eq!(map[&"a"], 1000); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get_mut(&mut self) -> &mut V { unsafe { &mut self.elem.as_mut().1 } } /// Gets a reference to the key and value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => assert_eq!(o.get_key_value(), (&"a", &100)), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get_key_value(&self) -> (&K, &V) { unsafe { let (key, value) = self.elem.as_ref(); (key, value) } } /// Gets a mutable reference to the key and value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// use std::rc::Rc; /// /// let key_one = Rc::new("a"); /// let key_two = Rc::new("a"); /// /// let mut map: HashMap, u32> = HashMap::new(); /// map.insert(key_one.clone(), 10); /// /// assert_eq!(map[&key_one], 10); /// assert!(Rc::strong_count(&key_one) == 2 && Rc::strong_count(&key_two) == 1); /// /// match map.raw_entry_mut().from_key(&key_one) { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(mut o) => { /// let (inside_key, inside_value) = o.get_key_value_mut(); /// *inside_key = key_two.clone(); /// *inside_value = 100; /// } /// } /// assert_eq!(map[&key_two], 100); /// assert!(Rc::strong_count(&key_one) == 1 && Rc::strong_count(&key_two) == 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get_key_value_mut(&mut self) -> (&mut K, &mut V) { unsafe { let &mut (ref mut key, ref mut value) = self.elem.as_mut(); (key, value) } } /// Converts the OccupiedEntry into a mutable reference to the key and value in the entry /// with a lifetime bound to the map itself. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// use std::rc::Rc; /// /// let key_one = Rc::new("a"); /// let key_two = Rc::new("a"); /// /// let mut map: HashMap, u32> = HashMap::new(); /// map.insert(key_one.clone(), 10); /// /// assert_eq!(map[&key_one], 10); /// assert!(Rc::strong_count(&key_one) == 2 && Rc::strong_count(&key_two) == 1); /// /// let inside_key: &mut Rc<&str>; /// let inside_value: &mut u32; /// match map.raw_entry_mut().from_key(&key_one) { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => { /// let tuple = o.into_key_value(); /// inside_key = tuple.0; /// inside_value = tuple.1; /// } /// } /// *inside_key = key_two.clone(); /// *inside_value = 100; /// assert_eq!(map[&key_two], 100); /// assert!(Rc::strong_count(&key_one) == 1 && Rc::strong_count(&key_two) == 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_key_value(self) -> (&'a mut K, &'a mut V) { unsafe { let &mut (ref mut key, ref mut value) = self.elem.as_mut(); (key, value) } } /// Sets the value of the entry, and returns the entry's old value. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(mut o) => assert_eq!(o.insert(1000), 100), /// } /// /// assert_eq!(map[&"a"], 1000); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(&mut self, value: V) -> V { mem::replace(self.get_mut(), value) } /// Sets the value of the entry, and returns the entry's old value. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// use std::rc::Rc; /// /// let key_one = Rc::new("a"); /// let key_two = Rc::new("a"); /// /// let mut map: HashMap, u32> = HashMap::new(); /// map.insert(key_one.clone(), 10); /// /// assert_eq!(map[&key_one], 10); /// assert!(Rc::strong_count(&key_one) == 2 && Rc::strong_count(&key_two) == 1); /// /// match map.raw_entry_mut().from_key(&key_one) { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(mut o) => { /// let old_key = o.insert_key(key_two.clone()); /// assert!(Rc::ptr_eq(&old_key, &key_one)); /// } /// } /// assert_eq!(map[&key_two], 10); /// assert!(Rc::strong_count(&key_one) == 1 && Rc::strong_count(&key_two) == 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert_key(&mut self, key: K) -> K { mem::replace(self.key_mut(), key) } /// Takes the value out of the entry, and returns it. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => assert_eq!(o.remove(), 100), /// } /// assert_eq!(map.get(&"a"), None); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove(self) -> V { self.remove_entry().1 } /// Take the ownership of the key and value from the map. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => assert_eq!(o.remove_entry(), ("a", 100)), /// } /// assert_eq!(map.get(&"a"), None); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove_entry(self) -> (K, V) { unsafe { self.table.remove(self.elem).0 } } /// Provides shared access to the key and owned access to the value of /// the entry and allows to replace or remove it based on the /// value of the returned option. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// let raw_entry = match map.raw_entry_mut().from_key(&"a") { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => o.replace_entry_with(|k, v| { /// assert_eq!(k, &"a"); /// assert_eq!(v, 100); /// Some(v + 900) /// }), /// }; /// let raw_entry = match raw_entry { /// RawEntryMut::Vacant(_) => panic!(), /// RawEntryMut::Occupied(o) => o.replace_entry_with(|k, v| { /// assert_eq!(k, &"a"); /// assert_eq!(v, 1000); /// None /// }), /// }; /// match raw_entry { /// RawEntryMut::Vacant(_) => { }, /// RawEntryMut::Occupied(_) => panic!(), /// }; /// assert_eq!(map.get(&"a"), None); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace_entry_with(self, f: F) -> RawEntryMut<'a, K, V, S, A> where F: FnOnce(&K, V) -> Option, { unsafe { let still_occupied = self .table .replace_bucket_with(self.elem.clone(), |(key, value)| { f(&key, value).map(|new_value| (key, new_value)) }); if still_occupied { RawEntryMut::Occupied(self) } else { RawEntryMut::Vacant(RawVacantEntryMut { table: self.table, hash_builder: self.hash_builder, }) } } } } impl<'a, K, V, S, A: Allocator> RawVacantEntryMut<'a, K, V, S, A> { /// Sets the value of the entry with the VacantEntry's key, /// and returns a mutable reference to it. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// /// match map.raw_entry_mut().from_key(&"c") { /// RawEntryMut::Occupied(_) => panic!(), /// RawEntryMut::Vacant(v) => assert_eq!(v.insert("c", 300), (&mut "c", &mut 300)), /// } /// /// assert_eq!(map[&"c"], 300); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(self, key: K, value: V) -> (&'a mut K, &'a mut V) where K: Hash, S: BuildHasher, { let hash = make_hash::(self.hash_builder, &key); self.insert_hashed_nocheck(hash, key, value) } /// Sets the value of the entry with the VacantEntry's key, /// and returns a mutable reference to it. /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// fn compute_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let mut map: HashMap<&str, u32> = [("a", 100), ("b", 200)].into(); /// let key = "c"; /// let hash = compute_hash(map.hasher(), &key); /// /// match map.raw_entry_mut().from_key_hashed_nocheck(hash, &key) { /// RawEntryMut::Occupied(_) => panic!(), /// RawEntryMut::Vacant(v) => assert_eq!( /// v.insert_hashed_nocheck(hash, key, 300), /// (&mut "c", &mut 300) /// ), /// } /// /// assert_eq!(map[&"c"], 300); /// ``` #[cfg_attr(feature = "inline-more", inline)] #[allow(clippy::shadow_unrelated)] pub fn insert_hashed_nocheck(self, hash: u64, key: K, value: V) -> (&'a mut K, &'a mut V) where K: Hash, S: BuildHasher, { let &mut (ref mut k, ref mut v) = self.table.insert_entry( hash, (key, value), make_hasher::<_, V, S>(self.hash_builder), ); (k, v) } /// Set the value of an entry with a custom hasher function. /// /// # Examples /// /// ``` /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::hash_map::{HashMap, RawEntryMut}; /// /// fn make_hasher(hash_builder: &S) -> impl Fn(&K) -> u64 + '_ /// where /// K: Hash + ?Sized, /// S: BuildHasher, /// { /// move |key: &K| { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// } /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// let key = "a"; /// let hash_builder = map.hasher().clone(); /// let hash = make_hasher(&hash_builder)(&key); /// /// match map.raw_entry_mut().from_hash(hash, |q| q == &key) { /// RawEntryMut::Occupied(_) => panic!(), /// RawEntryMut::Vacant(v) => assert_eq!( /// v.insert_with_hasher(hash, key, 100, make_hasher(&hash_builder)), /// (&mut "a", &mut 100) /// ), /// } /// map.extend([("b", 200), ("c", 300), ("d", 400), ("e", 500), ("f", 600)]); /// assert_eq!(map[&"a"], 100); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert_with_hasher( self, hash: u64, key: K, value: V, hasher: H, ) -> (&'a mut K, &'a mut V) where H: Fn(&K) -> u64, { let &mut (ref mut k, ref mut v) = self .table .insert_entry(hash, (key, value), |x| hasher(&x.0)); (k, v) } #[cfg_attr(feature = "inline-more", inline)] fn insert_entry(self, key: K, value: V) -> RawOccupiedEntryMut<'a, K, V, S, A> where K: Hash, S: BuildHasher, { let hash = make_hash::(self.hash_builder, &key); let elem = self.table.insert( hash, (key, value), make_hasher::<_, V, S>(self.hash_builder), ); RawOccupiedEntryMut { elem, table: self.table, hash_builder: self.hash_builder, } } } impl Debug for RawEntryBuilderMut<'_, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("RawEntryBuilder").finish() } } impl Debug for RawEntryMut<'_, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match *self { RawEntryMut::Vacant(ref v) => f.debug_tuple("RawEntry").field(v).finish(), RawEntryMut::Occupied(ref o) => f.debug_tuple("RawEntry").field(o).finish(), } } } impl Debug for RawOccupiedEntryMut<'_, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("RawOccupiedEntryMut") .field("key", self.key()) .field("value", self.get()) .finish() } } impl Debug for RawVacantEntryMut<'_, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("RawVacantEntryMut").finish() } } impl Debug for RawEntryBuilder<'_, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("RawEntryBuilder").finish() } } /// A view into a single entry in a map, which may either be vacant or occupied. /// /// This `enum` is constructed from the [`entry`] method on [`HashMap`]. /// /// [`HashMap`]: struct.HashMap.html /// [`entry`]: struct.HashMap.html#method.entry /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap, OccupiedEntry}; /// /// let mut map = HashMap::new(); /// map.extend([("a", 10), ("b", 20), ("c", 30)]); /// assert_eq!(map.len(), 3); /// /// // Existing key (insert) /// let entry: Entry<_, _, _> = map.entry("a"); /// let _raw_o: OccupiedEntry<_, _, _> = entry.insert(1); /// assert_eq!(map.len(), 3); /// // Nonexistent key (insert) /// map.entry("d").insert(4); /// /// // Existing key (or_insert) /// let v = map.entry("b").or_insert(2); /// assert_eq!(std::mem::replace(v, 2), 20); /// // Nonexistent key (or_insert) /// map.entry("e").or_insert(5); /// /// // Existing key (or_insert_with) /// let v = map.entry("c").or_insert_with(|| 3); /// assert_eq!(std::mem::replace(v, 3), 30); /// // Nonexistent key (or_insert_with) /// map.entry("f").or_insert_with(|| 6); /// /// println!("Our HashMap: {:?}", map); /// /// let mut vec: Vec<_> = map.iter().map(|(&k, &v)| (k, v)).collect(); /// // The `Iter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [("a", 1), ("b", 2), ("c", 3), ("d", 4), ("e", 5), ("f", 6)]); /// ``` pub enum Entry<'a, K, V, S, A = Global> where A: Allocator, { /// An occupied entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap}; /// let mut map: HashMap<_, _> = [("a", 100), ("b", 200)].into(); /// /// match map.entry("a") { /// Entry::Vacant(_) => unreachable!(), /// Entry::Occupied(_) => { } /// } /// ``` Occupied(OccupiedEntry<'a, K, V, S, A>), /// A vacant entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap}; /// let mut map: HashMap<&str, i32> = HashMap::new(); /// /// match map.entry("a") { /// Entry::Occupied(_) => unreachable!(), /// Entry::Vacant(_) => { } /// } /// ``` Vacant(VacantEntry<'a, K, V, S, A>), } impl Debug for Entry<'_, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match *self { Entry::Vacant(ref v) => f.debug_tuple("Entry").field(v).finish(), Entry::Occupied(ref o) => f.debug_tuple("Entry").field(o).finish(), } } } /// A view into an occupied entry in a `HashMap`. /// It is part of the [`Entry`] enum. /// /// [`Entry`]: enum.Entry.html /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap, OccupiedEntry}; /// /// let mut map = HashMap::new(); /// map.extend([("a", 10), ("b", 20), ("c", 30)]); /// /// let _entry_o: OccupiedEntry<_, _, _> = map.entry("a").insert(100); /// assert_eq!(map.len(), 3); /// /// // Existing key (insert and update) /// match map.entry("a") { /// Entry::Vacant(_) => unreachable!(), /// Entry::Occupied(mut view) => { /// assert_eq!(view.get(), &100); /// let v = view.get_mut(); /// *v *= 10; /// assert_eq!(view.insert(1111), 1000); /// } /// } /// /// assert_eq!(map[&"a"], 1111); /// assert_eq!(map.len(), 3); /// /// // Existing key (take) /// match map.entry("c") { /// Entry::Vacant(_) => unreachable!(), /// Entry::Occupied(view) => { /// assert_eq!(view.remove_entry(), ("c", 30)); /// } /// } /// assert_eq!(map.get(&"c"), None); /// assert_eq!(map.len(), 2); /// ``` pub struct OccupiedEntry<'a, K, V, S = DefaultHashBuilder, A: Allocator = Global> { hash: u64, key: Option, elem: Bucket<(K, V)>, table: &'a mut HashMap, } unsafe impl Send for OccupiedEntry<'_, K, V, S, A> where K: Send, V: Send, S: Send, A: Send + Allocator, { } unsafe impl Sync for OccupiedEntry<'_, K, V, S, A> where K: Sync, V: Sync, S: Sync, A: Sync + Allocator, { } impl Debug for OccupiedEntry<'_, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("OccupiedEntry") .field("key", self.key()) .field("value", self.get()) .finish() } } /// A view into a vacant entry in a `HashMap`. /// It is part of the [`Entry`] enum. /// /// [`Entry`]: enum.Entry.html /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap, VacantEntry}; /// /// let mut map = HashMap::<&str, i32>::new(); /// /// let entry_v: VacantEntry<_, _, _> = match map.entry("a") { /// Entry::Vacant(view) => view, /// Entry::Occupied(_) => unreachable!(), /// }; /// entry_v.insert(10); /// assert!(map[&"a"] == 10 && map.len() == 1); /// /// // Nonexistent key (insert and update) /// match map.entry("b") { /// Entry::Occupied(_) => unreachable!(), /// Entry::Vacant(view) => { /// let value = view.insert(2); /// assert_eq!(*value, 2); /// *value = 20; /// } /// } /// assert!(map[&"b"] == 20 && map.len() == 2); /// ``` pub struct VacantEntry<'a, K, V, S = DefaultHashBuilder, A: Allocator = Global> { hash: u64, key: K, table: &'a mut HashMap, } impl Debug for VacantEntry<'_, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_tuple("VacantEntry").field(self.key()).finish() } } /// A view into a single entry in a map, which may either be vacant or occupied, /// with any borrowed form of the map's key type. /// /// /// This `enum` is constructed from the [`entry_ref`] method on [`HashMap`]. /// /// [`Hash`] and [`Eq`] on the borrowed form of the map's key type *must* match those /// for the key type. It also require that key may be constructed from the borrowed /// form through the [`From`] trait. /// /// [`HashMap`]: struct.HashMap.html /// [`entry_ref`]: struct.HashMap.html#method.entry_ref /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// [`From`]: https://doc.rust-lang.org/std/convert/trait.From.html /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap, OccupiedEntryRef}; /// /// let mut map = HashMap::new(); /// map.extend([("a".to_owned(), 10), ("b".into(), 20), ("c".into(), 30)]); /// assert_eq!(map.len(), 3); /// /// // Existing key (insert) /// let key = String::from("a"); /// let entry: EntryRef<_, _, _, _> = map.entry_ref(&key); /// let _raw_o: OccupiedEntryRef<_, _, _, _> = entry.insert(1); /// assert_eq!(map.len(), 3); /// // Nonexistent key (insert) /// map.entry_ref("d").insert(4); /// /// // Existing key (or_insert) /// let v = map.entry_ref("b").or_insert(2); /// assert_eq!(std::mem::replace(v, 2), 20); /// // Nonexistent key (or_insert) /// map.entry_ref("e").or_insert(5); /// /// // Existing key (or_insert_with) /// let v = map.entry_ref("c").or_insert_with(|| 3); /// assert_eq!(std::mem::replace(v, 3), 30); /// // Nonexistent key (or_insert_with) /// map.entry_ref("f").or_insert_with(|| 6); /// /// println!("Our HashMap: {:?}", map); /// /// for (key, value) in ["a", "b", "c", "d", "e", "f"].into_iter().zip(1..=6) { /// assert_eq!(map[key], value) /// } /// assert_eq!(map.len(), 6); /// ``` pub enum EntryRef<'a, 'b, K, Q: ?Sized, V, S, A = Global> where A: Allocator, { /// An occupied entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap}; /// let mut map: HashMap<_, _> = [("a".to_owned(), 100), ("b".into(), 200)].into(); /// /// match map.entry_ref("a") { /// EntryRef::Vacant(_) => unreachable!(), /// EntryRef::Occupied(_) => { } /// } /// ``` Occupied(OccupiedEntryRef<'a, 'b, K, Q, V, S, A>), /// A vacant entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap}; /// let mut map: HashMap = HashMap::new(); /// /// match map.entry_ref("a") { /// EntryRef::Occupied(_) => unreachable!(), /// EntryRef::Vacant(_) => { } /// } /// ``` Vacant(VacantEntryRef<'a, 'b, K, Q, V, S, A>), } impl, Q: ?Sized + Debug, V: Debug, S, A: Allocator> Debug for EntryRef<'_, '_, K, Q, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match *self { EntryRef::Vacant(ref v) => f.debug_tuple("EntryRef").field(v).finish(), EntryRef::Occupied(ref o) => f.debug_tuple("EntryRef").field(o).finish(), } } } enum KeyOrRef<'a, K, Q: ?Sized> { Borrowed(&'a Q), Owned(K), } impl<'a, K, Q: ?Sized> KeyOrRef<'a, K, Q> { fn into_owned(self) -> K where K: From<&'a Q>, { match self { Self::Borrowed(borrowed) => borrowed.into(), Self::Owned(owned) => owned, } } } impl<'a, K: Borrow, Q: ?Sized> AsRef for KeyOrRef<'a, K, Q> { fn as_ref(&self) -> &Q { match self { Self::Borrowed(borrowed) => borrowed, Self::Owned(owned) => owned.borrow(), } } } /// A view into an occupied entry in a `HashMap`. /// It is part of the [`EntryRef`] enum. /// /// [`EntryRef`]: enum.EntryRef.html /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap, OccupiedEntryRef}; /// /// let mut map = HashMap::new(); /// map.extend([("a".to_owned(), 10), ("b".into(), 20), ("c".into(), 30)]); /// /// let key = String::from("a"); /// let _entry_o: OccupiedEntryRef<_, _, _, _> = map.entry_ref(&key).insert(100); /// assert_eq!(map.len(), 3); /// /// // Existing key (insert and update) /// match map.entry_ref("a") { /// EntryRef::Vacant(_) => unreachable!(), /// EntryRef::Occupied(mut view) => { /// assert_eq!(view.get(), &100); /// let v = view.get_mut(); /// *v *= 10; /// assert_eq!(view.insert(1111), 1000); /// } /// } /// /// assert_eq!(map["a"], 1111); /// assert_eq!(map.len(), 3); /// /// // Existing key (take) /// match map.entry_ref("c") { /// EntryRef::Vacant(_) => unreachable!(), /// EntryRef::Occupied(view) => { /// assert_eq!(view.remove_entry(), ("c".to_owned(), 30)); /// } /// } /// assert_eq!(map.get("c"), None); /// assert_eq!(map.len(), 2); /// ``` pub struct OccupiedEntryRef<'a, 'b, K, Q: ?Sized, V, S, A: Allocator = Global> { hash: u64, key: Option>, elem: Bucket<(K, V)>, table: &'a mut HashMap, } unsafe impl<'a, 'b, K, Q, V, S, A> Send for OccupiedEntryRef<'a, 'b, K, Q, V, S, A> where K: Send, Q: Sync + ?Sized, V: Send, S: Send, A: Send + Allocator, { } unsafe impl<'a, 'b, K, Q, V, S, A> Sync for OccupiedEntryRef<'a, 'b, K, Q, V, S, A> where K: Sync, Q: Sync + ?Sized, V: Sync, S: Sync, A: Sync + Allocator, { } impl, Q: ?Sized + Debug, V: Debug, S, A: Allocator> Debug for OccupiedEntryRef<'_, '_, K, Q, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("OccupiedEntryRef") .field("key", &self.key().borrow()) .field("value", &self.get()) .finish() } } /// A view into a vacant entry in a `HashMap`. /// It is part of the [`EntryRef`] enum. /// /// [`EntryRef`]: enum.EntryRef.html /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap, VacantEntryRef}; /// /// let mut map = HashMap::::new(); /// /// let entry_v: VacantEntryRef<_, _, _, _> = match map.entry_ref("a") { /// EntryRef::Vacant(view) => view, /// EntryRef::Occupied(_) => unreachable!(), /// }; /// entry_v.insert(10); /// assert!(map["a"] == 10 && map.len() == 1); /// /// // Nonexistent key (insert and update) /// match map.entry_ref("b") { /// EntryRef::Occupied(_) => unreachable!(), /// EntryRef::Vacant(view) => { /// let value = view.insert(2); /// assert_eq!(*value, 2); /// *value = 20; /// } /// } /// assert!(map["b"] == 20 && map.len() == 2); /// ``` pub struct VacantEntryRef<'a, 'b, K, Q: ?Sized, V, S, A: Allocator = Global> { hash: u64, key: KeyOrRef<'b, K, Q>, table: &'a mut HashMap, } impl, Q: ?Sized + Debug, V, S, A: Allocator> Debug for VacantEntryRef<'_, '_, K, Q, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_tuple("VacantEntryRef").field(&self.key()).finish() } } /// The error returned by [`try_insert`](HashMap::try_insert) when the key already exists. /// /// Contains the occupied entry, and the value that was not inserted. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{HashMap, OccupiedError}; /// /// let mut map: HashMap<_, _> = [("a", 10), ("b", 20)].into(); /// /// // try_insert method returns mutable reference to the value if keys are vacant, /// // but if the map did have key present, nothing is updated, and the provided /// // value is returned inside `Err(_)` variant /// match map.try_insert("a", 100) { /// Err(OccupiedError { mut entry, value }) => { /// assert_eq!(entry.key(), &"a"); /// assert_eq!(value, 100); /// assert_eq!(entry.insert(100), 10) /// } /// _ => unreachable!(), /// } /// assert_eq!(map[&"a"], 100); /// ``` pub struct OccupiedError<'a, K, V, S, A: Allocator = Global> { /// The entry in the map that was already occupied. pub entry: OccupiedEntry<'a, K, V, S, A>, /// The value which was not inserted, because the entry was already occupied. pub value: V, } impl Debug for OccupiedError<'_, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("OccupiedError") .field("key", self.entry.key()) .field("old_value", self.entry.get()) .field("new_value", &self.value) .finish() } } impl<'a, K: Debug, V: Debug, S, A: Allocator> fmt::Display for OccupiedError<'a, K, V, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!( f, "failed to insert {:?}, key {:?} already exists with value {:?}", self.value, self.entry.key(), self.entry.get(), ) } } impl<'a, K, V, S, A: Allocator> IntoIterator for &'a HashMap { type Item = (&'a K, &'a V); type IntoIter = Iter<'a, K, V>; /// Creates an iterator over the entries of a `HashMap` in arbitrary order. /// The iterator element type is `(&'a K, &'a V)`. /// /// Return the same `Iter` struct as by the [`iter`] method on [`HashMap`]. /// /// [`iter`]: struct.HashMap.html#method.iter /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// let map_one: HashMap<_, _> = [(1, "a"), (2, "b"), (3, "c")].into(); /// let mut map_two = HashMap::new(); /// /// for (key, value) in &map_one { /// println!("Key: {}, Value: {}", key, value); /// map_two.insert_unique_unchecked(*key, *value); /// } /// /// assert_eq!(map_one, map_two); /// ``` #[cfg_attr(feature = "inline-more", inline)] fn into_iter(self) -> Iter<'a, K, V> { self.iter() } } impl<'a, K, V, S, A: Allocator> IntoIterator for &'a mut HashMap { type Item = (&'a K, &'a mut V); type IntoIter = IterMut<'a, K, V>; /// Creates an iterator over the entries of a `HashMap` in arbitrary order /// with mutable references to the values. The iterator element type is /// `(&'a K, &'a mut V)`. /// /// Return the same `IterMut` struct as by the [`iter_mut`] method on /// [`HashMap`]. /// /// [`iter_mut`]: struct.HashMap.html#method.iter_mut /// [`HashMap`]: struct.HashMap.html /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// let mut map: HashMap<_, _> = [("a", 1), ("b", 2), ("c", 3)].into(); /// /// for (key, value) in &mut map { /// println!("Key: {}, Value: {}", key, value); /// *value *= 2; /// } /// /// let mut vec = map.iter().collect::>(); /// // The `Iter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [(&"a", &2), (&"b", &4), (&"c", &6)]); /// ``` #[cfg_attr(feature = "inline-more", inline)] fn into_iter(self) -> IterMut<'a, K, V> { self.iter_mut() } } impl IntoIterator for HashMap { type Item = (K, V); type IntoIter = IntoIter; /// Creates a consuming iterator, that is, one that moves each key-value /// pair out of the map in arbitrary order. The map cannot be used after /// calling this. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let map: HashMap<_, _> = [("a", 1), ("b", 2), ("c", 3)].into(); /// /// // Not possible with .iter() /// let mut vec: Vec<(&str, i32)> = map.into_iter().collect(); /// // The `IntoIter` iterator produces items in arbitrary order, so /// // the items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [("a", 1), ("b", 2), ("c", 3)]); /// ``` #[cfg_attr(feature = "inline-more", inline)] fn into_iter(self) -> IntoIter { IntoIter { inner: self.table.into_iter(), } } } impl<'a, K, V> Iterator for Iter<'a, K, V> { type Item = (&'a K, &'a V); #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<(&'a K, &'a V)> { // Avoid `Option::map` because it bloats LLVM IR. match self.inner.next() { Some(x) => unsafe { let r = x.as_ref(); Some((&r.0, &r.1)) }, None => None, } } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, |acc, x| unsafe { let (k, v) = x.as_ref(); f(acc, (k, v)) }) } } impl ExactSizeIterator for Iter<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for Iter<'_, K, V> {} impl<'a, K, V> Iterator for IterMut<'a, K, V> { type Item = (&'a K, &'a mut V); #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<(&'a K, &'a mut V)> { // Avoid `Option::map` because it bloats LLVM IR. match self.inner.next() { Some(x) => unsafe { let r = x.as_mut(); Some((&r.0, &mut r.1)) }, None => None, } } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, |acc, x| unsafe { let (k, v) = x.as_mut(); f(acc, (k, v)) }) } } impl ExactSizeIterator for IterMut<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for IterMut<'_, K, V> {} impl fmt::Debug for IterMut<'_, K, V> where K: fmt::Debug, V: fmt::Debug, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.iter()).finish() } } impl Iterator for IntoIter { type Item = (K, V); #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<(K, V)> { self.inner.next() } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, f) } } impl ExactSizeIterator for IntoIter { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for IntoIter {} impl fmt::Debug for IntoIter { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.iter()).finish() } } impl<'a, K, V> Iterator for Keys<'a, K, V> { type Item = &'a K; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<&'a K> { // Avoid `Option::map` because it bloats LLVM IR. match self.inner.next() { Some((k, _)) => Some(k), None => None, } } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, |acc, (k, _)| f(acc, k)) } } impl ExactSizeIterator for Keys<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for Keys<'_, K, V> {} impl<'a, K, V> Iterator for Values<'a, K, V> { type Item = &'a V; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<&'a V> { // Avoid `Option::map` because it bloats LLVM IR. match self.inner.next() { Some((_, v)) => Some(v), None => None, } } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, |acc, (_, v)| f(acc, v)) } } impl ExactSizeIterator for Values<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for Values<'_, K, V> {} impl<'a, K, V> Iterator for ValuesMut<'a, K, V> { type Item = &'a mut V; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<&'a mut V> { // Avoid `Option::map` because it bloats LLVM IR. match self.inner.next() { Some((_, v)) => Some(v), None => None, } } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, |acc, (_, v)| f(acc, v)) } } impl ExactSizeIterator for ValuesMut<'_, K, V> { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for ValuesMut<'_, K, V> {} impl fmt::Debug for ValuesMut<'_, K, V> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list() .entries(self.inner.iter().map(|(_, val)| val)) .finish() } } impl<'a, K, V, A: Allocator> Iterator for Drain<'a, K, V, A> { type Item = (K, V); #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<(K, V)> { self.inner.next() } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, f) } } impl ExactSizeIterator for Drain<'_, K, V, A> { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for Drain<'_, K, V, A> {} impl fmt::Debug for Drain<'_, K, V, A> where K: fmt::Debug, V: fmt::Debug, A: Allocator, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.iter()).finish() } } impl<'a, K, V, S, A: Allocator> Entry<'a, K, V, S, A> { /// Sets the value of the entry, and returns an OccupiedEntry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// let entry = map.entry("horseyland").insert(37); /// /// assert_eq!(entry.key(), &"horseyland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(self, value: V) -> OccupiedEntry<'a, K, V, S, A> where K: Hash, S: BuildHasher, { match self { Entry::Occupied(mut entry) => { entry.insert(value); entry } Entry::Vacant(entry) => entry.insert_entry(value), } } /// Ensures a value is in the entry by inserting the default if empty, and returns /// a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// // nonexistent key /// map.entry("poneyland").or_insert(3); /// assert_eq!(map["poneyland"], 3); /// /// // existing key /// *map.entry("poneyland").or_insert(10) *= 2; /// assert_eq!(map["poneyland"], 6); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert(self, default: V) -> &'a mut V where K: Hash, S: BuildHasher, { match self { Entry::Occupied(entry) => entry.into_mut(), Entry::Vacant(entry) => entry.insert(default), } } /// Ensures a value is in the entry by inserting the result of the default function if empty, /// and returns a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// // nonexistent key /// map.entry("poneyland").or_insert_with(|| 3); /// assert_eq!(map["poneyland"], 3); /// /// // existing key /// *map.entry("poneyland").or_insert_with(|| 10) *= 2; /// assert_eq!(map["poneyland"], 6); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert_with V>(self, default: F) -> &'a mut V where K: Hash, S: BuildHasher, { match self { Entry::Occupied(entry) => entry.into_mut(), Entry::Vacant(entry) => entry.insert(default()), } } /// Ensures a value is in the entry by inserting, if empty, the result of the default function. /// This method allows for generating key-derived values for insertion by providing the default /// function a reference to the key that was moved during the `.entry(key)` method call. /// /// The reference to the moved key is provided so that cloning or copying the key is /// unnecessary, unlike with `.or_insert_with(|| ... )`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, usize> = HashMap::new(); /// /// // nonexistent key /// map.entry("poneyland").or_insert_with_key(|key| key.chars().count()); /// assert_eq!(map["poneyland"], 9); /// /// // existing key /// *map.entry("poneyland").or_insert_with_key(|key| key.chars().count() * 10) *= 2; /// assert_eq!(map["poneyland"], 18); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert_with_key V>(self, default: F) -> &'a mut V where K: Hash, S: BuildHasher, { match self { Entry::Occupied(entry) => entry.into_mut(), Entry::Vacant(entry) => { let value = default(entry.key()); entry.insert(value) } } } /// Returns a reference to this entry's key. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.entry("poneyland").or_insert(3); /// // existing key /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); /// // nonexistent key /// assert_eq!(map.entry("horseland").key(), &"horseland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &K { match *self { Entry::Occupied(ref entry) => entry.key(), Entry::Vacant(ref entry) => entry.key(), } } /// Provides in-place mutable access to an occupied entry before any /// potential inserts into the map. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// map.entry("poneyland") /// .and_modify(|e| { *e += 1 }) /// .or_insert(42); /// assert_eq!(map["poneyland"], 42); /// /// map.entry("poneyland") /// .and_modify(|e| { *e += 1 }) /// .or_insert(42); /// assert_eq!(map["poneyland"], 43); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn and_modify(self, f: F) -> Self where F: FnOnce(&mut V), { match self { Entry::Occupied(mut entry) => { f(entry.get_mut()); Entry::Occupied(entry) } Entry::Vacant(entry) => Entry::Vacant(entry), } } /// Provides shared access to the key and owned access to the value of /// an occupied entry and allows to replace or remove it based on the /// value of the returned option. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::Entry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// let entry = map /// .entry("poneyland") /// .and_replace_entry_with(|_k, _v| panic!()); /// /// match entry { /// Entry::Vacant(e) => { /// assert_eq!(e.key(), &"poneyland"); /// } /// Entry::Occupied(_) => panic!(), /// } /// /// map.insert("poneyland", 42); /// /// let entry = map /// .entry("poneyland") /// .and_replace_entry_with(|k, v| { /// assert_eq!(k, &"poneyland"); /// assert_eq!(v, 42); /// Some(v + 1) /// }); /// /// match entry { /// Entry::Occupied(e) => { /// assert_eq!(e.key(), &"poneyland"); /// assert_eq!(e.get(), &43); /// } /// Entry::Vacant(_) => panic!(), /// } /// /// assert_eq!(map["poneyland"], 43); /// /// let entry = map /// .entry("poneyland") /// .and_replace_entry_with(|_k, _v| None); /// /// match entry { /// Entry::Vacant(e) => assert_eq!(e.key(), &"poneyland"), /// Entry::Occupied(_) => panic!(), /// } /// /// assert!(!map.contains_key("poneyland")); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn and_replace_entry_with(self, f: F) -> Self where F: FnOnce(&K, V) -> Option, { match self { Entry::Occupied(entry) => entry.replace_entry_with(f), Entry::Vacant(_) => self, } } } impl<'a, K, V: Default, S, A: Allocator> Entry<'a, K, V, S, A> { /// Ensures a value is in the entry by inserting the default value if empty, /// and returns a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, Option> = HashMap::new(); /// /// // nonexistent key /// map.entry("poneyland").or_default(); /// assert_eq!(map["poneyland"], None); /// /// map.insert("horseland", Some(3)); /// /// // existing key /// assert_eq!(map.entry("horseland").or_default(), &mut Some(3)); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_default(self) -> &'a mut V where K: Hash, S: BuildHasher, { match self { Entry::Occupied(entry) => entry.into_mut(), Entry::Vacant(entry) => entry.insert(Default::default()), } } } impl<'a, K, V, S, A: Allocator> OccupiedEntry<'a, K, V, S, A> { /// Gets a reference to the key in the entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap}; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.entry("poneyland").or_insert(12); /// /// match map.entry("poneyland") { /// Entry::Vacant(_) => panic!(), /// Entry::Occupied(entry) => assert_eq!(entry.key(), &"poneyland"), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &K { unsafe { &self.elem.as_ref().0 } } /// Take the ownership of the key and value from the map. /// Keeps the allocated memory for reuse. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::Entry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// // The map is empty /// assert!(map.is_empty() && map.capacity() == 0); /// /// map.entry("poneyland").or_insert(12); /// /// if let Entry::Occupied(o) = map.entry("poneyland") { /// // We delete the entry from the map. /// assert_eq!(o.remove_entry(), ("poneyland", 12)); /// } /// /// assert_eq!(map.contains_key("poneyland"), false); /// // Now map hold none elements /// assert!(map.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove_entry(self) -> (K, V) { unsafe { self.table.table.remove(self.elem).0 } } /// Gets a reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::Entry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.entry("poneyland").or_insert(12); /// /// match map.entry("poneyland") { /// Entry::Vacant(_) => panic!(), /// Entry::Occupied(entry) => assert_eq!(entry.get(), &12), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get(&self) -> &V { unsafe { &self.elem.as_ref().1 } } /// Gets a mutable reference to the value in the entry. /// /// If you need a reference to the `OccupiedEntry` which may outlive the /// destruction of the `Entry` value, see [`into_mut`]. /// /// [`into_mut`]: #method.into_mut /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::Entry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.entry("poneyland").or_insert(12); /// /// assert_eq!(map["poneyland"], 12); /// if let Entry::Occupied(mut o) = map.entry("poneyland") { /// *o.get_mut() += 10; /// assert_eq!(*o.get(), 22); /// /// // We can use the same Entry multiple times. /// *o.get_mut() += 2; /// } /// /// assert_eq!(map["poneyland"], 24); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get_mut(&mut self) -> &mut V { unsafe { &mut self.elem.as_mut().1 } } /// Converts the OccupiedEntry into a mutable reference to the value in the entry /// with a lifetime bound to the map itself. /// /// If you need multiple references to the `OccupiedEntry`, see [`get_mut`]. /// /// [`get_mut`]: #method.get_mut /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap}; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.entry("poneyland").or_insert(12); /// /// assert_eq!(map["poneyland"], 12); /// /// let value: &mut u32; /// match map.entry("poneyland") { /// Entry::Occupied(entry) => value = entry.into_mut(), /// Entry::Vacant(_) => panic!(), /// } /// *value += 10; /// /// assert_eq!(map["poneyland"], 22); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_mut(self) -> &'a mut V { unsafe { &mut self.elem.as_mut().1 } } /// Sets the value of the entry, and returns the entry's old value. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::Entry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.entry("poneyland").or_insert(12); /// /// if let Entry::Occupied(mut o) = map.entry("poneyland") { /// assert_eq!(o.insert(15), 12); /// } /// /// assert_eq!(map["poneyland"], 15); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(&mut self, value: V) -> V { mem::replace(self.get_mut(), value) } /// Takes the value out of the entry, and returns it. /// Keeps the allocated memory for reuse. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::Entry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// // The map is empty /// assert!(map.is_empty() && map.capacity() == 0); /// /// map.entry("poneyland").or_insert(12); /// /// if let Entry::Occupied(o) = map.entry("poneyland") { /// assert_eq!(o.remove(), 12); /// } /// /// assert_eq!(map.contains_key("poneyland"), false); /// // Now map hold none elements /// assert!(map.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove(self) -> V { self.remove_entry().1 } /// Replaces the entry, returning the old key and value. The new key in the hash map will be /// the key used to create this entry. /// /// # Panics /// /// Will panic if this OccupiedEntry was created through [`Entry::insert`]. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap}; /// use std::rc::Rc; /// /// let mut map: HashMap, u32> = HashMap::new(); /// let key_one = Rc::new("Stringthing".to_string()); /// let key_two = Rc::new("Stringthing".to_string()); /// /// map.insert(key_one.clone(), 15); /// assert!(Rc::strong_count(&key_one) == 2 && Rc::strong_count(&key_two) == 1); /// /// match map.entry(key_two.clone()) { /// Entry::Occupied(entry) => { /// let (old_key, old_value): (Rc, u32) = entry.replace_entry(16); /// assert!(Rc::ptr_eq(&key_one, &old_key) && old_value == 15); /// } /// Entry::Vacant(_) => panic!(), /// } /// /// assert!(Rc::strong_count(&key_one) == 1 && Rc::strong_count(&key_two) == 2); /// assert_eq!(map[&"Stringthing".to_owned()], 16); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace_entry(self, value: V) -> (K, V) { let entry = unsafe { self.elem.as_mut() }; let old_key = mem::replace(&mut entry.0, self.key.unwrap()); let old_value = mem::replace(&mut entry.1, value); (old_key, old_value) } /// Replaces the key in the hash map with the key used to create this entry. /// /// # Panics /// /// Will panic if this OccupiedEntry was created through [`Entry::insert`]. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap}; /// use std::rc::Rc; /// /// let mut map: HashMap, usize> = HashMap::with_capacity(6); /// let mut keys_one: Vec> = Vec::with_capacity(6); /// let mut keys_two: Vec> = Vec::with_capacity(6); /// /// for (value, key) in ["a", "b", "c", "d", "e", "f"].into_iter().enumerate() { /// let rc_key = Rc::new(key.to_owned()); /// keys_one.push(rc_key.clone()); /// map.insert(rc_key.clone(), value); /// keys_two.push(Rc::new(key.to_owned())); /// } /// /// assert!( /// keys_one.iter().all(|key| Rc::strong_count(key) == 2) /// && keys_two.iter().all(|key| Rc::strong_count(key) == 1) /// ); /// /// reclaim_memory(&mut map, &keys_two); /// /// assert!( /// keys_one.iter().all(|key| Rc::strong_count(key) == 1) /// && keys_two.iter().all(|key| Rc::strong_count(key) == 2) /// ); /// /// fn reclaim_memory(map: &mut HashMap, usize>, keys: &[Rc]) { /// for key in keys { /// if let Entry::Occupied(entry) = map.entry(key.clone()) { /// // Replaces the entry's key with our version of it in `keys`. /// entry.replace_key(); /// } /// } /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace_key(self) -> K { let entry = unsafe { self.elem.as_mut() }; mem::replace(&mut entry.0, self.key.unwrap()) } /// Provides shared access to the key and owned access to the value of /// the entry and allows to replace or remove it based on the /// value of the returned option. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::Entry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.insert("poneyland", 42); /// /// let entry = match map.entry("poneyland") { /// Entry::Occupied(e) => { /// e.replace_entry_with(|k, v| { /// assert_eq!(k, &"poneyland"); /// assert_eq!(v, 42); /// Some(v + 1) /// }) /// } /// Entry::Vacant(_) => panic!(), /// }; /// /// match entry { /// Entry::Occupied(e) => { /// assert_eq!(e.key(), &"poneyland"); /// assert_eq!(e.get(), &43); /// } /// Entry::Vacant(_) => panic!(), /// } /// /// assert_eq!(map["poneyland"], 43); /// /// let entry = match map.entry("poneyland") { /// Entry::Occupied(e) => e.replace_entry_with(|_k, _v| None), /// Entry::Vacant(_) => panic!(), /// }; /// /// match entry { /// Entry::Vacant(e) => { /// assert_eq!(e.key(), &"poneyland"); /// } /// Entry::Occupied(_) => panic!(), /// } /// /// assert!(!map.contains_key("poneyland")); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace_entry_with(self, f: F) -> Entry<'a, K, V, S, A> where F: FnOnce(&K, V) -> Option, { unsafe { let mut spare_key = None; self.table .table .replace_bucket_with(self.elem.clone(), |(key, value)| { if let Some(new_value) = f(&key, value) { Some((key, new_value)) } else { spare_key = Some(key); None } }); if let Some(key) = spare_key { Entry::Vacant(VacantEntry { hash: self.hash, key, table: self.table, }) } else { Entry::Occupied(self) } } } } impl<'a, K, V, S, A: Allocator> VacantEntry<'a, K, V, S, A> { /// Gets a reference to the key that would be used when inserting a value /// through the `VacantEntry`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &K { &self.key } /// Take ownership of the key. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{Entry, HashMap}; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// match map.entry("poneyland") { /// Entry::Occupied(_) => panic!(), /// Entry::Vacant(v) => assert_eq!(v.into_key(), "poneyland"), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_key(self) -> K { self.key } /// Sets the value of the entry with the VacantEntry's key, /// and returns a mutable reference to it. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::Entry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// if let Entry::Vacant(o) = map.entry("poneyland") { /// o.insert(37); /// } /// assert_eq!(map["poneyland"], 37); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(self, value: V) -> &'a mut V where K: Hash, S: BuildHasher, { let table = &mut self.table.table; let entry = table.insert_entry( self.hash, (self.key, value), make_hasher::<_, V, S>(&self.table.hash_builder), ); &mut entry.1 } #[cfg_attr(feature = "inline-more", inline)] pub(crate) fn insert_entry(self, value: V) -> OccupiedEntry<'a, K, V, S, A> where K: Hash, S: BuildHasher, { let elem = self.table.table.insert( self.hash, (self.key, value), make_hasher::<_, V, S>(&self.table.hash_builder), ); OccupiedEntry { hash: self.hash, key: None, elem, table: self.table, } } } impl<'a, 'b, K, Q: ?Sized, V, S, A: Allocator> EntryRef<'a, 'b, K, Q, V, S, A> { /// Sets the value of the entry, and returns an OccupiedEntryRef. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = HashMap::new(); /// let entry = map.entry_ref("horseyland").insert(37); /// /// assert_eq!(entry.key(), "horseyland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(self, value: V) -> OccupiedEntryRef<'a, 'b, K, Q, V, S, A> where K: Hash + From<&'b Q>, S: BuildHasher, { match self { EntryRef::Occupied(mut entry) => { entry.insert(value); entry } EntryRef::Vacant(entry) => entry.insert_entry(value), } } /// Ensures a value is in the entry by inserting the default if empty, and returns /// a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = HashMap::new(); /// /// // nonexistent key /// map.entry_ref("poneyland").or_insert(3); /// assert_eq!(map["poneyland"], 3); /// /// // existing key /// *map.entry_ref("poneyland").or_insert(10) *= 2; /// assert_eq!(map["poneyland"], 6); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert(self, default: V) -> &'a mut V where K: Hash + From<&'b Q>, S: BuildHasher, { match self { EntryRef::Occupied(entry) => entry.into_mut(), EntryRef::Vacant(entry) => entry.insert(default), } } /// Ensures a value is in the entry by inserting the result of the default function if empty, /// and returns a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = HashMap::new(); /// /// // nonexistent key /// map.entry_ref("poneyland").or_insert_with(|| 3); /// assert_eq!(map["poneyland"], 3); /// /// // existing key /// *map.entry_ref("poneyland").or_insert_with(|| 10) *= 2; /// assert_eq!(map["poneyland"], 6); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert_with V>(self, default: F) -> &'a mut V where K: Hash + From<&'b Q>, S: BuildHasher, { match self { EntryRef::Occupied(entry) => entry.into_mut(), EntryRef::Vacant(entry) => entry.insert(default()), } } /// Ensures a value is in the entry by inserting, if empty, the result of the default function. /// This method allows for generating key-derived values for insertion by providing the default /// function an access to the borrower form of the key. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = HashMap::new(); /// /// // nonexistent key /// map.entry_ref("poneyland").or_insert_with_key(|key| key.chars().count()); /// assert_eq!(map["poneyland"], 9); /// /// // existing key /// *map.entry_ref("poneyland").or_insert_with_key(|key| key.chars().count() * 10) *= 2; /// assert_eq!(map["poneyland"], 18); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert_with_key V>(self, default: F) -> &'a mut V where K: Hash + Borrow + From<&'b Q>, S: BuildHasher, { match self { EntryRef::Occupied(entry) => entry.into_mut(), EntryRef::Vacant(entry) => { let value = default(entry.key.as_ref()); entry.insert(value) } } } /// Returns a reference to this entry's key. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = HashMap::new(); /// map.entry_ref("poneyland").or_insert(3); /// // existing key /// assert_eq!(map.entry_ref("poneyland").key(), "poneyland"); /// // nonexistent key /// assert_eq!(map.entry_ref("horseland").key(), "horseland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &Q where K: Borrow, { match *self { EntryRef::Occupied(ref entry) => entry.key().borrow(), EntryRef::Vacant(ref entry) => entry.key(), } } /// Provides in-place mutable access to an occupied entry before any /// potential inserts into the map. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = HashMap::new(); /// /// map.entry_ref("poneyland") /// .and_modify(|e| { *e += 1 }) /// .or_insert(42); /// assert_eq!(map["poneyland"], 42); /// /// map.entry_ref("poneyland") /// .and_modify(|e| { *e += 1 }) /// .or_insert(42); /// assert_eq!(map["poneyland"], 43); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn and_modify(self, f: F) -> Self where F: FnOnce(&mut V), { match self { EntryRef::Occupied(mut entry) => { f(entry.get_mut()); EntryRef::Occupied(entry) } EntryRef::Vacant(entry) => EntryRef::Vacant(entry), } } /// Provides shared access to the key and owned access to the value of /// an occupied entry and allows to replace or remove it based on the /// value of the returned option. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::EntryRef; /// /// let mut map: HashMap = HashMap::new(); /// /// let entry = map /// .entry_ref("poneyland") /// .and_replace_entry_with(|_k, _v| panic!()); /// /// match entry { /// EntryRef::Vacant(e) => { /// assert_eq!(e.key(), "poneyland"); /// } /// EntryRef::Occupied(_) => panic!(), /// } /// /// map.insert("poneyland".to_string(), 42); /// /// let entry = map /// .entry_ref("poneyland") /// .and_replace_entry_with(|k, v| { /// assert_eq!(k, "poneyland"); /// assert_eq!(v, 42); /// Some(v + 1) /// }); /// /// match entry { /// EntryRef::Occupied(e) => { /// assert_eq!(e.key(), "poneyland"); /// assert_eq!(e.get(), &43); /// } /// EntryRef::Vacant(_) => panic!(), /// } /// /// assert_eq!(map["poneyland"], 43); /// /// let entry = map /// .entry_ref("poneyland") /// .and_replace_entry_with(|_k, _v| None); /// /// match entry { /// EntryRef::Vacant(e) => assert_eq!(e.key(), "poneyland"), /// EntryRef::Occupied(_) => panic!(), /// } /// /// assert!(!map.contains_key("poneyland")); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn and_replace_entry_with(self, f: F) -> Self where F: FnOnce(&K, V) -> Option, { match self { EntryRef::Occupied(entry) => entry.replace_entry_with(f), EntryRef::Vacant(_) => self, } } } impl<'a, 'b, K, Q: ?Sized, V: Default, S, A: Allocator> EntryRef<'a, 'b, K, Q, V, S, A> { /// Ensures a value is in the entry by inserting the default value if empty, /// and returns a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap> = HashMap::new(); /// /// // nonexistent key /// map.entry_ref("poneyland").or_default(); /// assert_eq!(map["poneyland"], None); /// /// map.insert("horseland".to_string(), Some(3)); /// /// // existing key /// assert_eq!(map.entry_ref("horseland").or_default(), &mut Some(3)); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_default(self) -> &'a mut V where K: Hash + From<&'b Q>, S: BuildHasher, { match self { EntryRef::Occupied(entry) => entry.into_mut(), EntryRef::Vacant(entry) => entry.insert(Default::default()), } } } impl<'a, 'b, K, Q: ?Sized, V, S, A: Allocator> OccupiedEntryRef<'a, 'b, K, Q, V, S, A> { /// Gets a reference to the key in the entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap}; /// /// let mut map: HashMap = HashMap::new(); /// map.entry_ref("poneyland").or_insert(12); /// /// match map.entry_ref("poneyland") { /// EntryRef::Vacant(_) => panic!(), /// EntryRef::Occupied(entry) => assert_eq!(entry.key(), "poneyland"), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &K { unsafe { &self.elem.as_ref().0 } } /// Take the ownership of the key and value from the map. /// Keeps the allocated memory for reuse. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::EntryRef; /// /// let mut map: HashMap = HashMap::new(); /// // The map is empty /// assert!(map.is_empty() && map.capacity() == 0); /// /// map.entry_ref("poneyland").or_insert(12); /// /// if let EntryRef::Occupied(o) = map.entry_ref("poneyland") { /// // We delete the entry from the map. /// assert_eq!(o.remove_entry(), ("poneyland".to_owned(), 12)); /// } /// /// assert_eq!(map.contains_key("poneyland"), false); /// // Now map hold none elements but capacity is equal to the old one /// assert!(map.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove_entry(self) -> (K, V) { unsafe { self.table.table.remove(self.elem).0 } } /// Gets a reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::EntryRef; /// /// let mut map: HashMap = HashMap::new(); /// map.entry_ref("poneyland").or_insert(12); /// /// match map.entry_ref("poneyland") { /// EntryRef::Vacant(_) => panic!(), /// EntryRef::Occupied(entry) => assert_eq!(entry.get(), &12), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get(&self) -> &V { unsafe { &self.elem.as_ref().1 } } /// Gets a mutable reference to the value in the entry. /// /// If you need a reference to the `OccupiedEntryRef` which may outlive the /// destruction of the `EntryRef` value, see [`into_mut`]. /// /// [`into_mut`]: #method.into_mut /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::EntryRef; /// /// let mut map: HashMap = HashMap::new(); /// map.entry_ref("poneyland").or_insert(12); /// /// assert_eq!(map["poneyland"], 12); /// if let EntryRef::Occupied(mut o) = map.entry_ref("poneyland") { /// *o.get_mut() += 10; /// assert_eq!(*o.get(), 22); /// /// // We can use the same Entry multiple times. /// *o.get_mut() += 2; /// } /// /// assert_eq!(map["poneyland"], 24); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get_mut(&mut self) -> &mut V { unsafe { &mut self.elem.as_mut().1 } } /// Converts the OccupiedEntryRef into a mutable reference to the value in the entry /// with a lifetime bound to the map itself. /// /// If you need multiple references to the `OccupiedEntryRef`, see [`get_mut`]. /// /// [`get_mut`]: #method.get_mut /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap}; /// /// let mut map: HashMap = HashMap::new(); /// map.entry_ref("poneyland").or_insert(12); /// /// let value: &mut u32; /// match map.entry_ref("poneyland") { /// EntryRef::Occupied(entry) => value = entry.into_mut(), /// EntryRef::Vacant(_) => panic!(), /// } /// *value += 10; /// /// assert_eq!(map["poneyland"], 22); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_mut(self) -> &'a mut V { unsafe { &mut self.elem.as_mut().1 } } /// Sets the value of the entry, and returns the entry's old value. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::EntryRef; /// /// let mut map: HashMap = HashMap::new(); /// map.entry_ref("poneyland").or_insert(12); /// /// if let EntryRef::Occupied(mut o) = map.entry_ref("poneyland") { /// assert_eq!(o.insert(15), 12); /// } /// /// assert_eq!(map["poneyland"], 15); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(&mut self, value: V) -> V { mem::replace(self.get_mut(), value) } /// Takes the value out of the entry, and returns it. /// Keeps the allocated memory for reuse. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::EntryRef; /// /// let mut map: HashMap = HashMap::new(); /// // The map is empty /// assert!(map.is_empty() && map.capacity() == 0); /// /// map.entry_ref("poneyland").or_insert(12); /// /// if let EntryRef::Occupied(o) = map.entry_ref("poneyland") { /// assert_eq!(o.remove(), 12); /// } /// /// assert_eq!(map.contains_key("poneyland"), false); /// // Now map hold none elements but capacity is equal to the old one /// assert!(map.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove(self) -> V { self.remove_entry().1 } /// Replaces the entry, returning the old key and value. The new key in the hash map will be /// the key used to create this entry. /// /// # Panics /// /// Will panic if this OccupiedEntryRef was created through [`EntryRef::insert`]. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap}; /// use std::rc::Rc; /// /// let mut map: HashMap, u32> = HashMap::new(); /// let key: Rc = Rc::from("Stringthing"); /// /// map.insert(key.clone(), 15); /// assert_eq!(Rc::strong_count(&key), 2); /// /// match map.entry_ref("Stringthing") { /// EntryRef::Occupied(entry) => { /// let (old_key, old_value): (Rc, u32) = entry.replace_entry(16); /// assert!(Rc::ptr_eq(&key, &old_key) && old_value == 15); /// } /// EntryRef::Vacant(_) => panic!(), /// } /// /// assert_eq!(Rc::strong_count(&key), 1); /// assert_eq!(map["Stringthing"], 16); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace_entry(self, value: V) -> (K, V) where K: From<&'b Q>, { let entry = unsafe { self.elem.as_mut() }; let old_key = mem::replace(&mut entry.0, self.key.unwrap().into_owned()); let old_value = mem::replace(&mut entry.1, value); (old_key, old_value) } /// Replaces the key in the hash map with the key used to create this entry. /// /// # Panics /// /// Will panic if this OccupiedEntryRef was created through [`EntryRef::insert`]. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap}; /// use std::rc::Rc; /// /// let mut map: HashMap, usize> = HashMap::with_capacity(6); /// let mut keys: Vec> = Vec::with_capacity(6); /// /// for (value, key) in ["a", "b", "c", "d", "e", "f"].into_iter().enumerate() { /// let rc_key: Rc = Rc::from(key); /// keys.push(rc_key.clone()); /// map.insert(rc_key.clone(), value); /// } /// /// assert!(keys.iter().all(|key| Rc::strong_count(key) == 2)); /// /// // It doesn't matter that we kind of use a vector with the same keys, /// // because all keys will be newly created from the references /// reclaim_memory(&mut map, &keys); /// /// assert!(keys.iter().all(|key| Rc::strong_count(key) == 1)); /// /// fn reclaim_memory(map: &mut HashMap, usize>, keys: &[Rc]) { /// for key in keys { /// if let EntryRef::Occupied(entry) = map.entry_ref(key.as_ref()) { /// // Replaces the entry's key with our version of it in `keys`. /// entry.replace_key(); /// } /// } /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace_key(self) -> K where K: From<&'b Q>, { let entry = unsafe { self.elem.as_mut() }; mem::replace(&mut entry.0, self.key.unwrap().into_owned()) } /// Provides shared access to the key and owned access to the value of /// the entry and allows to replace or remove it based on the /// value of the returned option. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::EntryRef; /// /// let mut map: HashMap = HashMap::new(); /// map.insert("poneyland".to_string(), 42); /// /// let entry = match map.entry_ref("poneyland") { /// EntryRef::Occupied(e) => { /// e.replace_entry_with(|k, v| { /// assert_eq!(k, "poneyland"); /// assert_eq!(v, 42); /// Some(v + 1) /// }) /// } /// EntryRef::Vacant(_) => panic!(), /// }; /// /// match entry { /// EntryRef::Occupied(e) => { /// assert_eq!(e.key(), "poneyland"); /// assert_eq!(e.get(), &43); /// } /// EntryRef::Vacant(_) => panic!(), /// } /// /// assert_eq!(map["poneyland"], 43); /// /// let entry = match map.entry_ref("poneyland") { /// EntryRef::Occupied(e) => e.replace_entry_with(|_k, _v| None), /// EntryRef::Vacant(_) => panic!(), /// }; /// /// match entry { /// EntryRef::Vacant(e) => { /// assert_eq!(e.key(), "poneyland"); /// } /// EntryRef::Occupied(_) => panic!(), /// } /// /// assert!(!map.contains_key("poneyland")); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace_entry_with(self, f: F) -> EntryRef<'a, 'b, K, Q, V, S, A> where F: FnOnce(&K, V) -> Option, { unsafe { let mut spare_key = None; self.table .table .replace_bucket_with(self.elem.clone(), |(key, value)| { if let Some(new_value) = f(&key, value) { Some((key, new_value)) } else { spare_key = Some(KeyOrRef::Owned(key)); None } }); if let Some(key) = spare_key { EntryRef::Vacant(VacantEntryRef { hash: self.hash, key, table: self.table, }) } else { EntryRef::Occupied(self) } } } } impl<'a, 'b, K, Q: ?Sized, V, S, A: Allocator> VacantEntryRef<'a, 'b, K, Q, V, S, A> { /// Gets a reference to the key that would be used when inserting a value /// through the `VacantEntryRef`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap = HashMap::new(); /// let key: &str = "poneyland"; /// assert_eq!(map.entry_ref(key).key(), "poneyland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &Q where K: Borrow, { self.key.as_ref() } /// Take ownership of the key. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{EntryRef, HashMap}; /// /// let mut map: HashMap = HashMap::new(); /// let key: &str = "poneyland"; /// /// match map.entry_ref(key) { /// EntryRef::Occupied(_) => panic!(), /// EntryRef::Vacant(v) => assert_eq!(v.into_key(), "poneyland".to_owned()), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_key(self) -> K where K: From<&'b Q>, { self.key.into_owned() } /// Sets the value of the entry with the VacantEntryRef's key, /// and returns a mutable reference to it. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::EntryRef; /// /// let mut map: HashMap = HashMap::new(); /// let key: &str = "poneyland"; /// /// if let EntryRef::Vacant(o) = map.entry_ref(key) { /// o.insert(37); /// } /// assert_eq!(map["poneyland"], 37); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(self, value: V) -> &'a mut V where K: Hash + From<&'b Q>, S: BuildHasher, { let table = &mut self.table.table; let entry = table.insert_entry( self.hash, (self.key.into_owned(), value), make_hasher::<_, V, S>(&self.table.hash_builder), ); &mut entry.1 } #[cfg_attr(feature = "inline-more", inline)] fn insert_entry(self, value: V) -> OccupiedEntryRef<'a, 'b, K, Q, V, S, A> where K: Hash + From<&'b Q>, S: BuildHasher, { let elem = self.table.table.insert( self.hash, (self.key.into_owned(), value), make_hasher::<_, V, S>(&self.table.hash_builder), ); OccupiedEntryRef { hash: self.hash, key: None, elem, table: self.table, } } } impl FromIterator<(K, V)> for HashMap where K: Eq + Hash, S: BuildHasher + Default, A: Default + Allocator, { #[cfg_attr(feature = "inline-more", inline)] fn from_iter>(iter: T) -> Self { let iter = iter.into_iter(); let mut map = Self::with_capacity_and_hasher_in(iter.size_hint().0, S::default(), A::default()); iter.for_each(|(k, v)| { map.insert(k, v); }); map } } /// Inserts all new key-values from the iterator and replaces values with existing /// keys with new values returned from the iterator. impl Extend<(K, V)> for HashMap where K: Eq + Hash, S: BuildHasher, A: Allocator, { /// Inserts all new key-values from the iterator to existing `HashMap`. /// Replace values with existing keys with new values returned from the iterator. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::HashMap; /// /// let mut map = HashMap::new(); /// map.insert(1, 100); /// /// let some_iter = [(1, 1), (2, 2)].into_iter(); /// map.extend(some_iter); /// // Replace values with existing keys with new values returned from the iterator. /// // So that the map.get(&1) doesn't return Some(&100). /// assert_eq!(map.get(&1), Some(&1)); /// /// let some_vec: Vec<_> = vec![(3, 3), (4, 4)]; /// map.extend(some_vec); /// /// let some_arr = [(5, 5), (6, 6)]; /// map.extend(some_arr); /// let old_map_len = map.len(); /// /// // You can also extend from another HashMap /// let mut new_map = HashMap::new(); /// new_map.extend(map); /// assert_eq!(new_map.len(), old_map_len); /// /// let mut vec: Vec<_> = new_map.into_iter().collect(); /// // The `IntoIter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]); /// ``` #[cfg_attr(feature = "inline-more", inline)] fn extend>(&mut self, iter: T) { // Keys may be already present or show multiple times in the iterator. // Reserve the entire hint lower bound if the map is empty. // Otherwise reserve half the hint (rounded up), so the map // will only resize twice in the worst case. let iter = iter.into_iter(); let reserve = if self.is_empty() { iter.size_hint().0 } else { (iter.size_hint().0 + 1) / 2 }; self.reserve(reserve); iter.for_each(move |(k, v)| { self.insert(k, v); }); } #[inline] #[cfg(feature = "nightly")] fn extend_one(&mut self, (k, v): (K, V)) { self.insert(k, v); } #[inline] #[cfg(feature = "nightly")] fn extend_reserve(&mut self, additional: usize) { // Keys may be already present or show multiple times in the iterator. // Reserve the entire hint lower bound if the map is empty. // Otherwise reserve half the hint (rounded up), so the map // will only resize twice in the worst case. let reserve = if self.is_empty() { additional } else { (additional + 1) / 2 }; self.reserve(reserve); } } /// Inserts all new key-values from the iterator and replaces values with existing /// keys with new values returned from the iterator. impl<'a, K, V, S, A> Extend<(&'a K, &'a V)> for HashMap where K: Eq + Hash + Copy, V: Copy, S: BuildHasher, A: Allocator, { /// Inserts all new key-values from the iterator to existing `HashMap`. /// Replace values with existing keys with new values returned from the iterator. /// The keys and values must implement [`Copy`] trait. /// /// [`Copy`]: https://doc.rust-lang.org/core/marker/trait.Copy.html /// /// # Examples /// /// ``` /// use hashbrown::hash_map::HashMap; /// /// let mut map = HashMap::new(); /// map.insert(1, 100); /// /// let arr = [(1, 1), (2, 2)]; /// let some_iter = arr.iter().map(|(k, v)| (k, v)); /// map.extend(some_iter); /// // Replace values with existing keys with new values returned from the iterator. /// // So that the map.get(&1) doesn't return Some(&100). /// assert_eq!(map.get(&1), Some(&1)); /// /// let some_vec: Vec<_> = vec![(3, 3), (4, 4)]; /// map.extend(some_vec.iter().map(|(k, v)| (k, v))); /// /// let some_arr = [(5, 5), (6, 6)]; /// map.extend(some_arr.iter().map(|(k, v)| (k, v))); /// /// // You can also extend from another HashMap /// let mut new_map = HashMap::new(); /// new_map.extend(&map); /// assert_eq!(new_map, map); /// /// let mut vec: Vec<_> = new_map.into_iter().collect(); /// // The `IntoIter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]); /// ``` #[cfg_attr(feature = "inline-more", inline)] fn extend>(&mut self, iter: T) { self.extend(iter.into_iter().map(|(&key, &value)| (key, value))); } #[inline] #[cfg(feature = "nightly")] fn extend_one(&mut self, (k, v): (&'a K, &'a V)) { self.insert(*k, *v); } #[inline] #[cfg(feature = "nightly")] fn extend_reserve(&mut self, additional: usize) { Extend::<(K, V)>::extend_reserve(self, additional); } } /// Inserts all new key-values from the iterator and replaces values with existing /// keys with new values returned from the iterator. impl<'a, K, V, S, A> Extend<&'a (K, V)> for HashMap where K: Eq + Hash + Copy, V: Copy, S: BuildHasher, A: Allocator, { /// Inserts all new key-values from the iterator to existing `HashMap`. /// Replace values with existing keys with new values returned from the iterator. /// The keys and values must implement [`Copy`] trait. /// /// [`Copy`]: https://doc.rust-lang.org/core/marker/trait.Copy.html /// /// # Examples /// /// ``` /// use hashbrown::hash_map::HashMap; /// /// let mut map = HashMap::new(); /// map.insert(1, 100); /// /// let arr = [(1, 1), (2, 2)]; /// let some_iter = arr.iter(); /// map.extend(some_iter); /// // Replace values with existing keys with new values returned from the iterator. /// // So that the map.get(&1) doesn't return Some(&100). /// assert_eq!(map.get(&1), Some(&1)); /// /// let some_vec: Vec<_> = vec![(3, 3), (4, 4)]; /// map.extend(&some_vec); /// /// let some_arr = [(5, 5), (6, 6)]; /// map.extend(&some_arr); /// /// let mut vec: Vec<_> = map.into_iter().collect(); /// // The `IntoIter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]); /// ``` #[cfg_attr(feature = "inline-more", inline)] fn extend>(&mut self, iter: T) { self.extend(iter.into_iter().map(|&(key, value)| (key, value))); } #[inline] #[cfg(feature = "nightly")] fn extend_one(&mut self, &(k, v): &'a (K, V)) { self.insert(k, v); } #[inline] #[cfg(feature = "nightly")] fn extend_reserve(&mut self, additional: usize) { Extend::<(K, V)>::extend_reserve(self, additional); } } #[allow(dead_code)] fn assert_covariance() { fn map_key<'new>(v: HashMap<&'static str, u8>) -> HashMap<&'new str, u8> { v } fn map_val<'new>(v: HashMap) -> HashMap { v } fn iter_key<'a, 'new>(v: Iter<'a, &'static str, u8>) -> Iter<'a, &'new str, u8> { v } fn iter_val<'a, 'new>(v: Iter<'a, u8, &'static str>) -> Iter<'a, u8, &'new str> { v } fn into_iter_key<'new, A: Allocator>( v: IntoIter<&'static str, u8, A>, ) -> IntoIter<&'new str, u8, A> { v } fn into_iter_val<'new, A: Allocator>( v: IntoIter, ) -> IntoIter { v } fn keys_key<'a, 'new>(v: Keys<'a, &'static str, u8>) -> Keys<'a, &'new str, u8> { v } fn keys_val<'a, 'new>(v: Keys<'a, u8, &'static str>) -> Keys<'a, u8, &'new str> { v } fn values_key<'a, 'new>(v: Values<'a, &'static str, u8>) -> Values<'a, &'new str, u8> { v } fn values_val<'a, 'new>(v: Values<'a, u8, &'static str>) -> Values<'a, u8, &'new str> { v } fn drain<'new>( d: Drain<'static, &'static str, &'static str>, ) -> Drain<'new, &'new str, &'new str> { d } } #[cfg(test)] mod test_map { use super::DefaultHashBuilder; use super::Entry::{Occupied, Vacant}; use super::EntryRef; use super::{HashMap, RawEntryMut}; use alloc::string::{String, ToString}; use alloc::sync::Arc; use allocator_api2::alloc::{AllocError, Allocator, Global}; use core::alloc::Layout; use core::ptr::NonNull; use core::sync::atomic::{AtomicI8, Ordering}; use rand::{rngs::SmallRng, Rng, SeedableRng}; use std::borrow::ToOwned; use std::cell::RefCell; use std::usize; use std::vec::Vec; #[test] fn test_zero_capacities() { type HM = HashMap; let m = HM::new(); assert_eq!(m.capacity(), 0); let m = HM::default(); assert_eq!(m.capacity(), 0); let m = HM::with_hasher(DefaultHashBuilder::default()); assert_eq!(m.capacity(), 0); let m = HM::with_capacity(0); assert_eq!(m.capacity(), 0); let m = HM::with_capacity_and_hasher(0, DefaultHashBuilder::default()); assert_eq!(m.capacity(), 0); let mut m = HM::new(); m.insert(1, 1); m.insert(2, 2); m.remove(&1); m.remove(&2); m.shrink_to_fit(); assert_eq!(m.capacity(), 0); let mut m = HM::new(); m.reserve(0); assert_eq!(m.capacity(), 0); } #[test] fn test_create_capacity_zero() { let mut m = HashMap::with_capacity(0); assert!(m.insert(1, 1).is_none()); assert!(m.contains_key(&1)); assert!(!m.contains_key(&0)); } #[test] fn test_insert() { let mut m = HashMap::new(); assert_eq!(m.len(), 0); assert!(m.insert(1, 2).is_none()); assert_eq!(m.len(), 1); assert!(m.insert(2, 4).is_none()); assert_eq!(m.len(), 2); assert_eq!(*m.get(&1).unwrap(), 2); assert_eq!(*m.get(&2).unwrap(), 4); } #[test] fn test_clone() { let mut m = HashMap::new(); assert_eq!(m.len(), 0); assert!(m.insert(1, 2).is_none()); assert_eq!(m.len(), 1); assert!(m.insert(2, 4).is_none()); assert_eq!(m.len(), 2); #[allow(clippy::redundant_clone)] let m2 = m.clone(); assert_eq!(*m2.get(&1).unwrap(), 2); assert_eq!(*m2.get(&2).unwrap(), 4); assert_eq!(m2.len(), 2); } #[test] fn test_clone_from() { let mut m = HashMap::new(); let mut m2 = HashMap::new(); assert_eq!(m.len(), 0); assert!(m.insert(1, 2).is_none()); assert_eq!(m.len(), 1); assert!(m.insert(2, 4).is_none()); assert_eq!(m.len(), 2); m2.clone_from(&m); assert_eq!(*m2.get(&1).unwrap(), 2); assert_eq!(*m2.get(&2).unwrap(), 4); assert_eq!(m2.len(), 2); } thread_local! { static DROP_VECTOR: RefCell> = const { RefCell::new(Vec::new()) } } #[derive(Hash, PartialEq, Eq)] struct Droppable { k: usize, } impl Droppable { fn new(k: usize) -> Droppable { DROP_VECTOR.with(|slot| { slot.borrow_mut()[k] += 1; }); Droppable { k } } } impl Drop for Droppable { fn drop(&mut self) { DROP_VECTOR.with(|slot| { slot.borrow_mut()[self.k] -= 1; }); } } impl Clone for Droppable { fn clone(&self) -> Self { Droppable::new(self.k) } } #[test] fn test_drops() { DROP_VECTOR.with(|slot| { *slot.borrow_mut() = vec![0; 200]; }); { let mut m = HashMap::new(); DROP_VECTOR.with(|v| { for i in 0..200 { assert_eq!(v.borrow()[i], 0); } }); for i in 0..100 { let d1 = Droppable::new(i); let d2 = Droppable::new(i + 100); m.insert(d1, d2); } DROP_VECTOR.with(|v| { for i in 0..200 { assert_eq!(v.borrow()[i], 1); } }); for i in 0..50 { let k = Droppable::new(i); let v = m.remove(&k); assert!(v.is_some()); DROP_VECTOR.with(|v| { assert_eq!(v.borrow()[i], 1); assert_eq!(v.borrow()[i + 100], 1); }); } DROP_VECTOR.with(|v| { for i in 0..50 { assert_eq!(v.borrow()[i], 0); assert_eq!(v.borrow()[i + 100], 0); } for i in 50..100 { assert_eq!(v.borrow()[i], 1); assert_eq!(v.borrow()[i + 100], 1); } }); } DROP_VECTOR.with(|v| { for i in 0..200 { assert_eq!(v.borrow()[i], 0); } }); } #[test] fn test_into_iter_drops() { DROP_VECTOR.with(|v| { *v.borrow_mut() = vec![0; 200]; }); let hm = { let mut hm = HashMap::new(); DROP_VECTOR.with(|v| { for i in 0..200 { assert_eq!(v.borrow()[i], 0); } }); for i in 0..100 { let d1 = Droppable::new(i); let d2 = Droppable::new(i + 100); hm.insert(d1, d2); } DROP_VECTOR.with(|v| { for i in 0..200 { assert_eq!(v.borrow()[i], 1); } }); hm }; // By the way, ensure that cloning doesn't screw up the dropping. drop(hm.clone()); { let mut half = hm.into_iter().take(50); DROP_VECTOR.with(|v| { for i in 0..200 { assert_eq!(v.borrow()[i], 1); } }); for _ in half.by_ref() {} DROP_VECTOR.with(|v| { let nk = (0..100).filter(|&i| v.borrow()[i] == 1).count(); let nv = (0..100).filter(|&i| v.borrow()[i + 100] == 1).count(); assert_eq!(nk, 50); assert_eq!(nv, 50); }); }; DROP_VECTOR.with(|v| { for i in 0..200 { assert_eq!(v.borrow()[i], 0); } }); } #[test] fn test_empty_remove() { let mut m: HashMap = HashMap::new(); assert_eq!(m.remove(&0), None); } #[test] fn test_empty_entry() { let mut m: HashMap = HashMap::new(); match m.entry(0) { Occupied(_) => panic!(), Vacant(_) => {} } assert!(*m.entry(0).or_insert(true)); assert_eq!(m.len(), 1); } #[test] fn test_empty_entry_ref() { let mut m: HashMap = HashMap::new(); match m.entry_ref("poneyland") { EntryRef::Occupied(_) => panic!(), EntryRef::Vacant(_) => {} } assert!(*m.entry_ref("poneyland").or_insert(true)); assert_eq!(m.len(), 1); } #[test] fn test_empty_iter() { let mut m: HashMap = HashMap::new(); assert_eq!(m.drain().next(), None); assert_eq!(m.keys().next(), None); assert_eq!(m.values().next(), None); assert_eq!(m.values_mut().next(), None); assert_eq!(m.iter().next(), None); assert_eq!(m.iter_mut().next(), None); assert_eq!(m.len(), 0); assert!(m.is_empty()); assert_eq!(m.into_iter().next(), None); } #[test] #[cfg_attr(miri, ignore)] // FIXME: takes too long fn test_lots_of_insertions() { let mut m = HashMap::new(); // Try this a few times to make sure we never screw up the hashmap's // internal state. for _ in 0..10 { assert!(m.is_empty()); for i in 1..1001 { assert!(m.insert(i, i).is_none()); for j in 1..=i { let r = m.get(&j); assert_eq!(r, Some(&j)); } for j in i + 1..1001 { let r = m.get(&j); assert_eq!(r, None); } } for i in 1001..2001 { assert!(!m.contains_key(&i)); } // remove forwards for i in 1..1001 { assert!(m.remove(&i).is_some()); for j in 1..=i { assert!(!m.contains_key(&j)); } for j in i + 1..1001 { assert!(m.contains_key(&j)); } } for i in 1..1001 { assert!(!m.contains_key(&i)); } for i in 1..1001 { assert!(m.insert(i, i).is_none()); } // remove backwards for i in (1..1001).rev() { assert!(m.remove(&i).is_some()); for j in i..1001 { assert!(!m.contains_key(&j)); } for j in 1..i { assert!(m.contains_key(&j)); } } } } #[test] fn test_find_mut() { let mut m = HashMap::new(); assert!(m.insert(1, 12).is_none()); assert!(m.insert(2, 8).is_none()); assert!(m.insert(5, 14).is_none()); let new = 100; match m.get_mut(&5) { None => panic!(), Some(x) => *x = new, } assert_eq!(m.get(&5), Some(&new)); } #[test] fn test_insert_overwrite() { let mut m = HashMap::new(); assert!(m.insert(1, 2).is_none()); assert_eq!(*m.get(&1).unwrap(), 2); assert!(m.insert(1, 3).is_some()); assert_eq!(*m.get(&1).unwrap(), 3); } #[test] fn test_insert_conflicts() { let mut m = HashMap::with_capacity(4); assert!(m.insert(1, 2).is_none()); assert!(m.insert(5, 3).is_none()); assert!(m.insert(9, 4).is_none()); assert_eq!(*m.get(&9).unwrap(), 4); assert_eq!(*m.get(&5).unwrap(), 3); assert_eq!(*m.get(&1).unwrap(), 2); } #[test] fn test_conflict_remove() { let mut m = HashMap::with_capacity(4); assert!(m.insert(1, 2).is_none()); assert_eq!(*m.get(&1).unwrap(), 2); assert!(m.insert(5, 3).is_none()); assert_eq!(*m.get(&1).unwrap(), 2); assert_eq!(*m.get(&5).unwrap(), 3); assert!(m.insert(9, 4).is_none()); assert_eq!(*m.get(&1).unwrap(), 2); assert_eq!(*m.get(&5).unwrap(), 3); assert_eq!(*m.get(&9).unwrap(), 4); assert!(m.remove(&1).is_some()); assert_eq!(*m.get(&9).unwrap(), 4); assert_eq!(*m.get(&5).unwrap(), 3); } #[test] fn test_insert_unique_unchecked() { let mut map = HashMap::new(); let (k1, v1) = map.insert_unique_unchecked(10, 11); assert_eq!((&10, &mut 11), (k1, v1)); let (k2, v2) = map.insert_unique_unchecked(20, 21); assert_eq!((&20, &mut 21), (k2, v2)); assert_eq!(Some(&11), map.get(&10)); assert_eq!(Some(&21), map.get(&20)); assert_eq!(None, map.get(&30)); } #[test] fn test_is_empty() { let mut m = HashMap::with_capacity(4); assert!(m.insert(1, 2).is_none()); assert!(!m.is_empty()); assert!(m.remove(&1).is_some()); assert!(m.is_empty()); } #[test] fn test_remove() { let mut m = HashMap::new(); m.insert(1, 2); assert_eq!(m.remove(&1), Some(2)); assert_eq!(m.remove(&1), None); } #[test] fn test_remove_entry() { let mut m = HashMap::new(); m.insert(1, 2); assert_eq!(m.remove_entry(&1), Some((1, 2))); assert_eq!(m.remove(&1), None); } #[test] fn test_iterate() { let mut m = HashMap::with_capacity(4); for i in 0..32 { assert!(m.insert(i, i * 2).is_none()); } assert_eq!(m.len(), 32); let mut observed: u32 = 0; for (k, v) in &m { assert_eq!(*v, *k * 2); observed |= 1 << *k; } assert_eq!(observed, 0xFFFF_FFFF); } #[test] fn test_keys() { let vec = vec![(1, 'a'), (2, 'b'), (3, 'c')]; let map: HashMap<_, _> = vec.into_iter().collect(); let keys: Vec<_> = map.keys().copied().collect(); assert_eq!(keys.len(), 3); assert!(keys.contains(&1)); assert!(keys.contains(&2)); assert!(keys.contains(&3)); } #[test] fn test_values() { let vec = vec![(1, 'a'), (2, 'b'), (3, 'c')]; let map: HashMap<_, _> = vec.into_iter().collect(); let values: Vec<_> = map.values().copied().collect(); assert_eq!(values.len(), 3); assert!(values.contains(&'a')); assert!(values.contains(&'b')); assert!(values.contains(&'c')); } #[test] fn test_values_mut() { let vec = vec![(1, 1), (2, 2), (3, 3)]; let mut map: HashMap<_, _> = vec.into_iter().collect(); for value in map.values_mut() { *value *= 2; } let values: Vec<_> = map.values().copied().collect(); assert_eq!(values.len(), 3); assert!(values.contains(&2)); assert!(values.contains(&4)); assert!(values.contains(&6)); } #[test] fn test_into_keys() { let vec = vec![(1, 'a'), (2, 'b'), (3, 'c')]; let map: HashMap<_, _> = vec.into_iter().collect(); let keys: Vec<_> = map.into_keys().collect(); assert_eq!(keys.len(), 3); assert!(keys.contains(&1)); assert!(keys.contains(&2)); assert!(keys.contains(&3)); } #[test] fn test_into_values() { let vec = vec![(1, 'a'), (2, 'b'), (3, 'c')]; let map: HashMap<_, _> = vec.into_iter().collect(); let values: Vec<_> = map.into_values().collect(); assert_eq!(values.len(), 3); assert!(values.contains(&'a')); assert!(values.contains(&'b')); assert!(values.contains(&'c')); } #[test] fn test_find() { let mut m = HashMap::new(); assert!(m.get(&1).is_none()); m.insert(1, 2); match m.get(&1) { None => panic!(), Some(v) => assert_eq!(*v, 2), } } #[test] fn test_eq() { let mut m1 = HashMap::new(); m1.insert(1, 2); m1.insert(2, 3); m1.insert(3, 4); let mut m2 = HashMap::new(); m2.insert(1, 2); m2.insert(2, 3); assert!(m1 != m2); m2.insert(3, 4); assert_eq!(m1, m2); } #[test] fn test_show() { let mut map = HashMap::new(); let empty: HashMap = HashMap::new(); map.insert(1, 2); map.insert(3, 4); let map_str = format!("{map:?}"); assert!(map_str == "{1: 2, 3: 4}" || map_str == "{3: 4, 1: 2}"); assert_eq!(format!("{empty:?}"), "{}"); } #[test] fn test_expand() { let mut m = HashMap::new(); assert_eq!(m.len(), 0); assert!(m.is_empty()); let mut i = 0; let old_raw_cap = m.raw_capacity(); while old_raw_cap == m.raw_capacity() { m.insert(i, i); i += 1; } assert_eq!(m.len(), i); assert!(!m.is_empty()); } #[test] fn test_behavior_resize_policy() { let mut m = HashMap::new(); assert_eq!(m.len(), 0); assert_eq!(m.raw_capacity(), 1); assert!(m.is_empty()); m.insert(0, 0); m.remove(&0); assert!(m.is_empty()); let initial_raw_cap = m.raw_capacity(); m.reserve(initial_raw_cap); let raw_cap = m.raw_capacity(); assert_eq!(raw_cap, initial_raw_cap * 2); let mut i = 0; for _ in 0..raw_cap * 3 / 4 { m.insert(i, i); i += 1; } // three quarters full assert_eq!(m.len(), i); assert_eq!(m.raw_capacity(), raw_cap); for _ in 0..raw_cap / 4 { m.insert(i, i); i += 1; } // half full let new_raw_cap = m.raw_capacity(); assert_eq!(new_raw_cap, raw_cap * 2); for _ in 0..raw_cap / 2 - 1 { i -= 1; m.remove(&i); assert_eq!(m.raw_capacity(), new_raw_cap); } // A little more than one quarter full. m.shrink_to_fit(); assert_eq!(m.raw_capacity(), raw_cap); // again, a little more than half full for _ in 0..raw_cap / 2 { i -= 1; m.remove(&i); } m.shrink_to_fit(); assert_eq!(m.len(), i); assert!(!m.is_empty()); assert_eq!(m.raw_capacity(), initial_raw_cap); } #[test] fn test_reserve_shrink_to_fit() { let mut m = HashMap::new(); m.insert(0, 0); m.remove(&0); assert!(m.capacity() >= m.len()); for i in 0..128 { m.insert(i, i); } m.reserve(256); let usable_cap = m.capacity(); for i in 128..(128 + 256) { m.insert(i, i); assert_eq!(m.capacity(), usable_cap); } for i in 100..(128 + 256) { assert_eq!(m.remove(&i), Some(i)); } m.shrink_to_fit(); assert_eq!(m.len(), 100); assert!(!m.is_empty()); assert!(m.capacity() >= m.len()); for i in 0..100 { assert_eq!(m.remove(&i), Some(i)); } m.shrink_to_fit(); m.insert(0, 0); assert_eq!(m.len(), 1); assert!(m.capacity() >= m.len()); assert_eq!(m.remove(&0), Some(0)); } #[test] fn test_from_iter() { let xs = [(1, 1), (2, 2), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; let map: HashMap<_, _> = xs.iter().copied().collect(); for &(k, v) in &xs { assert_eq!(map.get(&k), Some(&v)); } assert_eq!(map.iter().len(), xs.len() - 1); } #[test] fn test_size_hint() { let xs = [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; let map: HashMap<_, _> = xs.iter().copied().collect(); let mut iter = map.iter(); for _ in iter.by_ref().take(3) {} assert_eq!(iter.size_hint(), (3, Some(3))); } #[test] fn test_iter_len() { let xs = [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; let map: HashMap<_, _> = xs.iter().copied().collect(); let mut iter = map.iter(); for _ in iter.by_ref().take(3) {} assert_eq!(iter.len(), 3); } #[test] fn test_mut_size_hint() { let xs = [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; let mut map: HashMap<_, _> = xs.iter().copied().collect(); let mut iter = map.iter_mut(); for _ in iter.by_ref().take(3) {} assert_eq!(iter.size_hint(), (3, Some(3))); } #[test] fn test_iter_mut_len() { let xs = [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; let mut map: HashMap<_, _> = xs.iter().copied().collect(); let mut iter = map.iter_mut(); for _ in iter.by_ref().take(3) {} assert_eq!(iter.len(), 3); } #[test] fn test_index() { let mut map = HashMap::new(); map.insert(1, 2); map.insert(2, 1); map.insert(3, 4); assert_eq!(map[&2], 1); } #[test] #[should_panic] fn test_index_nonexistent() { let mut map = HashMap::new(); map.insert(1, 2); map.insert(2, 1); map.insert(3, 4); #[allow(clippy::no_effect)] // false positive lint map[&4]; } #[test] fn test_entry() { let xs = [(1, 10), (2, 20), (3, 30), (4, 40), (5, 50), (6, 60)]; let mut map: HashMap<_, _> = xs.iter().copied().collect(); // Existing key (insert) match map.entry(1) { Vacant(_) => unreachable!(), Occupied(mut view) => { assert_eq!(view.get(), &10); assert_eq!(view.insert(100), 10); } } assert_eq!(map.get(&1).unwrap(), &100); assert_eq!(map.len(), 6); // Existing key (update) match map.entry(2) { Vacant(_) => unreachable!(), Occupied(mut view) => { let v = view.get_mut(); let new_v = (*v) * 10; *v = new_v; } } assert_eq!(map.get(&2).unwrap(), &200); assert_eq!(map.len(), 6); // Existing key (take) match map.entry(3) { Vacant(_) => unreachable!(), Occupied(view) => { assert_eq!(view.remove(), 30); } } assert_eq!(map.get(&3), None); assert_eq!(map.len(), 5); // Inexistent key (insert) match map.entry(10) { Occupied(_) => unreachable!(), Vacant(view) => { assert_eq!(*view.insert(1000), 1000); } } assert_eq!(map.get(&10).unwrap(), &1000); assert_eq!(map.len(), 6); } #[test] fn test_entry_ref() { let xs = [ ("One".to_owned(), 10), ("Two".to_owned(), 20), ("Three".to_owned(), 30), ("Four".to_owned(), 40), ("Five".to_owned(), 50), ("Six".to_owned(), 60), ]; let mut map: HashMap<_, _> = xs.iter().cloned().collect(); // Existing key (insert) match map.entry_ref("One") { EntryRef::Vacant(_) => unreachable!(), EntryRef::Occupied(mut view) => { assert_eq!(view.get(), &10); assert_eq!(view.insert(100), 10); } } assert_eq!(map.get("One").unwrap(), &100); assert_eq!(map.len(), 6); // Existing key (update) match map.entry_ref("Two") { EntryRef::Vacant(_) => unreachable!(), EntryRef::Occupied(mut view) => { let v = view.get_mut(); let new_v = (*v) * 10; *v = new_v; } } assert_eq!(map.get("Two").unwrap(), &200); assert_eq!(map.len(), 6); // Existing key (take) match map.entry_ref("Three") { EntryRef::Vacant(_) => unreachable!(), EntryRef::Occupied(view) => { assert_eq!(view.remove(), 30); } } assert_eq!(map.get("Three"), None); assert_eq!(map.len(), 5); // Inexistent key (insert) match map.entry_ref("Ten") { EntryRef::Occupied(_) => unreachable!(), EntryRef::Vacant(view) => { assert_eq!(*view.insert(1000), 1000); } } assert_eq!(map.get("Ten").unwrap(), &1000); assert_eq!(map.len(), 6); } #[test] fn test_entry_take_doesnt_corrupt() { #![allow(deprecated)] //rand // Test for #19292 fn check(m: &HashMap) { for k in m.keys() { assert!(m.contains_key(k), "{k} is in keys() but not in the map?"); } } let mut m = HashMap::new(); let mut rng = { let seed = u64::from_le_bytes(*b"testseed"); SmallRng::seed_from_u64(seed) }; // Populate the map with some items. for _ in 0..50 { let x = rng.gen_range(-10..10); m.insert(x, ()); } for _ in 0..1000 { let x = rng.gen_range(-10..10); match m.entry(x) { Vacant(_) => {} Occupied(e) => { e.remove(); } } check(&m); } } #[test] fn test_entry_ref_take_doesnt_corrupt() { #![allow(deprecated)] //rand // Test for #19292 fn check(m: &HashMap) { for k in m.keys() { assert!(m.contains_key(k), "{k} is in keys() but not in the map?"); } } let mut m = HashMap::new(); let mut rng = { let seed = u64::from_le_bytes(*b"testseed"); SmallRng::seed_from_u64(seed) }; // Populate the map with some items. for _ in 0..50 { let mut x = std::string::String::with_capacity(1); x.push(rng.gen_range('a'..='z')); m.insert(x, ()); } for _ in 0..1000 { let mut x = std::string::String::with_capacity(1); x.push(rng.gen_range('a'..='z')); match m.entry_ref(x.as_str()) { EntryRef::Vacant(_) => {} EntryRef::Occupied(e) => { e.remove(); } } check(&m); } } #[test] fn test_extend_ref_k_ref_v() { let mut a = HashMap::new(); a.insert(1, "one"); let mut b = HashMap::new(); b.insert(2, "two"); b.insert(3, "three"); a.extend(&b); assert_eq!(a.len(), 3); assert_eq!(a[&1], "one"); assert_eq!(a[&2], "two"); assert_eq!(a[&3], "three"); } #[test] #[allow(clippy::needless_borrow)] fn test_extend_ref_kv_tuple() { use std::ops::AddAssign; let mut a = HashMap::new(); a.insert(0, 0); fn create_arr + Copy, const N: usize>(start: T, step: T) -> [(T, T); N] { let mut outs: [(T, T); N] = [(start, start); N]; let mut element = step; outs.iter_mut().skip(1).for_each(|(k, v)| { *k += element; *v += element; element += step; }); outs } let for_iter: Vec<_> = (0..100).map(|i| (i, i)).collect(); let iter = for_iter.iter(); let vec: Vec<_> = (100..200).map(|i| (i, i)).collect(); a.extend(iter); a.extend(&vec); a.extend(create_arr::(200, 1)); assert_eq!(a.len(), 300); for item in 0..300 { assert_eq!(a[&item], item); } } #[test] fn test_capacity_not_less_than_len() { let mut a = HashMap::new(); let mut item = 0; for _ in 0..116 { a.insert(item, 0); item += 1; } assert!(a.capacity() > a.len()); let free = a.capacity() - a.len(); for _ in 0..free { a.insert(item, 0); item += 1; } assert_eq!(a.len(), a.capacity()); // Insert at capacity should cause allocation. a.insert(item, 0); assert!(a.capacity() > a.len()); } #[test] fn test_occupied_entry_key() { let mut a = HashMap::new(); let key = "hello there"; let value = "value goes here"; assert!(a.is_empty()); a.insert(key, value); assert_eq!(a.len(), 1); assert_eq!(a[key], value); match a.entry(key) { Vacant(_) => panic!(), Occupied(e) => assert_eq!(key, *e.key()), } assert_eq!(a.len(), 1); assert_eq!(a[key], value); } #[test] fn test_occupied_entry_ref_key() { let mut a = HashMap::new(); let key = "hello there"; let value = "value goes here"; assert!(a.is_empty()); a.insert(key.to_owned(), value); assert_eq!(a.len(), 1); assert_eq!(a[key], value); match a.entry_ref(key) { EntryRef::Vacant(_) => panic!(), EntryRef::Occupied(e) => assert_eq!(key, e.key()), } assert_eq!(a.len(), 1); assert_eq!(a[key], value); } #[test] fn test_vacant_entry_key() { let mut a = HashMap::new(); let key = "hello there"; let value = "value goes here"; assert!(a.is_empty()); match a.entry(key) { Occupied(_) => panic!(), Vacant(e) => { assert_eq!(key, *e.key()); e.insert(value); } } assert_eq!(a.len(), 1); assert_eq!(a[key], value); } #[test] fn test_vacant_entry_ref_key() { let mut a: HashMap = HashMap::new(); let key = "hello there"; let value = "value goes here"; assert!(a.is_empty()); match a.entry_ref(key) { EntryRef::Occupied(_) => panic!(), EntryRef::Vacant(e) => { assert_eq!(key, e.key()); e.insert(value); } } assert_eq!(a.len(), 1); assert_eq!(a[key], value); } #[test] fn test_occupied_entry_replace_entry_with() { let mut a = HashMap::new(); let key = "a key"; let value = "an initial value"; let new_value = "a new value"; let entry = a.entry(key).insert(value).replace_entry_with(|k, v| { assert_eq!(k, &key); assert_eq!(v, value); Some(new_value) }); match entry { Occupied(e) => { assert_eq!(e.key(), &key); assert_eq!(e.get(), &new_value); } Vacant(_) => panic!(), } assert_eq!(a[key], new_value); assert_eq!(a.len(), 1); let entry = match a.entry(key) { Occupied(e) => e.replace_entry_with(|k, v| { assert_eq!(k, &key); assert_eq!(v, new_value); None }), Vacant(_) => panic!(), }; match entry { Vacant(e) => assert_eq!(e.key(), &key), Occupied(_) => panic!(), } assert!(!a.contains_key(key)); assert_eq!(a.len(), 0); } #[test] fn test_occupied_entry_ref_replace_entry_with() { let mut a: HashMap = HashMap::new(); let key = "a key"; let value = "an initial value"; let new_value = "a new value"; let entry = a.entry_ref(key).insert(value).replace_entry_with(|k, v| { assert_eq!(k, key); assert_eq!(v, value); Some(new_value) }); match entry { EntryRef::Occupied(e) => { assert_eq!(e.key(), key); assert_eq!(e.get(), &new_value); } EntryRef::Vacant(_) => panic!(), } assert_eq!(a[key], new_value); assert_eq!(a.len(), 1); let entry = match a.entry_ref(key) { EntryRef::Occupied(e) => e.replace_entry_with(|k, v| { assert_eq!(k, key); assert_eq!(v, new_value); None }), EntryRef::Vacant(_) => panic!(), }; match entry { EntryRef::Vacant(e) => assert_eq!(e.key(), key), EntryRef::Occupied(_) => panic!(), } assert!(!a.contains_key(key)); assert_eq!(a.len(), 0); } #[test] fn test_entry_and_replace_entry_with() { let mut a = HashMap::new(); let key = "a key"; let value = "an initial value"; let new_value = "a new value"; let entry = a.entry(key).and_replace_entry_with(|_, _| panic!()); match entry { Vacant(e) => assert_eq!(e.key(), &key), Occupied(_) => panic!(), } a.insert(key, value); let entry = a.entry(key).and_replace_entry_with(|k, v| { assert_eq!(k, &key); assert_eq!(v, value); Some(new_value) }); match entry { Occupied(e) => { assert_eq!(e.key(), &key); assert_eq!(e.get(), &new_value); } Vacant(_) => panic!(), } assert_eq!(a[key], new_value); assert_eq!(a.len(), 1); let entry = a.entry(key).and_replace_entry_with(|k, v| { assert_eq!(k, &key); assert_eq!(v, new_value); None }); match entry { Vacant(e) => assert_eq!(e.key(), &key), Occupied(_) => panic!(), } assert!(!a.contains_key(key)); assert_eq!(a.len(), 0); } #[test] fn test_entry_ref_and_replace_entry_with() { let mut a = HashMap::new(); let key = "a key"; let value = "an initial value"; let new_value = "a new value"; let entry = a.entry_ref(key).and_replace_entry_with(|_, _| panic!()); match entry { EntryRef::Vacant(e) => assert_eq!(e.key(), key), EntryRef::Occupied(_) => panic!(), } a.insert(key.to_owned(), value); let entry = a.entry_ref(key).and_replace_entry_with(|k, v| { assert_eq!(k, key); assert_eq!(v, value); Some(new_value) }); match entry { EntryRef::Occupied(e) => { assert_eq!(e.key(), key); assert_eq!(e.get(), &new_value); } EntryRef::Vacant(_) => panic!(), } assert_eq!(a[key], new_value); assert_eq!(a.len(), 1); let entry = a.entry_ref(key).and_replace_entry_with(|k, v| { assert_eq!(k, key); assert_eq!(v, new_value); None }); match entry { EntryRef::Vacant(e) => assert_eq!(e.key(), key), EntryRef::Occupied(_) => panic!(), } assert!(!a.contains_key(key)); assert_eq!(a.len(), 0); } #[test] fn test_raw_occupied_entry_replace_entry_with() { let mut a = HashMap::new(); let key = "a key"; let value = "an initial value"; let new_value = "a new value"; let entry = a .raw_entry_mut() .from_key(&key) .insert(key, value) .replace_entry_with(|k, v| { assert_eq!(k, &key); assert_eq!(v, value); Some(new_value) }); match entry { RawEntryMut::Occupied(e) => { assert_eq!(e.key(), &key); assert_eq!(e.get(), &new_value); } RawEntryMut::Vacant(_) => panic!(), } assert_eq!(a[key], new_value); assert_eq!(a.len(), 1); let entry = match a.raw_entry_mut().from_key(&key) { RawEntryMut::Occupied(e) => e.replace_entry_with(|k, v| { assert_eq!(k, &key); assert_eq!(v, new_value); None }), RawEntryMut::Vacant(_) => panic!(), }; match entry { RawEntryMut::Vacant(_) => {} RawEntryMut::Occupied(_) => panic!(), } assert!(!a.contains_key(key)); assert_eq!(a.len(), 0); } #[test] fn test_raw_entry_and_replace_entry_with() { let mut a = HashMap::new(); let key = "a key"; let value = "an initial value"; let new_value = "a new value"; let entry = a .raw_entry_mut() .from_key(&key) .and_replace_entry_with(|_, _| panic!()); match entry { RawEntryMut::Vacant(_) => {} RawEntryMut::Occupied(_) => panic!(), } a.insert(key, value); let entry = a .raw_entry_mut() .from_key(&key) .and_replace_entry_with(|k, v| { assert_eq!(k, &key); assert_eq!(v, value); Some(new_value) }); match entry { RawEntryMut::Occupied(e) => { assert_eq!(e.key(), &key); assert_eq!(e.get(), &new_value); } RawEntryMut::Vacant(_) => panic!(), } assert_eq!(a[key], new_value); assert_eq!(a.len(), 1); let entry = a .raw_entry_mut() .from_key(&key) .and_replace_entry_with(|k, v| { assert_eq!(k, &key); assert_eq!(v, new_value); None }); match entry { RawEntryMut::Vacant(_) => {} RawEntryMut::Occupied(_) => panic!(), } assert!(!a.contains_key(key)); assert_eq!(a.len(), 0); } #[test] fn test_replace_entry_with_doesnt_corrupt() { #![allow(deprecated)] //rand // Test for #19292 fn check(m: &HashMap) { for k in m.keys() { assert!(m.contains_key(k), "{k} is in keys() but not in the map?"); } } let mut m = HashMap::new(); let mut rng = { let seed = u64::from_le_bytes(*b"testseed"); SmallRng::seed_from_u64(seed) }; // Populate the map with some items. for _ in 0..50 { let x = rng.gen_range(-10..10); m.insert(x, ()); } for _ in 0..1000 { let x = rng.gen_range(-10..10); m.entry(x).and_replace_entry_with(|_, _| None); check(&m); } } #[test] fn test_replace_entry_ref_with_doesnt_corrupt() { #![allow(deprecated)] //rand // Test for #19292 fn check(m: &HashMap) { for k in m.keys() { assert!(m.contains_key(k), "{k} is in keys() but not in the map?"); } } let mut m = HashMap::new(); let mut rng = { let seed = u64::from_le_bytes(*b"testseed"); SmallRng::seed_from_u64(seed) }; // Populate the map with some items. for _ in 0..50 { let mut x = std::string::String::with_capacity(1); x.push(rng.gen_range('a'..='z')); m.insert(x, ()); } for _ in 0..1000 { let mut x = std::string::String::with_capacity(1); x.push(rng.gen_range('a'..='z')); m.entry_ref(x.as_str()).and_replace_entry_with(|_, _| None); check(&m); } } #[test] fn test_retain() { let mut map: HashMap = (0..100).map(|x| (x, x * 10)).collect(); map.retain(|&k, _| k % 2 == 0); assert_eq!(map.len(), 50); assert_eq!(map[&2], 20); assert_eq!(map[&4], 40); assert_eq!(map[&6], 60); } #[test] fn test_extract_if() { { let mut map: HashMap = (0..8).map(|x| (x, x * 10)).collect(); let drained = map.extract_if(|&k, _| k % 2 == 0); let mut out = drained.collect::>(); out.sort_unstable(); assert_eq!(vec![(0, 0), (2, 20), (4, 40), (6, 60)], out); assert_eq!(map.len(), 4); } { let mut map: HashMap = (0..8).map(|x| (x, x * 10)).collect(); map.extract_if(|&k, _| k % 2 == 0).for_each(drop); assert_eq!(map.len(), 4); } } #[test] #[cfg_attr(miri, ignore)] // FIXME: no OOM signalling (https://github.com/rust-lang/miri/issues/613) fn test_try_reserve() { use crate::TryReserveError::{AllocError, CapacityOverflow}; const MAX_ISIZE: usize = isize::MAX as usize; let mut empty_bytes: HashMap = HashMap::new(); if let Err(CapacityOverflow) = empty_bytes.try_reserve(usize::MAX) { } else { panic!("usize::MAX should trigger an overflow!"); } if let Err(CapacityOverflow) = empty_bytes.try_reserve(MAX_ISIZE) { } else { panic!("isize::MAX should trigger an overflow!"); } if let Err(AllocError { .. }) = empty_bytes.try_reserve(MAX_ISIZE / 5) { } else { // This may succeed if there is enough free memory. Attempt to // allocate a few more hashmaps to ensure the allocation will fail. let mut empty_bytes2: HashMap = HashMap::new(); let _ = empty_bytes2.try_reserve(MAX_ISIZE / 5); let mut empty_bytes3: HashMap = HashMap::new(); let _ = empty_bytes3.try_reserve(MAX_ISIZE / 5); let mut empty_bytes4: HashMap = HashMap::new(); if let Err(AllocError { .. }) = empty_bytes4.try_reserve(MAX_ISIZE / 5) { } else { panic!("isize::MAX / 5 should trigger an OOM!"); } } } #[test] fn test_raw_entry() { use super::RawEntryMut::{Occupied, Vacant}; let xs = [(1_i32, 10_i32), (2, 20), (3, 30), (4, 40), (5, 50), (6, 60)]; let mut map: HashMap<_, _> = xs.iter().copied().collect(); let compute_hash = |map: &HashMap, k: i32| -> u64 { super::make_hash::(map.hasher(), &k) }; // Existing key (insert) match map.raw_entry_mut().from_key(&1) { Vacant(_) => unreachable!(), Occupied(mut view) => { assert_eq!(view.get(), &10); assert_eq!(view.insert(100), 10); } } let hash1 = compute_hash(&map, 1); assert_eq!(map.raw_entry().from_key(&1).unwrap(), (&1, &100)); assert_eq!( map.raw_entry().from_hash(hash1, |k| *k == 1).unwrap(), (&1, &100) ); assert_eq!( map.raw_entry().from_key_hashed_nocheck(hash1, &1).unwrap(), (&1, &100) ); assert_eq!(map.len(), 6); // Existing key (update) match map.raw_entry_mut().from_key(&2) { Vacant(_) => unreachable!(), Occupied(mut view) => { let v = view.get_mut(); let new_v = (*v) * 10; *v = new_v; } } let hash2 = compute_hash(&map, 2); assert_eq!(map.raw_entry().from_key(&2).unwrap(), (&2, &200)); assert_eq!( map.raw_entry().from_hash(hash2, |k| *k == 2).unwrap(), (&2, &200) ); assert_eq!( map.raw_entry().from_key_hashed_nocheck(hash2, &2).unwrap(), (&2, &200) ); assert_eq!(map.len(), 6); // Existing key (take) let hash3 = compute_hash(&map, 3); match map.raw_entry_mut().from_key_hashed_nocheck(hash3, &3) { Vacant(_) => unreachable!(), Occupied(view) => { assert_eq!(view.remove_entry(), (3, 30)); } } assert_eq!(map.raw_entry().from_key(&3), None); assert_eq!(map.raw_entry().from_hash(hash3, |k| *k == 3), None); assert_eq!(map.raw_entry().from_key_hashed_nocheck(hash3, &3), None); assert_eq!(map.len(), 5); // Nonexistent key (insert) match map.raw_entry_mut().from_key(&10) { Occupied(_) => unreachable!(), Vacant(view) => { assert_eq!(view.insert(10, 1000), (&mut 10, &mut 1000)); } } assert_eq!(map.raw_entry().from_key(&10).unwrap(), (&10, &1000)); assert_eq!(map.len(), 6); // Ensure all lookup methods produce equivalent results. for k in 0..12 { let hash = compute_hash(&map, k); let v = map.get(&k).copied(); let kv = v.as_ref().map(|v| (&k, v)); assert_eq!(map.raw_entry().from_key(&k), kv); assert_eq!(map.raw_entry().from_hash(hash, |q| *q == k), kv); assert_eq!(map.raw_entry().from_key_hashed_nocheck(hash, &k), kv); match map.raw_entry_mut().from_key(&k) { Occupied(o) => assert_eq!(Some(o.get_key_value()), kv), Vacant(_) => assert_eq!(v, None), } match map.raw_entry_mut().from_key_hashed_nocheck(hash, &k) { Occupied(o) => assert_eq!(Some(o.get_key_value()), kv), Vacant(_) => assert_eq!(v, None), } match map.raw_entry_mut().from_hash(hash, |q| *q == k) { Occupied(o) => assert_eq!(Some(o.get_key_value()), kv), Vacant(_) => assert_eq!(v, None), } } } #[test] fn test_key_without_hash_impl() { #[derive(Debug)] struct IntWrapper(u64); let mut m: HashMap = HashMap::default(); { assert!(m.raw_entry().from_hash(0, |k| k.0 == 0).is_none()); } { let vacant_entry = match m.raw_entry_mut().from_hash(0, |k| k.0 == 0) { RawEntryMut::Occupied(..) => panic!("Found entry for key 0"), RawEntryMut::Vacant(e) => e, }; vacant_entry.insert_with_hasher(0, IntWrapper(0), (), |k| k.0); } { assert!(m.raw_entry().from_hash(0, |k| k.0 == 0).is_some()); assert!(m.raw_entry().from_hash(1, |k| k.0 == 1).is_none()); assert!(m.raw_entry().from_hash(2, |k| k.0 == 2).is_none()); } { let vacant_entry = match m.raw_entry_mut().from_hash(1, |k| k.0 == 1) { RawEntryMut::Occupied(..) => panic!("Found entry for key 1"), RawEntryMut::Vacant(e) => e, }; vacant_entry.insert_with_hasher(1, IntWrapper(1), (), |k| k.0); } { assert!(m.raw_entry().from_hash(0, |k| k.0 == 0).is_some()); assert!(m.raw_entry().from_hash(1, |k| k.0 == 1).is_some()); assert!(m.raw_entry().from_hash(2, |k| k.0 == 2).is_none()); } { let occupied_entry = match m.raw_entry_mut().from_hash(0, |k| k.0 == 0) { RawEntryMut::Occupied(e) => e, RawEntryMut::Vacant(..) => panic!("Couldn't find entry for key 0"), }; occupied_entry.remove(); } assert!(m.raw_entry().from_hash(0, |k| k.0 == 0).is_none()); assert!(m.raw_entry().from_hash(1, |k| k.0 == 1).is_some()); assert!(m.raw_entry().from_hash(2, |k| k.0 == 2).is_none()); } #[test] #[cfg(feature = "raw")] fn test_into_iter_refresh() { #[cfg(miri)] const N: usize = 32; #[cfg(not(miri))] const N: usize = 128; let mut rng = rand::thread_rng(); for n in 0..N { let mut map = HashMap::new(); for i in 0..n { assert!(map.insert(i, 2 * i).is_none()); } let hash_builder = map.hasher().clone(); let mut it = unsafe { map.table.iter() }; assert_eq!(it.len(), n); let mut i = 0; let mut left = n; let mut removed = Vec::new(); loop { // occasionally remove some elements if i < n && rng.gen_bool(0.1) { let hash_value = super::make_hash(&hash_builder, &i); unsafe { let e = map.table.find(hash_value, |q| q.0.eq(&i)); if let Some(e) = e { it.reflect_remove(&e); let t = map.table.remove(e).0; removed.push(t); left -= 1; } else { assert!(removed.contains(&(i, 2 * i)), "{i} not in {removed:?}"); let e = map.table.insert( hash_value, (i, 2 * i), super::make_hasher::<_, usize, _>(&hash_builder), ); it.reflect_insert(&e); if let Some(p) = removed.iter().position(|e| e == &(i, 2 * i)) { removed.swap_remove(p); } left += 1; } } } let e = it.next(); if e.is_none() { break; } assert!(i < n); let t = unsafe { e.unwrap().as_ref() }; assert!(!removed.contains(t)); let (key, value) = t; assert_eq!(*value, 2 * key); i += 1; } assert!(i <= n); // just for safety: assert_eq!(map.table.len(), left); } } #[test] fn test_const_with_hasher() { use core::hash::BuildHasher; use std::collections::hash_map::DefaultHasher; #[derive(Clone)] struct MyHasher; impl BuildHasher for MyHasher { type Hasher = DefaultHasher; fn build_hasher(&self) -> DefaultHasher { DefaultHasher::new() } } const EMPTY_MAP: HashMap = HashMap::with_hasher(MyHasher); let mut map = EMPTY_MAP; map.insert(17, "seventeen".to_owned()); assert_eq!("seventeen", map[&17]); } #[test] fn test_get_each_mut() { let mut map = HashMap::new(); map.insert("foo".to_owned(), 0); map.insert("bar".to_owned(), 10); map.insert("baz".to_owned(), 20); map.insert("qux".to_owned(), 30); let xs = map.get_many_mut(["foo", "qux"]); assert_eq!(xs, Some([&mut 0, &mut 30])); let xs = map.get_many_mut(["foo", "dud"]); assert_eq!(xs, None); let xs = map.get_many_mut(["foo", "foo"]); assert_eq!(xs, None); let ys = map.get_many_key_value_mut(["bar", "baz"]); assert_eq!( ys, Some([(&"bar".to_owned(), &mut 10), (&"baz".to_owned(), &mut 20),]), ); let ys = map.get_many_key_value_mut(["bar", "dip"]); assert_eq!(ys, None); let ys = map.get_many_key_value_mut(["baz", "baz"]); assert_eq!(ys, None); } #[test] #[should_panic = "panic in drop"] fn test_clone_from_double_drop() { #[derive(Clone)] struct CheckedDrop { panic_in_drop: bool, dropped: bool, } impl Drop for CheckedDrop { fn drop(&mut self) { if self.panic_in_drop { self.dropped = true; panic!("panic in drop"); } if self.dropped { panic!("double drop"); } self.dropped = true; } } const DISARMED: CheckedDrop = CheckedDrop { panic_in_drop: false, dropped: false, }; const ARMED: CheckedDrop = CheckedDrop { panic_in_drop: true, dropped: false, }; let mut map1 = HashMap::new(); map1.insert(1, DISARMED); map1.insert(2, DISARMED); map1.insert(3, DISARMED); map1.insert(4, DISARMED); let mut map2 = HashMap::new(); map2.insert(1, DISARMED); map2.insert(2, ARMED); map2.insert(3, DISARMED); map2.insert(4, DISARMED); map2.clone_from(&map1); } #[test] #[should_panic = "panic in clone"] fn test_clone_from_memory_leaks() { use alloc::vec::Vec; struct CheckedClone { panic_in_clone: bool, need_drop: Vec, } impl Clone for CheckedClone { fn clone(&self) -> Self { if self.panic_in_clone { panic!("panic in clone") } Self { panic_in_clone: self.panic_in_clone, need_drop: self.need_drop.clone(), } } } let mut map1 = HashMap::new(); map1.insert( 1, CheckedClone { panic_in_clone: false, need_drop: vec![0, 1, 2], }, ); map1.insert( 2, CheckedClone { panic_in_clone: false, need_drop: vec![3, 4, 5], }, ); map1.insert( 3, CheckedClone { panic_in_clone: true, need_drop: vec![6, 7, 8], }, ); let _map2 = map1.clone(); } struct MyAllocInner { drop_count: Arc, } #[derive(Clone)] struct MyAlloc { _inner: Arc, } impl MyAlloc { fn new(drop_count: Arc) -> Self { MyAlloc { _inner: Arc::new(MyAllocInner { drop_count }), } } } impl Drop for MyAllocInner { fn drop(&mut self) { println!("MyAlloc freed."); self.drop_count.fetch_sub(1, Ordering::SeqCst); } } unsafe impl Allocator for MyAlloc { fn allocate(&self, layout: Layout) -> std::result::Result, AllocError> { let g = Global; g.allocate(layout) } unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { let g = Global; g.deallocate(ptr, layout) } } #[test] fn test_hashmap_into_iter_bug() { let dropped: Arc = Arc::new(AtomicI8::new(1)); { let mut map = HashMap::with_capacity_in(10, MyAlloc::new(dropped.clone())); for i in 0..10 { map.entry(i).or_insert_with(|| "i".to_string()); } for (k, v) in map { println!("{}, {}", k, v); } } // All allocator clones should already be dropped. assert_eq!(dropped.load(Ordering::SeqCst), 0); } #[derive(Debug)] struct CheckedCloneDrop { panic_in_clone: bool, panic_in_drop: bool, dropped: bool, data: T, } impl CheckedCloneDrop { fn new(panic_in_clone: bool, panic_in_drop: bool, data: T) -> Self { CheckedCloneDrop { panic_in_clone, panic_in_drop, dropped: false, data, } } } impl Clone for CheckedCloneDrop { fn clone(&self) -> Self { if self.panic_in_clone { panic!("panic in clone") } Self { panic_in_clone: self.panic_in_clone, panic_in_drop: self.panic_in_drop, dropped: self.dropped, data: self.data.clone(), } } } impl Drop for CheckedCloneDrop { fn drop(&mut self) { if self.panic_in_drop { self.dropped = true; panic!("panic in drop"); } if self.dropped { panic!("double drop"); } self.dropped = true; } } /// Return hashmap with predefined distribution of elements. /// All elements will be located in the same order as elements /// returned by iterator. /// /// This function does not panic, but returns an error as a `String` /// to distinguish between a test panic and an error in the input data. fn get_test_map( iter: I, mut fun: impl FnMut(u64) -> T, alloc: A, ) -> Result, DefaultHashBuilder, A>, String> where I: Iterator + Clone + ExactSizeIterator, A: Allocator, T: PartialEq + core::fmt::Debug, { use crate::scopeguard::guard; let mut map: HashMap, _, A> = HashMap::with_capacity_in(iter.size_hint().0, alloc); { let mut guard = guard(&mut map, |map| { for (_, value) in map.iter_mut() { value.panic_in_drop = false } }); let mut count = 0; // Hash and Key must be equal to each other for controlling the elements placement. for (panic_in_clone, panic_in_drop) in iter.clone() { if core::mem::needs_drop::() && panic_in_drop { return Err(String::from( "panic_in_drop can be set with a type that doesn't need to be dropped", )); } guard.table.insert( count, ( count, CheckedCloneDrop::new(panic_in_clone, panic_in_drop, fun(count)), ), |(k, _)| *k, ); count += 1; } // Let's check that all elements are located as we wanted let mut check_count = 0; for ((key, value), (panic_in_clone, panic_in_drop)) in guard.iter().zip(iter) { if *key != check_count { return Err(format!( "key != check_count,\nkey: `{}`,\ncheck_count: `{}`", key, check_count )); } if value.dropped || value.panic_in_clone != panic_in_clone || value.panic_in_drop != panic_in_drop || value.data != fun(check_count) { return Err(format!( "Value is not equal to expected,\nvalue: `{:?}`,\nexpected: \ `CheckedCloneDrop {{ panic_in_clone: {}, panic_in_drop: {}, dropped: {}, data: {:?} }}`", value, panic_in_clone, panic_in_drop, false, fun(check_count) )); } check_count += 1; } if guard.len() != check_count as usize { return Err(format!( "map.len() != check_count,\nmap.len(): `{}`,\ncheck_count: `{}`", guard.len(), check_count )); } if count != check_count { return Err(format!( "count != check_count,\ncount: `{}`,\ncheck_count: `{}`", count, check_count )); } core::mem::forget(guard); } Ok(map) } const DISARMED: bool = false; const ARMED: bool = true; const ARMED_FLAGS: [bool; 8] = [ DISARMED, DISARMED, DISARMED, ARMED, DISARMED, DISARMED, DISARMED, DISARMED, ]; const DISARMED_FLAGS: [bool; 8] = [ DISARMED, DISARMED, DISARMED, DISARMED, DISARMED, DISARMED, DISARMED, DISARMED, ]; #[test] #[should_panic = "panic in clone"] fn test_clone_memory_leaks_and_double_drop_one() { let dropped: Arc = Arc::new(AtomicI8::new(2)); { assert_eq!(ARMED_FLAGS.len(), DISARMED_FLAGS.len()); let map: HashMap>, DefaultHashBuilder, MyAlloc> = match get_test_map( ARMED_FLAGS.into_iter().zip(DISARMED_FLAGS), |n| vec![n], MyAlloc::new(dropped.clone()), ) { Ok(map) => map, Err(msg) => panic!("{msg}"), }; // Clone should normally clone a few elements, and then (when the // clone function panics), deallocate both its own memory, memory // of `dropped: Arc` and the memory of already cloned // elements (Vec memory inside CheckedCloneDrop). let _map2 = map.clone(); } } #[test] #[should_panic = "panic in drop"] fn test_clone_memory_leaks_and_double_drop_two() { let dropped: Arc = Arc::new(AtomicI8::new(2)); { assert_eq!(ARMED_FLAGS.len(), DISARMED_FLAGS.len()); let map: HashMap, DefaultHashBuilder, _> = match get_test_map( DISARMED_FLAGS.into_iter().zip(DISARMED_FLAGS), |n| n, MyAlloc::new(dropped.clone()), ) { Ok(map) => map, Err(msg) => panic!("{msg}"), }; let mut map2 = match get_test_map( DISARMED_FLAGS.into_iter().zip(ARMED_FLAGS), |n| n, MyAlloc::new(dropped.clone()), ) { Ok(map) => map, Err(msg) => panic!("{msg}"), }; // The `clone_from` should try to drop the elements of `map2` without // double drop and leaking the allocator. Elements that have not been // dropped leak their memory. map2.clone_from(&map); } } /// We check that we have a working table if the clone operation from another /// thread ended in a panic (when buckets of maps are equal to each other). #[test] fn test_catch_panic_clone_from_when_len_is_equal() { use std::thread; let dropped: Arc = Arc::new(AtomicI8::new(2)); { assert_eq!(ARMED_FLAGS.len(), DISARMED_FLAGS.len()); let mut map = match get_test_map( DISARMED_FLAGS.into_iter().zip(DISARMED_FLAGS), |n| vec![n], MyAlloc::new(dropped.clone()), ) { Ok(map) => map, Err(msg) => panic!("{msg}"), }; thread::scope(|s| { let result: thread::ScopedJoinHandle<'_, String> = s.spawn(|| { let scope_map = match get_test_map(ARMED_FLAGS.into_iter().zip(DISARMED_FLAGS), |n| vec![n * 2], MyAlloc::new(dropped.clone())) { Ok(map) => map, Err(msg) => return msg, }; if map.table.buckets() != scope_map.table.buckets() { return format!( "map.table.buckets() != scope_map.table.buckets(),\nleft: `{}`,\nright: `{}`", map.table.buckets(), scope_map.table.buckets() ); } map.clone_from(&scope_map); "We must fail the cloning!!!".to_owned() }); if let Ok(msg) = result.join() { panic!("{msg}") } }); // Let's check that all iterators work fine and do not return elements // (especially `RawIterRange`, which does not depend on the number of // elements in the table, but looks directly at the control bytes) // // SAFETY: We know for sure that `RawTable` will outlive // the returned `RawIter / RawIterRange` iterator. assert_eq!(map.len(), 0); assert_eq!(map.iter().count(), 0); assert_eq!(unsafe { map.table.iter().count() }, 0); assert_eq!(unsafe { map.table.iter().iter.count() }, 0); for idx in 0..map.table.buckets() { let idx = idx as u64; assert!( map.table.find(idx, |(k, _)| *k == idx).is_none(), "Index: {idx}" ); } } // All allocator clones should already be dropped. assert_eq!(dropped.load(Ordering::SeqCst), 0); } /// We check that we have a working table if the clone operation from another /// thread ended in a panic (when buckets of maps are not equal to each other). #[test] fn test_catch_panic_clone_from_when_len_is_not_equal() { use std::thread; let dropped: Arc = Arc::new(AtomicI8::new(2)); { assert_eq!(ARMED_FLAGS.len(), DISARMED_FLAGS.len()); let mut map = match get_test_map( [DISARMED].into_iter().zip([DISARMED]), |n| vec![n], MyAlloc::new(dropped.clone()), ) { Ok(map) => map, Err(msg) => panic!("{msg}"), }; thread::scope(|s| { let result: thread::ScopedJoinHandle<'_, String> = s.spawn(|| { let scope_map = match get_test_map( ARMED_FLAGS.into_iter().zip(DISARMED_FLAGS), |n| vec![n * 2], MyAlloc::new(dropped.clone()), ) { Ok(map) => map, Err(msg) => return msg, }; if map.table.buckets() == scope_map.table.buckets() { return format!( "map.table.buckets() == scope_map.table.buckets(): `{}`", map.table.buckets() ); } map.clone_from(&scope_map); "We must fail the cloning!!!".to_owned() }); if let Ok(msg) = result.join() { panic!("{msg}") } }); // Let's check that all iterators work fine and do not return elements // (especially `RawIterRange`, which does not depend on the number of // elements in the table, but looks directly at the control bytes) // // SAFETY: We know for sure that `RawTable` will outlive // the returned `RawIter / RawIterRange` iterator. assert_eq!(map.len(), 0); assert_eq!(map.iter().count(), 0); assert_eq!(unsafe { map.table.iter().count() }, 0); assert_eq!(unsafe { map.table.iter().iter.count() }, 0); for idx in 0..map.table.buckets() { let idx = idx as u64; assert!( map.table.find(idx, |(k, _)| *k == idx).is_none(), "Index: {idx}" ); } } // All allocator clones should already be dropped. assert_eq!(dropped.load(Ordering::SeqCst), 0); } } hashbrown-0.14.5/src/raw/alloc.rs000064400000000000000000000054361046102023000147360ustar 00000000000000pub(crate) use self::inner::{do_alloc, Allocator, Global}; // Nightly-case. // Use unstable `allocator_api` feature. // This is compatible with `allocator-api2` which can be enabled or not. // This is used when building for `std`. #[cfg(feature = "nightly")] mod inner { use crate::alloc::alloc::Layout; pub use crate::alloc::alloc::{Allocator, Global}; use core::ptr::NonNull; #[allow(clippy::map_err_ignore)] pub(crate) fn do_alloc(alloc: &A, layout: Layout) -> Result, ()> { match alloc.allocate(layout) { Ok(ptr) => Ok(ptr.as_non_null_ptr()), Err(_) => Err(()), } } } // Basic non-nightly case. // This uses `allocator-api2` enabled by default. // If any crate enables "nightly" in `allocator-api2`, // this will be equivalent to the nightly case, // since `allocator_api2::alloc::Allocator` would be re-export of // `core::alloc::Allocator`. #[cfg(all(not(feature = "nightly"), feature = "allocator-api2"))] mod inner { use crate::alloc::alloc::Layout; pub use allocator_api2::alloc::{Allocator, Global}; use core::ptr::NonNull; #[allow(clippy::map_err_ignore)] pub(crate) fn do_alloc(alloc: &A, layout: Layout) -> Result, ()> { match alloc.allocate(layout) { Ok(ptr) => Ok(ptr.cast()), Err(_) => Err(()), } } } // No-defaults case. // When building with default-features turned off and // neither `nightly` nor `allocator-api2` is enabled, // this will be used. // Making it impossible to use any custom allocator with collections defined // in this crate. // Any crate in build-tree can enable `allocator-api2`, // or `nightly` without disturbing users that don't want to use it. #[cfg(not(any(feature = "nightly", feature = "allocator-api2")))] mod inner { use crate::alloc::alloc::{alloc, dealloc, Layout}; use core::ptr::NonNull; #[allow(clippy::missing_safety_doc)] // not exposed outside of this crate pub unsafe trait Allocator { fn allocate(&self, layout: Layout) -> Result, ()>; unsafe fn deallocate(&self, ptr: NonNull, layout: Layout); } #[derive(Copy, Clone)] pub struct Global; unsafe impl Allocator for Global { #[inline] fn allocate(&self, layout: Layout) -> Result, ()> { unsafe { NonNull::new(alloc(layout)).ok_or(()) } } #[inline] unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { dealloc(ptr.as_ptr(), layout); } } impl Default for Global { #[inline] fn default() -> Self { Global } } pub(crate) fn do_alloc(alloc: &A, layout: Layout) -> Result, ()> { alloc.allocate(layout) } } hashbrown-0.14.5/src/raw/bitmask.rs000064400000000000000000000110541046102023000152670ustar 00000000000000use super::imp::{ BitMaskWord, NonZeroBitMaskWord, BITMASK_ITER_MASK, BITMASK_MASK, BITMASK_STRIDE, }; /// A bit mask which contains the result of a `Match` operation on a `Group` and /// allows iterating through them. /// /// The bit mask is arranged so that low-order bits represent lower memory /// addresses for group match results. /// /// For implementation reasons, the bits in the set may be sparsely packed with /// groups of 8 bits representing one element. If any of these bits are non-zero /// then this element is considered to true in the mask. If this is the /// case, `BITMASK_STRIDE` will be 8 to indicate a divide-by-8 should be /// performed on counts/indices to normalize this difference. `BITMASK_MASK` is /// similarly a mask of all the actually-used bits. /// /// To iterate over a bit mask, it must be converted to a form where only 1 bit /// is set per element. This is done by applying `BITMASK_ITER_MASK` on the /// mask bits. #[derive(Copy, Clone)] pub(crate) struct BitMask(pub(crate) BitMaskWord); #[allow(clippy::use_self)] impl BitMask { /// Returns a new `BitMask` with all bits inverted. #[inline] #[must_use] #[allow(dead_code)] pub(crate) fn invert(self) -> Self { BitMask(self.0 ^ BITMASK_MASK) } /// Returns a new `BitMask` with the lowest bit removed. #[inline] #[must_use] fn remove_lowest_bit(self) -> Self { BitMask(self.0 & (self.0 - 1)) } /// Returns whether the `BitMask` has at least one set bit. #[inline] pub(crate) fn any_bit_set(self) -> bool { self.0 != 0 } /// Returns the first set bit in the `BitMask`, if there is one. #[inline] pub(crate) fn lowest_set_bit(self) -> Option { if let Some(nonzero) = NonZeroBitMaskWord::new(self.0) { Some(Self::nonzero_trailing_zeros(nonzero)) } else { None } } /// Returns the number of trailing zeroes in the `BitMask`. #[inline] pub(crate) fn trailing_zeros(self) -> usize { // ARM doesn't have a trailing_zeroes instruction, and instead uses // reverse_bits (RBIT) + leading_zeroes (CLZ). However older ARM // versions (pre-ARMv7) don't have RBIT and need to emulate it // instead. Since we only have 1 bit set in each byte on ARM, we can // use swap_bytes (REV) + leading_zeroes instead. if cfg!(target_arch = "arm") && BITMASK_STRIDE % 8 == 0 { self.0.swap_bytes().leading_zeros() as usize / BITMASK_STRIDE } else { self.0.trailing_zeros() as usize / BITMASK_STRIDE } } /// Same as above but takes a `NonZeroBitMaskWord`. #[inline] fn nonzero_trailing_zeros(nonzero: NonZeroBitMaskWord) -> usize { if cfg!(target_arch = "arm") && BITMASK_STRIDE % 8 == 0 { // SAFETY: A byte-swapped non-zero value is still non-zero. let swapped = unsafe { NonZeroBitMaskWord::new_unchecked(nonzero.get().swap_bytes()) }; swapped.leading_zeros() as usize / BITMASK_STRIDE } else { nonzero.trailing_zeros() as usize / BITMASK_STRIDE } } /// Returns the number of leading zeroes in the `BitMask`. #[inline] pub(crate) fn leading_zeros(self) -> usize { self.0.leading_zeros() as usize / BITMASK_STRIDE } } impl IntoIterator for BitMask { type Item = usize; type IntoIter = BitMaskIter; #[inline] fn into_iter(self) -> BitMaskIter { // A BitMask only requires each element (group of bits) to be non-zero. // However for iteration we need each element to only contain 1 bit. BitMaskIter(BitMask(self.0 & BITMASK_ITER_MASK)) } } /// Iterator over the contents of a `BitMask`, returning the indices of set /// bits. #[derive(Copy, Clone)] pub(crate) struct BitMaskIter(pub(crate) BitMask); impl BitMaskIter { /// Flip the bit in the mask for the entry at the given index. /// /// Returns the bit's previous state. #[inline] #[allow(clippy::cast_ptr_alignment)] #[cfg(feature = "raw")] pub(crate) unsafe fn flip(&mut self, index: usize) -> bool { // NOTE: The + BITMASK_STRIDE - 1 is to set the high bit. let mask = 1 << (index * BITMASK_STRIDE + BITMASK_STRIDE - 1); self.0 .0 ^= mask; // The bit was set if the bit is now 0. self.0 .0 & mask == 0 } } impl Iterator for BitMaskIter { type Item = usize; #[inline] fn next(&mut self) -> Option { let bit = self.0.lowest_set_bit()?; self.0 = self.0.remove_lowest_bit(); Some(bit) } } hashbrown-0.14.5/src/raw/generic.rs000064400000000000000000000134651046102023000152610ustar 00000000000000use super::bitmask::BitMask; use super::EMPTY; use core::{mem, ptr}; // Use the native word size as the group size. Using a 64-bit group size on // a 32-bit architecture will just end up being more expensive because // shifts and multiplies will need to be emulated. cfg_if! { if #[cfg(any( target_pointer_width = "64", target_arch = "aarch64", target_arch = "x86_64", target_arch = "wasm32", ))] { type GroupWord = u64; type NonZeroGroupWord = core::num::NonZeroU64; } else { type GroupWord = u32; type NonZeroGroupWord = core::num::NonZeroU32; } } pub(crate) type BitMaskWord = GroupWord; pub(crate) type NonZeroBitMaskWord = NonZeroGroupWord; pub(crate) const BITMASK_STRIDE: usize = 8; // We only care about the highest bit of each byte for the mask. #[allow(clippy::cast_possible_truncation, clippy::unnecessary_cast)] pub(crate) const BITMASK_MASK: BitMaskWord = 0x8080_8080_8080_8080_u64 as GroupWord; pub(crate) const BITMASK_ITER_MASK: BitMaskWord = !0; /// Helper function to replicate a byte across a `GroupWord`. #[inline] fn repeat(byte: u8) -> GroupWord { GroupWord::from_ne_bytes([byte; Group::WIDTH]) } /// Abstraction over a group of control bytes which can be scanned in /// parallel. /// /// This implementation uses a word-sized integer. #[derive(Copy, Clone)] pub(crate) struct Group(GroupWord); // We perform all operations in the native endianness, and convert to // little-endian just before creating a BitMask. The can potentially // enable the compiler to eliminate unnecessary byte swaps if we are // only checking whether a BitMask is empty. #[allow(clippy::use_self)] impl Group { /// Number of bytes in the group. pub(crate) const WIDTH: usize = mem::size_of::(); /// Returns a full group of empty bytes, suitable for use as the initial /// value for an empty hash table. /// /// This is guaranteed to be aligned to the group size. #[inline] pub(crate) const fn static_empty() -> &'static [u8; Group::WIDTH] { #[repr(C)] struct AlignedBytes { _align: [Group; 0], bytes: [u8; Group::WIDTH], } const ALIGNED_BYTES: AlignedBytes = AlignedBytes { _align: [], bytes: [EMPTY; Group::WIDTH], }; &ALIGNED_BYTES.bytes } /// Loads a group of bytes starting at the given address. #[inline] #[allow(clippy::cast_ptr_alignment)] // unaligned load pub(crate) unsafe fn load(ptr: *const u8) -> Self { Group(ptr::read_unaligned(ptr.cast())) } /// Loads a group of bytes starting at the given address, which must be /// aligned to `mem::align_of::()`. #[inline] #[allow(clippy::cast_ptr_alignment)] pub(crate) unsafe fn load_aligned(ptr: *const u8) -> Self { // FIXME: use align_offset once it stabilizes debug_assert_eq!(ptr as usize & (mem::align_of::() - 1), 0); Group(ptr::read(ptr.cast())) } /// Stores the group of bytes to the given address, which must be /// aligned to `mem::align_of::()`. #[inline] #[allow(clippy::cast_ptr_alignment)] pub(crate) unsafe fn store_aligned(self, ptr: *mut u8) { // FIXME: use align_offset once it stabilizes debug_assert_eq!(ptr as usize & (mem::align_of::() - 1), 0); ptr::write(ptr.cast(), self.0); } /// Returns a `BitMask` indicating all bytes in the group which *may* /// have the given value. /// /// This function may return a false positive in certain cases where /// the byte in the group differs from the searched value only in its /// lowest bit. This is fine because: /// - This never happens for `EMPTY` and `DELETED`, only full entries. /// - The check for key equality will catch these. /// - This only happens if there is at least 1 true match. /// - The chance of this happening is very low (< 1% chance per byte). #[inline] pub(crate) fn match_byte(self, byte: u8) -> BitMask { // This algorithm is derived from // https://graphics.stanford.edu/~seander/bithacks.html##ValueInWord let cmp = self.0 ^ repeat(byte); BitMask((cmp.wrapping_sub(repeat(0x01)) & !cmp & repeat(0x80)).to_le()) } /// Returns a `BitMask` indicating all bytes in the group which are /// `EMPTY`. #[inline] pub(crate) fn match_empty(self) -> BitMask { // If the high bit is set, then the byte must be either: // 1111_1111 (EMPTY) or 1000_0000 (DELETED). // So we can just check if the top two bits are 1 by ANDing them. BitMask((self.0 & (self.0 << 1) & repeat(0x80)).to_le()) } /// Returns a `BitMask` indicating all bytes in the group which are /// `EMPTY` or `DELETED`. #[inline] pub(crate) fn match_empty_or_deleted(self) -> BitMask { // A byte is EMPTY or DELETED iff the high bit is set BitMask((self.0 & repeat(0x80)).to_le()) } /// Returns a `BitMask` indicating all bytes in the group which are full. #[inline] pub(crate) fn match_full(self) -> BitMask { self.match_empty_or_deleted().invert() } /// Performs the following transformation on all bytes in the group: /// - `EMPTY => EMPTY` /// - `DELETED => EMPTY` /// - `FULL => DELETED` #[inline] pub(crate) fn convert_special_to_empty_and_full_to_deleted(self) -> Self { // Map high_bit = 1 (EMPTY or DELETED) to 1111_1111 // and high_bit = 0 (FULL) to 1000_0000 // // Here's this logic expanded to concrete values: // let full = 1000_0000 (true) or 0000_0000 (false) // !1000_0000 + 1 = 0111_1111 + 1 = 1000_0000 (no carry) // !0000_0000 + 0 = 1111_1111 + 0 = 1111_1111 (no carry) let full = !self.0 & repeat(0x80); Group(!full + (full >> 7)) } } hashbrown-0.14.5/src/raw/mod.rs000064400000000000000000006243301046102023000144230ustar 00000000000000use crate::alloc::alloc::{handle_alloc_error, Layout}; use crate::scopeguard::{guard, ScopeGuard}; use crate::TryReserveError; use core::iter::FusedIterator; use core::marker::PhantomData; use core::mem; use core::mem::MaybeUninit; use core::ptr::NonNull; use core::{hint, ptr}; cfg_if! { // Use the SSE2 implementation if possible: it allows us to scan 16 buckets // at once instead of 8. We don't bother with AVX since it would require // runtime dispatch and wouldn't gain us much anyways: the probability of // finding a match drops off drastically after the first few buckets. // // I attempted an implementation on ARM using NEON instructions, but it // turns out that most NEON instructions have multi-cycle latency, which in // the end outweighs any gains over the generic implementation. if #[cfg(all( target_feature = "sse2", any(target_arch = "x86", target_arch = "x86_64"), not(miri), ))] { mod sse2; use sse2 as imp; } else if #[cfg(all( target_arch = "aarch64", target_feature = "neon", // NEON intrinsics are currently broken on big-endian targets. // See https://github.com/rust-lang/stdarch/issues/1484. target_endian = "little", not(miri), ))] { mod neon; use neon as imp; } else { mod generic; use generic as imp; } } mod alloc; pub(crate) use self::alloc::{do_alloc, Allocator, Global}; mod bitmask; use self::bitmask::BitMaskIter; use self::imp::Group; // Branch prediction hint. This is currently only available on nightly but it // consistently improves performance by 10-15%. #[cfg(not(feature = "nightly"))] use core::convert::identity as likely; #[cfg(not(feature = "nightly"))] use core::convert::identity as unlikely; #[cfg(feature = "nightly")] use core::intrinsics::{likely, unlikely}; // FIXME: use strict provenance functions once they are stable. // Implement it with a transmute for now. #[inline(always)] #[allow(clippy::useless_transmute)] // clippy is wrong, cast and transmute are different here fn invalid_mut(addr: usize) -> *mut T { unsafe { core::mem::transmute(addr) } } #[inline] unsafe fn offset_from(to: *const T, from: *const T) -> usize { to.offset_from(from) as usize } /// Whether memory allocation errors should return an error or abort. #[derive(Copy, Clone)] enum Fallibility { Fallible, Infallible, } impl Fallibility { /// Error to return on capacity overflow. #[cfg_attr(feature = "inline-more", inline)] fn capacity_overflow(self) -> TryReserveError { match self { Fallibility::Fallible => TryReserveError::CapacityOverflow, Fallibility::Infallible => panic!("Hash table capacity overflow"), } } /// Error to return on allocation error. #[cfg_attr(feature = "inline-more", inline)] fn alloc_err(self, layout: Layout) -> TryReserveError { match self { Fallibility::Fallible => TryReserveError::AllocError { layout }, Fallibility::Infallible => handle_alloc_error(layout), } } } trait SizedTypeProperties: Sized { const IS_ZERO_SIZED: bool = mem::size_of::() == 0; const NEEDS_DROP: bool = mem::needs_drop::(); } impl SizedTypeProperties for T {} /// Control byte value for an empty bucket. const EMPTY: u8 = 0b1111_1111; /// Control byte value for a deleted bucket. const DELETED: u8 = 0b1000_0000; /// Checks whether a control byte represents a full bucket (top bit is clear). #[inline] fn is_full(ctrl: u8) -> bool { ctrl & 0x80 == 0 } /// Checks whether a control byte represents a special value (top bit is set). #[inline] fn is_special(ctrl: u8) -> bool { ctrl & 0x80 != 0 } /// Checks whether a special control value is EMPTY (just check 1 bit). #[inline] fn special_is_empty(ctrl: u8) -> bool { debug_assert!(is_special(ctrl)); ctrl & 0x01 != 0 } /// Primary hash function, used to select the initial bucket to probe from. #[inline] #[allow(clippy::cast_possible_truncation)] fn h1(hash: u64) -> usize { // On 32-bit platforms we simply ignore the higher hash bits. hash as usize } // Constant for h2 function that grabing the top 7 bits of the hash. const MIN_HASH_LEN: usize = if mem::size_of::() < mem::size_of::() { mem::size_of::() } else { mem::size_of::() }; /// Secondary hash function, saved in the low 7 bits of the control byte. #[inline] #[allow(clippy::cast_possible_truncation)] fn h2(hash: u64) -> u8 { // Grab the top 7 bits of the hash. While the hash is normally a full 64-bit // value, some hash functions (such as FxHash) produce a usize result // instead, which means that the top 32 bits are 0 on 32-bit platforms. // So we use MIN_HASH_LEN constant to handle this. let top7 = hash >> (MIN_HASH_LEN * 8 - 7); (top7 & 0x7f) as u8 // truncation } /// Probe sequence based on triangular numbers, which is guaranteed (since our /// table size is a power of two) to visit every group of elements exactly once. /// /// A triangular probe has us jump by 1 more group every time. So first we /// jump by 1 group (meaning we just continue our linear scan), then 2 groups /// (skipping over 1 group), then 3 groups (skipping over 2 groups), and so on. /// /// Proof that the probe will visit every group in the table: /// struct ProbeSeq { pos: usize, stride: usize, } impl ProbeSeq { #[inline] fn move_next(&mut self, bucket_mask: usize) { // We should have found an empty bucket by now and ended the probe. debug_assert!( self.stride <= bucket_mask, "Went past end of probe sequence" ); self.stride += Group::WIDTH; self.pos += self.stride; self.pos &= bucket_mask; } } /// Returns the number of buckets needed to hold the given number of items, /// taking the maximum load factor into account. /// /// Returns `None` if an overflow occurs. // Workaround for emscripten bug emscripten-core/emscripten-fastcomp#258 #[cfg_attr(target_os = "emscripten", inline(never))] #[cfg_attr(not(target_os = "emscripten"), inline)] fn capacity_to_buckets(cap: usize) -> Option { debug_assert_ne!(cap, 0); // For small tables we require at least 1 empty bucket so that lookups are // guaranteed to terminate if an element doesn't exist in the table. if cap < 8 { // We don't bother with a table size of 2 buckets since that can only // hold a single element. Instead we skip directly to a 4 bucket table // which can hold 3 elements. return Some(if cap < 4 { 4 } else { 8 }); } // Otherwise require 1/8 buckets to be empty (87.5% load) // // Be careful when modifying this, calculate_layout relies on the // overflow check here. let adjusted_cap = cap.checked_mul(8)? / 7; // Any overflows will have been caught by the checked_mul. Also, any // rounding errors from the division above will be cleaned up by // next_power_of_two (which can't overflow because of the previous division). Some(adjusted_cap.next_power_of_two()) } /// Returns the maximum effective capacity for the given bucket mask, taking /// the maximum load factor into account. #[inline] fn bucket_mask_to_capacity(bucket_mask: usize) -> usize { if bucket_mask < 8 { // For tables with 1/2/4/8 buckets, we always reserve one empty slot. // Keep in mind that the bucket mask is one less than the bucket count. bucket_mask } else { // For larger tables we reserve 12.5% of the slots as empty. ((bucket_mask + 1) / 8) * 7 } } /// Helper which allows the max calculation for ctrl_align to be statically computed for each T /// while keeping the rest of `calculate_layout_for` independent of `T` #[derive(Copy, Clone)] struct TableLayout { size: usize, ctrl_align: usize, } impl TableLayout { #[inline] const fn new() -> Self { let layout = Layout::new::(); Self { size: layout.size(), ctrl_align: if layout.align() > Group::WIDTH { layout.align() } else { Group::WIDTH }, } } #[inline] fn calculate_layout_for(self, buckets: usize) -> Option<(Layout, usize)> { debug_assert!(buckets.is_power_of_two()); let TableLayout { size, ctrl_align } = self; // Manual layout calculation since Layout methods are not yet stable. let ctrl_offset = size.checked_mul(buckets)?.checked_add(ctrl_align - 1)? & !(ctrl_align - 1); let len = ctrl_offset.checked_add(buckets + Group::WIDTH)?; // We need an additional check to ensure that the allocation doesn't // exceed `isize::MAX` (https://github.com/rust-lang/rust/pull/95295). if len > isize::MAX as usize - (ctrl_align - 1) { return None; } Some(( unsafe { Layout::from_size_align_unchecked(len, ctrl_align) }, ctrl_offset, )) } } /// A reference to an empty bucket into which an can be inserted. pub struct InsertSlot { index: usize, } /// A reference to a hash table bucket containing a `T`. /// /// This is usually just a pointer to the element itself. However if the element /// is a ZST, then we instead track the index of the element in the table so /// that `erase` works properly. pub struct Bucket { // Actually it is pointer to next element than element itself // this is needed to maintain pointer arithmetic invariants // keeping direct pointer to element introduces difficulty. // Using `NonNull` for variance and niche layout ptr: NonNull, } // This Send impl is needed for rayon support. This is safe since Bucket is // never exposed in a public API. unsafe impl Send for Bucket {} impl Clone for Bucket { #[inline] fn clone(&self) -> Self { Self { ptr: self.ptr } } } impl Bucket { /// Creates a [`Bucket`] that contain pointer to the data. /// The pointer calculation is performed by calculating the /// offset from given `base` pointer (convenience for /// `base.as_ptr().sub(index)`). /// /// `index` is in units of `T`; e.g., an `index` of 3 represents a pointer /// offset of `3 * size_of::()` bytes. /// /// If the `T` is a ZST, then we instead track the index of the element /// in the table so that `erase` works properly (return /// `NonNull::new_unchecked((index + 1) as *mut T)`) /// /// # Safety /// /// If `mem::size_of::() != 0`, then the safety rules are directly derived /// from the safety rules for [`<*mut T>::sub`] method of `*mut T` and the safety /// rules of [`NonNull::new_unchecked`] function. /// /// Thus, in order to uphold the safety contracts for the [`<*mut T>::sub`] method /// and [`NonNull::new_unchecked`] function, as well as for the correct /// logic of the work of this crate, the following rules are necessary and /// sufficient: /// /// * the `base` pointer must not be `dangling` and must points to the /// end of the first `value element` from the `data part` of the table, i.e. /// must be the pointer that returned by [`RawTable::data_end`] or by /// [`RawTableInner::data_end`]; /// /// * `index` must not be greater than `RawTableInner.bucket_mask`, i.e. /// `index <= RawTableInner.bucket_mask` or, in other words, `(index + 1)` /// must be no greater than the number returned by the function /// [`RawTable::buckets`] or [`RawTableInner::buckets`]. /// /// If `mem::size_of::() == 0`, then the only requirement is that the /// `index` must not be greater than `RawTableInner.bucket_mask`, i.e. /// `index <= RawTableInner.bucket_mask` or, in other words, `(index + 1)` /// must be no greater than the number returned by the function /// [`RawTable::buckets`] or [`RawTableInner::buckets`]. /// /// [`Bucket`]: crate::raw::Bucket /// [`<*mut T>::sub`]: https://doc.rust-lang.org/core/primitive.pointer.html#method.sub-1 /// [`NonNull::new_unchecked`]: https://doc.rust-lang.org/stable/std/ptr/struct.NonNull.html#method.new_unchecked /// [`RawTable::data_end`]: crate::raw::RawTable::data_end /// [`RawTableInner::data_end`]: RawTableInner::data_end /// [`RawTable::buckets`]: crate::raw::RawTable::buckets /// [`RawTableInner::buckets`]: RawTableInner::buckets #[inline] unsafe fn from_base_index(base: NonNull, index: usize) -> Self { // If mem::size_of::() != 0 then return a pointer to an `element` in // the data part of the table (we start counting from "0", so that // in the expression T[last], the "last" index actually one less than the // "buckets" number in the table, i.e. "last = RawTableInner.bucket_mask"): // // `from_base_index(base, 1).as_ptr()` returns a pointer that // points here in the data part of the table // (to the start of T1) // | // | `base: NonNull` must point here // | (to the end of T0 or to the start of C0) // v v // [Padding], Tlast, ..., |T1|, T0, |C0, C1, ..., Clast // ^ // `from_base_index(base, 1)` returns a pointer // that points here in the data part of the table // (to the end of T1) // // where: T0...Tlast - our stored data; C0...Clast - control bytes // or metadata for data. let ptr = if T::IS_ZERO_SIZED { // won't overflow because index must be less than length (bucket_mask) // and bucket_mask is guaranteed to be less than `isize::MAX` // (see TableLayout::calculate_layout_for method) invalid_mut(index + 1) } else { base.as_ptr().sub(index) }; Self { ptr: NonNull::new_unchecked(ptr), } } /// Calculates the index of a [`Bucket`] as distance between two pointers /// (convenience for `base.as_ptr().offset_from(self.ptr.as_ptr()) as usize`). /// The returned value is in units of T: the distance in bytes divided by /// [`core::mem::size_of::()`]. /// /// If the `T` is a ZST, then we return the index of the element in /// the table so that `erase` works properly (return `self.ptr.as_ptr() as usize - 1`). /// /// This function is the inverse of [`from_base_index`]. /// /// # Safety /// /// If `mem::size_of::() != 0`, then the safety rules are directly derived /// from the safety rules for [`<*const T>::offset_from`] method of `*const T`. /// /// Thus, in order to uphold the safety contracts for [`<*const T>::offset_from`] /// method, as well as for the correct logic of the work of this crate, the /// following rules are necessary and sufficient: /// /// * `base` contained pointer must not be `dangling` and must point to the /// end of the first `element` from the `data part` of the table, i.e. /// must be a pointer that returns by [`RawTable::data_end`] or by /// [`RawTableInner::data_end`]; /// /// * `self` also must not contain dangling pointer; /// /// * both `self` and `base` must be created from the same [`RawTable`] /// (or [`RawTableInner`]). /// /// If `mem::size_of::() == 0`, this function is always safe. /// /// [`Bucket`]: crate::raw::Bucket /// [`from_base_index`]: crate::raw::Bucket::from_base_index /// [`RawTable::data_end`]: crate::raw::RawTable::data_end /// [`RawTableInner::data_end`]: RawTableInner::data_end /// [`RawTable`]: crate::raw::RawTable /// [`RawTableInner`]: RawTableInner /// [`<*const T>::offset_from`]: https://doc.rust-lang.org/nightly/core/primitive.pointer.html#method.offset_from #[inline] unsafe fn to_base_index(&self, base: NonNull) -> usize { // If mem::size_of::() != 0 then return an index under which we used to store the // `element` in the data part of the table (we start counting from "0", so // that in the expression T[last], the "last" index actually is one less than the // "buckets" number in the table, i.e. "last = RawTableInner.bucket_mask"). // For example for 5th element in table calculation is performed like this: // // mem::size_of::() // | // | `self = from_base_index(base, 5)` that returns pointer // | that points here in tha data part of the table // | (to the end of T5) // | | `base: NonNull` must point here // v | (to the end of T0 or to the start of C0) // /???\ v v // [Padding], Tlast, ..., |T10|, ..., T5|, T4, T3, T2, T1, T0, |C0, C1, C2, C3, C4, C5, ..., C10, ..., Clast // \__________ __________/ // \/ // `bucket.to_base_index(base)` = 5 // (base.as_ptr() as usize - self.ptr.as_ptr() as usize) / mem::size_of::() // // where: T0...Tlast - our stored data; C0...Clast - control bytes or metadata for data. if T::IS_ZERO_SIZED { // this can not be UB self.ptr.as_ptr() as usize - 1 } else { offset_from(base.as_ptr(), self.ptr.as_ptr()) } } /// Acquires the underlying raw pointer `*mut T` to `data`. /// /// # Note /// /// If `T` is not [`Copy`], do not use `*mut T` methods that can cause calling the /// destructor of `T` (for example the [`<*mut T>::drop_in_place`] method), because /// for properly dropping the data we also need to clear `data` control bytes. If we /// drop data, but do not clear `data control byte` it leads to double drop when /// [`RawTable`] goes out of scope. /// /// If you modify an already initialized `value`, so [`Hash`] and [`Eq`] on the new /// `T` value and its borrowed form *must* match those for the old `T` value, as the map /// will not re-evaluate where the new value should go, meaning the value may become /// "lost" if their location does not reflect their state. /// /// [`RawTable`]: crate::raw::RawTable /// [`<*mut T>::drop_in_place`]: https://doc.rust-lang.org/core/primitive.pointer.html#method.drop_in_place /// [`Hash`]: https://doc.rust-lang.org/core/hash/trait.Hash.html /// [`Eq`]: https://doc.rust-lang.org/core/cmp/trait.Eq.html /// /// # Examples /// /// ``` /// # #[cfg(feature = "raw")] /// # fn test() { /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::raw::{Bucket, RawTable}; /// /// type NewHashBuilder = core::hash::BuildHasherDefault; /// /// fn make_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let hash_builder = NewHashBuilder::default(); /// let mut table = RawTable::new(); /// /// let value = ("a", 100); /// let hash = make_hash(&hash_builder, &value.0); /// /// table.insert(hash, value.clone(), |val| make_hash(&hash_builder, &val.0)); /// /// let bucket: Bucket<(&str, i32)> = table.find(hash, |(k1, _)| k1 == &value.0).unwrap(); /// /// assert_eq!(unsafe { &*bucket.as_ptr() }, &("a", 100)); /// # } /// # fn main() { /// # #[cfg(feature = "raw")] /// # test() /// # } /// ``` #[inline] pub fn as_ptr(&self) -> *mut T { if T::IS_ZERO_SIZED { // Just return an arbitrary ZST pointer which is properly aligned // invalid pointer is good enough for ZST invalid_mut(mem::align_of::()) } else { unsafe { self.ptr.as_ptr().sub(1) } } } /// Create a new [`Bucket`] that is offset from the `self` by the given /// `offset`. The pointer calculation is performed by calculating the /// offset from `self` pointer (convenience for `self.ptr.as_ptr().sub(offset)`). /// This function is used for iterators. /// /// `offset` is in units of `T`; e.g., a `offset` of 3 represents a pointer /// offset of `3 * size_of::()` bytes. /// /// # Safety /// /// If `mem::size_of::() != 0`, then the safety rules are directly derived /// from the safety rules for [`<*mut T>::sub`] method of `*mut T` and safety /// rules of [`NonNull::new_unchecked`] function. /// /// Thus, in order to uphold the safety contracts for [`<*mut T>::sub`] method /// and [`NonNull::new_unchecked`] function, as well as for the correct /// logic of the work of this crate, the following rules are necessary and /// sufficient: /// /// * `self` contained pointer must not be `dangling`; /// /// * `self.to_base_index() + ofset` must not be greater than `RawTableInner.bucket_mask`, /// i.e. `(self.to_base_index() + ofset) <= RawTableInner.bucket_mask` or, in other /// words, `self.to_base_index() + ofset + 1` must be no greater than the number returned /// by the function [`RawTable::buckets`] or [`RawTableInner::buckets`]. /// /// If `mem::size_of::() == 0`, then the only requirement is that the /// `self.to_base_index() + ofset` must not be greater than `RawTableInner.bucket_mask`, /// i.e. `(self.to_base_index() + ofset) <= RawTableInner.bucket_mask` or, in other words, /// `self.to_base_index() + ofset + 1` must be no greater than the number returned by the /// function [`RawTable::buckets`] or [`RawTableInner::buckets`]. /// /// [`Bucket`]: crate::raw::Bucket /// [`<*mut T>::sub`]: https://doc.rust-lang.org/core/primitive.pointer.html#method.sub-1 /// [`NonNull::new_unchecked`]: https://doc.rust-lang.org/stable/std/ptr/struct.NonNull.html#method.new_unchecked /// [`RawTable::buckets`]: crate::raw::RawTable::buckets /// [`RawTableInner::buckets`]: RawTableInner::buckets #[inline] unsafe fn next_n(&self, offset: usize) -> Self { let ptr = if T::IS_ZERO_SIZED { // invalid pointer is good enough for ZST invalid_mut(self.ptr.as_ptr() as usize + offset) } else { self.ptr.as_ptr().sub(offset) }; Self { ptr: NonNull::new_unchecked(ptr), } } /// Executes the destructor (if any) of the pointed-to `data`. /// /// # Safety /// /// See [`ptr::drop_in_place`] for safety concerns. /// /// You should use [`RawTable::erase`] instead of this function, /// or be careful with calling this function directly, because for /// properly dropping the data we need also clear `data` control bytes. /// If we drop data, but do not erase `data control byte` it leads to /// double drop when [`RawTable`] goes out of scope. /// /// [`ptr::drop_in_place`]: https://doc.rust-lang.org/core/ptr/fn.drop_in_place.html /// [`RawTable`]: crate::raw::RawTable /// [`RawTable::erase`]: crate::raw::RawTable::erase #[cfg_attr(feature = "inline-more", inline)] pub(crate) unsafe fn drop(&self) { self.as_ptr().drop_in_place(); } /// Reads the `value` from `self` without moving it. This leaves the /// memory in `self` unchanged. /// /// # Safety /// /// See [`ptr::read`] for safety concerns. /// /// You should use [`RawTable::remove`] instead of this function, /// or be careful with calling this function directly, because compiler /// calls its destructor when readed `value` goes out of scope. It /// can cause double dropping when [`RawTable`] goes out of scope, /// because of not erased `data control byte`. /// /// [`ptr::read`]: https://doc.rust-lang.org/core/ptr/fn.read.html /// [`RawTable`]: crate::raw::RawTable /// [`RawTable::remove`]: crate::raw::RawTable::remove #[inline] pub(crate) unsafe fn read(&self) -> T { self.as_ptr().read() } /// Overwrites a memory location with the given `value` without reading /// or dropping the old value (like [`ptr::write`] function). /// /// # Safety /// /// See [`ptr::write`] for safety concerns. /// /// # Note /// /// [`Hash`] and [`Eq`] on the new `T` value and its borrowed form *must* match /// those for the old `T` value, as the map will not re-evaluate where the new /// value should go, meaning the value may become "lost" if their location /// does not reflect their state. /// /// [`ptr::write`]: https://doc.rust-lang.org/core/ptr/fn.write.html /// [`Hash`]: https://doc.rust-lang.org/core/hash/trait.Hash.html /// [`Eq`]: https://doc.rust-lang.org/core/cmp/trait.Eq.html #[inline] pub(crate) unsafe fn write(&self, val: T) { self.as_ptr().write(val); } /// Returns a shared immutable reference to the `value`. /// /// # Safety /// /// See [`NonNull::as_ref`] for safety concerns. /// /// [`NonNull::as_ref`]: https://doc.rust-lang.org/core/ptr/struct.NonNull.html#method.as_ref /// /// # Examples /// /// ``` /// # #[cfg(feature = "raw")] /// # fn test() { /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::raw::{Bucket, RawTable}; /// /// type NewHashBuilder = core::hash::BuildHasherDefault; /// /// fn make_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let hash_builder = NewHashBuilder::default(); /// let mut table = RawTable::new(); /// /// let value: (&str, String) = ("A pony", "is a small horse".to_owned()); /// let hash = make_hash(&hash_builder, &value.0); /// /// table.insert(hash, value.clone(), |val| make_hash(&hash_builder, &val.0)); /// /// let bucket: Bucket<(&str, String)> = table.find(hash, |(k, _)| k == &value.0).unwrap(); /// /// assert_eq!( /// unsafe { bucket.as_ref() }, /// &("A pony", "is a small horse".to_owned()) /// ); /// # } /// # fn main() { /// # #[cfg(feature = "raw")] /// # test() /// # } /// ``` #[inline] pub unsafe fn as_ref<'a>(&self) -> &'a T { &*self.as_ptr() } /// Returns a unique mutable reference to the `value`. /// /// # Safety /// /// See [`NonNull::as_mut`] for safety concerns. /// /// # Note /// /// [`Hash`] and [`Eq`] on the new `T` value and its borrowed form *must* match /// those for the old `T` value, as the map will not re-evaluate where the new /// value should go, meaning the value may become "lost" if their location /// does not reflect their state. /// /// [`NonNull::as_mut`]: https://doc.rust-lang.org/core/ptr/struct.NonNull.html#method.as_mut /// [`Hash`]: https://doc.rust-lang.org/core/hash/trait.Hash.html /// [`Eq`]: https://doc.rust-lang.org/core/cmp/trait.Eq.html /// /// # Examples /// /// ``` /// # #[cfg(feature = "raw")] /// # fn test() { /// use core::hash::{BuildHasher, Hash}; /// use hashbrown::raw::{Bucket, RawTable}; /// /// type NewHashBuilder = core::hash::BuildHasherDefault; /// /// fn make_hash(hash_builder: &S, key: &K) -> u64 { /// use core::hash::Hasher; /// let mut state = hash_builder.build_hasher(); /// key.hash(&mut state); /// state.finish() /// } /// /// let hash_builder = NewHashBuilder::default(); /// let mut table = RawTable::new(); /// /// let value: (&str, String) = ("A pony", "is a small horse".to_owned()); /// let hash = make_hash(&hash_builder, &value.0); /// /// table.insert(hash, value.clone(), |val| make_hash(&hash_builder, &val.0)); /// /// let bucket: Bucket<(&str, String)> = table.find(hash, |(k, _)| k == &value.0).unwrap(); /// /// unsafe { /// bucket /// .as_mut() /// .1 /// .push_str(" less than 147 cm at the withers") /// }; /// assert_eq!( /// unsafe { bucket.as_ref() }, /// &( /// "A pony", /// "is a small horse less than 147 cm at the withers".to_owned() /// ) /// ); /// # } /// # fn main() { /// # #[cfg(feature = "raw")] /// # test() /// # } /// ``` #[inline] pub unsafe fn as_mut<'a>(&self) -> &'a mut T { &mut *self.as_ptr() } /// Copies `size_of` bytes from `other` to `self`. The source /// and destination may *not* overlap. /// /// # Safety /// /// See [`ptr::copy_nonoverlapping`] for safety concerns. /// /// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values /// in the region beginning at `*self` and the region beginning at `*other` can /// [violate memory safety]. /// /// # Note /// /// [`Hash`] and [`Eq`] on the new `T` value and its borrowed form *must* match /// those for the old `T` value, as the map will not re-evaluate where the new /// value should go, meaning the value may become "lost" if their location /// does not reflect their state. /// /// [`ptr::copy_nonoverlapping`]: https://doc.rust-lang.org/core/ptr/fn.copy_nonoverlapping.html /// [`read`]: https://doc.rust-lang.org/core/ptr/fn.read.html /// [violate memory safety]: https://doc.rust-lang.org/std/ptr/fn.read.html#ownership-of-the-returned-value /// [`Hash`]: https://doc.rust-lang.org/core/hash/trait.Hash.html /// [`Eq`]: https://doc.rust-lang.org/core/cmp/trait.Eq.html #[cfg(feature = "raw")] #[inline] pub unsafe fn copy_from_nonoverlapping(&self, other: &Self) { self.as_ptr().copy_from_nonoverlapping(other.as_ptr(), 1); } } /// A raw hash table with an unsafe API. pub struct RawTable { table: RawTableInner, alloc: A, // Tell dropck that we own instances of T. marker: PhantomData, } /// Non-generic part of `RawTable` which allows functions to be instantiated only once regardless /// of how many different key-value types are used. struct RawTableInner { // Mask to get an index from a hash value. The value is one less than the // number of buckets in the table. bucket_mask: usize, // [Padding], T1, T2, ..., Tlast, C1, C2, ... // ^ points here ctrl: NonNull, // Number of elements that can be inserted before we need to grow the table growth_left: usize, // Number of elements in the table, only really used by len() items: usize, } impl RawTable { /// Creates a new empty hash table without allocating any memory. /// /// In effect this returns a table with exactly 1 bucket. However we can /// leave the data pointer dangling since that bucket is never written to /// due to our load factor forcing us to always have at least 1 free bucket. #[inline] pub const fn new() -> Self { Self { table: RawTableInner::NEW, alloc: Global, marker: PhantomData, } } /// Attempts to allocate a new hash table with at least enough capacity /// for inserting the given number of elements without reallocating. #[cfg(feature = "raw")] pub fn try_with_capacity(capacity: usize) -> Result { Self::try_with_capacity_in(capacity, Global) } /// Allocates a new hash table with at least enough capacity for inserting /// the given number of elements without reallocating. pub fn with_capacity(capacity: usize) -> Self { Self::with_capacity_in(capacity, Global) } } impl RawTable { const TABLE_LAYOUT: TableLayout = TableLayout::new::(); /// Creates a new empty hash table without allocating any memory, using the /// given allocator. /// /// In effect this returns a table with exactly 1 bucket. However we can /// leave the data pointer dangling since that bucket is never written to /// due to our load factor forcing us to always have at least 1 free bucket. #[inline] pub const fn new_in(alloc: A) -> Self { Self { table: RawTableInner::NEW, alloc, marker: PhantomData, } } /// Allocates a new hash table with the given number of buckets. /// /// The control bytes are left uninitialized. #[cfg_attr(feature = "inline-more", inline)] unsafe fn new_uninitialized( alloc: A, buckets: usize, fallibility: Fallibility, ) -> Result { debug_assert!(buckets.is_power_of_two()); Ok(Self { table: RawTableInner::new_uninitialized( &alloc, Self::TABLE_LAYOUT, buckets, fallibility, )?, alloc, marker: PhantomData, }) } /// Attempts to allocate a new hash table using the given allocator, with at least enough /// capacity for inserting the given number of elements without reallocating. #[cfg(feature = "raw")] pub fn try_with_capacity_in(capacity: usize, alloc: A) -> Result { Ok(Self { table: RawTableInner::fallible_with_capacity( &alloc, Self::TABLE_LAYOUT, capacity, Fallibility::Fallible, )?, alloc, marker: PhantomData, }) } /// Allocates a new hash table using the given allocator, with at least enough capacity for /// inserting the given number of elements without reallocating. pub fn with_capacity_in(capacity: usize, alloc: A) -> Self { Self { table: RawTableInner::with_capacity(&alloc, Self::TABLE_LAYOUT, capacity), alloc, marker: PhantomData, } } /// Returns a reference to the underlying allocator. #[inline] pub fn allocator(&self) -> &A { &self.alloc } /// Returns pointer to one past last `data` element in the table as viewed from /// the start point of the allocation. /// /// The caller must ensure that the `RawTable` outlives the returned [`NonNull`], /// otherwise using it may result in [`undefined behavior`]. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] pub fn data_end(&self) -> NonNull { // `self.table.ctrl.cast()` returns pointer that // points here (to the end of `T0`) // ∨ // [Pad], T_n, ..., T1, T0, |CT0, CT1, ..., CT_n|, CTa_0, CTa_1, ..., CTa_m // \________ ________/ // \/ // `n = buckets - 1`, i.e. `RawTable::buckets() - 1` // // where: T0...T_n - our stored data; // CT0...CT_n - control bytes or metadata for `data`. // CTa_0...CTa_m - additional control bytes, where `m = Group::WIDTH - 1` (so that the search // with loading `Group` bytes from the heap works properly, even if the result // of `h1(hash) & self.bucket_mask` is equal to `self.bucket_mask`). See also // `RawTableInner::set_ctrl` function. // // P.S. `h1(hash) & self.bucket_mask` is the same as `hash as usize % self.buckets()` because the number // of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. self.table.ctrl.cast() } /// Returns pointer to start of data table. #[inline] #[cfg(any(feature = "raw", feature = "nightly"))] pub unsafe fn data_start(&self) -> NonNull { NonNull::new_unchecked(self.data_end().as_ptr().wrapping_sub(self.buckets())) } /// Return the information about memory allocated by the table. /// /// `RawTable` allocates single memory block to store both data and metadata. /// This function returns allocation size and alignment and the beginning of the area. /// These are the arguments which will be passed to `dealloc` when the table is dropped. /// /// This function might be useful for memory profiling. #[inline] #[cfg(feature = "raw")] pub fn allocation_info(&self) -> (NonNull, Layout) { // SAFETY: We use the same `table_layout` that was used to allocate // this table. unsafe { self.table.allocation_info_or_zero(Self::TABLE_LAYOUT) } } /// Returns the index of a bucket from a `Bucket`. #[inline] pub unsafe fn bucket_index(&self, bucket: &Bucket) -> usize { bucket.to_base_index(self.data_end()) } /// Returns a pointer to an element in the table. /// /// The caller must ensure that the `RawTable` outlives the returned [`Bucket`], /// otherwise using it may result in [`undefined behavior`]. /// /// # Safety /// /// If `mem::size_of::() != 0`, then the caller of this function must observe the /// following safety rules: /// /// * The table must already be allocated; /// /// * The `index` must not be greater than the number returned by the [`RawTable::buckets`] /// function, i.e. `(index + 1) <= self.buckets()`. /// /// It is safe to call this function with index of zero (`index == 0`) on a table that has /// not been allocated, but using the returned [`Bucket`] results in [`undefined behavior`]. /// /// If `mem::size_of::() == 0`, then the only requirement is that the `index` must /// not be greater than the number returned by the [`RawTable::buckets`] function, i.e. /// `(index + 1) <= self.buckets()`. /// /// [`RawTable::buckets`]: RawTable::buckets /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] pub unsafe fn bucket(&self, index: usize) -> Bucket { // If mem::size_of::() != 0 then return a pointer to the `element` in the `data part` of the table // (we start counting from "0", so that in the expression T[n], the "n" index actually one less than // the "buckets" number of our `RawTable`, i.e. "n = RawTable::buckets() - 1"): // // `table.bucket(3).as_ptr()` returns a pointer that points here in the `data` // part of the `RawTable`, i.e. to the start of T3 (see `Bucket::as_ptr`) // | // | `base = self.data_end()` points here // | (to the start of CT0 or to the end of T0) // v v // [Pad], T_n, ..., |T3|, T2, T1, T0, |CT0, CT1, CT2, CT3, ..., CT_n, CTa_0, CTa_1, ..., CTa_m // ^ \__________ __________/ // `table.bucket(3)` returns a pointer that points \/ // here in the `data` part of the `RawTable` (to additional control bytes // the end of T3) `m = Group::WIDTH - 1` // // where: T0...T_n - our stored data; // CT0...CT_n - control bytes or metadata for `data`; // CTa_0...CTa_m - additional control bytes (so that the search with loading `Group` bytes from // the heap works properly, even if the result of `h1(hash) & self.table.bucket_mask` // is equal to `self.table.bucket_mask`). See also `RawTableInner::set_ctrl` function. // // P.S. `h1(hash) & self.table.bucket_mask` is the same as `hash as usize % self.buckets()` because the number // of buckets is a power of two, and `self.table.bucket_mask = self.buckets() - 1`. debug_assert_ne!(self.table.bucket_mask, 0); debug_assert!(index < self.buckets()); Bucket::from_base_index(self.data_end(), index) } /// Erases an element from the table without dropping it. #[cfg_attr(feature = "inline-more", inline)] unsafe fn erase_no_drop(&mut self, item: &Bucket) { let index = self.bucket_index(item); self.table.erase(index); } /// Erases an element from the table, dropping it in place. #[cfg_attr(feature = "inline-more", inline)] #[allow(clippy::needless_pass_by_value)] pub unsafe fn erase(&mut self, item: Bucket) { // Erase the element from the table first since drop might panic. self.erase_no_drop(&item); item.drop(); } /// Finds and erases an element from the table, dropping it in place. /// Returns true if an element was found. #[cfg(feature = "raw")] #[cfg_attr(feature = "inline-more", inline)] pub fn erase_entry(&mut self, hash: u64, eq: impl FnMut(&T) -> bool) -> bool { // Avoid `Option::map` because it bloats LLVM IR. if let Some(bucket) = self.find(hash, eq) { unsafe { self.erase(bucket); } true } else { false } } /// Removes an element from the table, returning it. /// /// This also returns an `InsertSlot` pointing to the newly free bucket. #[cfg_attr(feature = "inline-more", inline)] #[allow(clippy::needless_pass_by_value)] pub unsafe fn remove(&mut self, item: Bucket) -> (T, InsertSlot) { self.erase_no_drop(&item); ( item.read(), InsertSlot { index: self.bucket_index(&item), }, ) } /// Finds and removes an element from the table, returning it. #[cfg_attr(feature = "inline-more", inline)] pub fn remove_entry(&mut self, hash: u64, eq: impl FnMut(&T) -> bool) -> Option { // Avoid `Option::map` because it bloats LLVM IR. match self.find(hash, eq) { Some(bucket) => Some(unsafe { self.remove(bucket).0 }), None => None, } } /// Marks all table buckets as empty without dropping their contents. #[cfg_attr(feature = "inline-more", inline)] pub fn clear_no_drop(&mut self) { self.table.clear_no_drop(); } /// Removes all elements from the table without freeing the backing memory. #[cfg_attr(feature = "inline-more", inline)] pub fn clear(&mut self) { if self.is_empty() { // Special case empty table to avoid surprising O(capacity) time. return; } // Ensure that the table is reset even if one of the drops panic let mut self_ = guard(self, |self_| self_.clear_no_drop()); unsafe { // SAFETY: ScopeGuard sets to zero the `items` field of the table // even in case of panic during the dropping of the elements so // that there will be no double drop of the elements. self_.table.drop_elements::(); } } /// Shrinks the table to fit `max(self.len(), min_size)` elements. #[cfg_attr(feature = "inline-more", inline)] pub fn shrink_to(&mut self, min_size: usize, hasher: impl Fn(&T) -> u64) { // Calculate the minimal number of elements that we need to reserve // space for. let min_size = usize::max(self.table.items, min_size); if min_size == 0 { let mut old_inner = mem::replace(&mut self.table, RawTableInner::NEW); unsafe { // SAFETY: // 1. We call the function only once; // 2. We know for sure that `alloc` and `table_layout` matches the [`Allocator`] // and [`TableLayout`] that were used to allocate this table. // 3. If any elements' drop function panics, then there will only be a memory leak, // because we have replaced the inner table with a new one. old_inner.drop_inner_table::(&self.alloc, Self::TABLE_LAYOUT); } return; } // Calculate the number of buckets that we need for this number of // elements. If the calculation overflows then the requested bucket // count must be larger than what we have right and nothing needs to be // done. let min_buckets = match capacity_to_buckets(min_size) { Some(buckets) => buckets, None => return, }; // If we have more buckets than we need, shrink the table. if min_buckets < self.buckets() { // Fast path if the table is empty if self.table.items == 0 { let new_inner = RawTableInner::with_capacity(&self.alloc, Self::TABLE_LAYOUT, min_size); let mut old_inner = mem::replace(&mut self.table, new_inner); unsafe { // SAFETY: // 1. We call the function only once; // 2. We know for sure that `alloc` and `table_layout` matches the [`Allocator`] // and [`TableLayout`] that were used to allocate this table. // 3. If any elements' drop function panics, then there will only be a memory leak, // because we have replaced the inner table with a new one. old_inner.drop_inner_table::(&self.alloc, Self::TABLE_LAYOUT); } } else { // Avoid `Result::unwrap_or_else` because it bloats LLVM IR. unsafe { // SAFETY: // 1. We know for sure that `min_size >= self.table.items`. // 2. The [`RawTableInner`] must already have properly initialized control bytes since // we will never expose RawTable::new_uninitialized in a public API. if self .resize(min_size, hasher, Fallibility::Infallible) .is_err() { // SAFETY: The result of calling the `resize` function cannot be an error // because `fallibility == Fallibility::Infallible. hint::unreachable_unchecked() } } } } } /// Ensures that at least `additional` items can be inserted into the table /// without reallocation. #[cfg_attr(feature = "inline-more", inline)] pub fn reserve(&mut self, additional: usize, hasher: impl Fn(&T) -> u64) { if unlikely(additional > self.table.growth_left) { // Avoid `Result::unwrap_or_else` because it bloats LLVM IR. unsafe { // SAFETY: The [`RawTableInner`] must already have properly initialized control // bytes since we will never expose RawTable::new_uninitialized in a public API. if self .reserve_rehash(additional, hasher, Fallibility::Infallible) .is_err() { // SAFETY: All allocation errors will be caught inside `RawTableInner::reserve_rehash`. hint::unreachable_unchecked() } } } } /// Tries to ensure that at least `additional` items can be inserted into /// the table without reallocation. #[cfg_attr(feature = "inline-more", inline)] pub fn try_reserve( &mut self, additional: usize, hasher: impl Fn(&T) -> u64, ) -> Result<(), TryReserveError> { if additional > self.table.growth_left { // SAFETY: The [`RawTableInner`] must already have properly initialized control // bytes since we will never expose RawTable::new_uninitialized in a public API. unsafe { self.reserve_rehash(additional, hasher, Fallibility::Fallible) } } else { Ok(()) } } /// Out-of-line slow path for `reserve` and `try_reserve`. /// /// # Safety /// /// The [`RawTableInner`] must have properly initialized control bytes, /// otherwise calling this function results in [`undefined behavior`] /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[cold] #[inline(never)] unsafe fn reserve_rehash( &mut self, additional: usize, hasher: impl Fn(&T) -> u64, fallibility: Fallibility, ) -> Result<(), TryReserveError> { unsafe { // SAFETY: // 1. We know for sure that `alloc` and `layout` matches the [`Allocator`] and // [`TableLayout`] that were used to allocate this table. // 2. The `drop` function is the actual drop function of the elements stored in // the table. // 3. The caller ensures that the control bytes of the `RawTableInner` // are already initialized. self.table.reserve_rehash_inner( &self.alloc, additional, &|table, index| hasher(table.bucket::(index).as_ref()), fallibility, Self::TABLE_LAYOUT, if T::NEEDS_DROP { Some(mem::transmute(ptr::drop_in_place:: as unsafe fn(*mut T))) } else { None }, ) } } /// Allocates a new table of a different size and moves the contents of the /// current table into it. /// /// # Safety /// /// The [`RawTableInner`] must have properly initialized control bytes, /// otherwise calling this function results in [`undefined behavior`] /// /// The caller of this function must ensure that `capacity >= self.table.items` /// otherwise: /// /// * If `self.table.items != 0`, calling of this function with `capacity` /// equal to 0 (`capacity == 0`) results in [`undefined behavior`]. /// /// * If `capacity_to_buckets(capacity) < Group::WIDTH` and /// `self.table.items > capacity_to_buckets(capacity)` /// calling this function results in [`undefined behavior`]. /// /// * If `capacity_to_buckets(capacity) >= Group::WIDTH` and /// `self.table.items > capacity_to_buckets(capacity)` /// calling this function are never return (will go into an /// infinite loop). /// /// See [`RawTableInner::find_insert_slot`] for more information. /// /// [`RawTableInner::find_insert_slot`]: RawTableInner::find_insert_slot /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html unsafe fn resize( &mut self, capacity: usize, hasher: impl Fn(&T) -> u64, fallibility: Fallibility, ) -> Result<(), TryReserveError> { // SAFETY: // 1. The caller of this function guarantees that `capacity >= self.table.items`. // 2. We know for sure that `alloc` and `layout` matches the [`Allocator`] and // [`TableLayout`] that were used to allocate this table. // 3. The caller ensures that the control bytes of the `RawTableInner` // are already initialized. self.table.resize_inner( &self.alloc, capacity, &|table, index| hasher(table.bucket::(index).as_ref()), fallibility, Self::TABLE_LAYOUT, ) } /// Inserts a new element into the table, and returns its raw bucket. /// /// This does not check if the given element already exists in the table. #[cfg_attr(feature = "inline-more", inline)] pub fn insert(&mut self, hash: u64, value: T, hasher: impl Fn(&T) -> u64) -> Bucket { unsafe { // SAFETY: // 1. The [`RawTableInner`] must already have properly initialized control bytes since // we will never expose `RawTable::new_uninitialized` in a public API. // // 2. We reserve additional space (if necessary) right after calling this function. let mut slot = self.table.find_insert_slot(hash); // We can avoid growing the table once we have reached our load factor if we are replacing // a tombstone. This works since the number of EMPTY slots does not change in this case. // // SAFETY: The function is guaranteed to return [`InsertSlot`] that contains an index // in the range `0..=self.buckets()`. let old_ctrl = *self.table.ctrl(slot.index); if unlikely(self.table.growth_left == 0 && special_is_empty(old_ctrl)) { self.reserve(1, hasher); // SAFETY: We know for sure that `RawTableInner` has control bytes // initialized and that there is extra space in the table. slot = self.table.find_insert_slot(hash); } self.insert_in_slot(hash, slot, value) } } /// Attempts to insert a new element without growing the table and return its raw bucket. /// /// Returns an `Err` containing the given element if inserting it would require growing the /// table. /// /// This does not check if the given element already exists in the table. #[cfg(feature = "raw")] #[cfg_attr(feature = "inline-more", inline)] pub fn try_insert_no_grow(&mut self, hash: u64, value: T) -> Result, T> { unsafe { match self.table.prepare_insert_no_grow(hash) { Ok(index) => { let bucket = self.bucket(index); bucket.write(value); Ok(bucket) } Err(()) => Err(value), } } } /// Inserts a new element into the table, and returns a mutable reference to it. /// /// This does not check if the given element already exists in the table. #[cfg_attr(feature = "inline-more", inline)] pub fn insert_entry(&mut self, hash: u64, value: T, hasher: impl Fn(&T) -> u64) -> &mut T { unsafe { self.insert(hash, value, hasher).as_mut() } } /// Inserts a new element into the table, without growing the table. /// /// There must be enough space in the table to insert the new element. /// /// This does not check if the given element already exists in the table. #[cfg_attr(feature = "inline-more", inline)] #[cfg(any(feature = "raw", feature = "rustc-internal-api"))] pub unsafe fn insert_no_grow(&mut self, hash: u64, value: T) -> Bucket { let (index, old_ctrl) = self.table.prepare_insert_slot(hash); let bucket = self.table.bucket(index); // If we are replacing a DELETED entry then we don't need to update // the load counter. self.table.growth_left -= special_is_empty(old_ctrl) as usize; bucket.write(value); self.table.items += 1; bucket } /// Temporary removes a bucket, applying the given function to the removed /// element and optionally put back the returned value in the same bucket. /// /// Returns `true` if the bucket still contains an element /// /// This does not check if the given bucket is actually occupied. #[cfg_attr(feature = "inline-more", inline)] pub unsafe fn replace_bucket_with(&mut self, bucket: Bucket, f: F) -> bool where F: FnOnce(T) -> Option, { let index = self.bucket_index(&bucket); let old_ctrl = *self.table.ctrl(index); debug_assert!(self.is_bucket_full(index)); let old_growth_left = self.table.growth_left; let item = self.remove(bucket).0; if let Some(new_item) = f(item) { self.table.growth_left = old_growth_left; self.table.set_ctrl(index, old_ctrl); self.table.items += 1; self.bucket(index).write(new_item); true } else { false } } /// Searches for an element in the table. If the element is not found, /// returns `Err` with the position of a slot where an element with the /// same hash could be inserted. /// /// This function may resize the table if additional space is required for /// inserting an element. #[inline] pub fn find_or_find_insert_slot( &mut self, hash: u64, mut eq: impl FnMut(&T) -> bool, hasher: impl Fn(&T) -> u64, ) -> Result, InsertSlot> { self.reserve(1, hasher); unsafe { // SAFETY: // 1. We know for sure that there is at least one empty `bucket` in the table. // 2. The [`RawTableInner`] must already have properly initialized control bytes since we will // never expose `RawTable::new_uninitialized` in a public API. // 3. The `find_or_find_insert_slot_inner` function returns the `index` of only the full bucket, // which is in the range `0..self.buckets()` (since there is at least one empty `bucket` in // the table), so calling `self.bucket(index)` and `Bucket::as_ref` is safe. match self .table .find_or_find_insert_slot_inner(hash, &mut |index| eq(self.bucket(index).as_ref())) { // SAFETY: See explanation above. Ok(index) => Ok(self.bucket(index)), Err(slot) => Err(slot), } } } /// Inserts a new element into the table in the given slot, and returns its /// raw bucket. /// /// # Safety /// /// `slot` must point to a slot previously returned by /// `find_or_find_insert_slot`, and no mutation of the table must have /// occurred since that call. #[inline] pub unsafe fn insert_in_slot(&mut self, hash: u64, slot: InsertSlot, value: T) -> Bucket { let old_ctrl = *self.table.ctrl(slot.index); self.table.record_item_insert_at(slot.index, old_ctrl, hash); let bucket = self.bucket(slot.index); bucket.write(value); bucket } /// Searches for an element in the table. #[inline] pub fn find(&self, hash: u64, mut eq: impl FnMut(&T) -> bool) -> Option> { unsafe { // SAFETY: // 1. The [`RawTableInner`] must already have properly initialized control bytes since we // will never expose `RawTable::new_uninitialized` in a public API. // 1. The `find_inner` function returns the `index` of only the full bucket, which is in // the range `0..self.buckets()`, so calling `self.bucket(index)` and `Bucket::as_ref` // is safe. let result = self .table .find_inner(hash, &mut |index| eq(self.bucket(index).as_ref())); // Avoid `Option::map` because it bloats LLVM IR. match result { // SAFETY: See explanation above. Some(index) => Some(self.bucket(index)), None => None, } } } /// Gets a reference to an element in the table. #[inline] pub fn get(&self, hash: u64, eq: impl FnMut(&T) -> bool) -> Option<&T> { // Avoid `Option::map` because it bloats LLVM IR. match self.find(hash, eq) { Some(bucket) => Some(unsafe { bucket.as_ref() }), None => None, } } /// Gets a mutable reference to an element in the table. #[inline] pub fn get_mut(&mut self, hash: u64, eq: impl FnMut(&T) -> bool) -> Option<&mut T> { // Avoid `Option::map` because it bloats LLVM IR. match self.find(hash, eq) { Some(bucket) => Some(unsafe { bucket.as_mut() }), None => None, } } /// Attempts to get mutable references to `N` entries in the table at once. /// /// Returns an array of length `N` with the results of each query. /// /// At most one mutable reference will be returned to any entry. `None` will be returned if any /// of the hashes are duplicates. `None` will be returned if the hash is not found. /// /// The `eq` argument should be a closure such that `eq(i, k)` returns true if `k` is equal to /// the `i`th key to be looked up. pub fn get_many_mut( &mut self, hashes: [u64; N], eq: impl FnMut(usize, &T) -> bool, ) -> Option<[&'_ mut T; N]> { unsafe { let ptrs = self.get_many_mut_pointers(hashes, eq)?; for (i, &cur) in ptrs.iter().enumerate() { if ptrs[..i].iter().any(|&prev| ptr::eq::(prev, cur)) { return None; } } // All bucket are distinct from all previous buckets so we're clear to return the result // of the lookup. // TODO use `MaybeUninit::array_assume_init` here instead once that's stable. Some(mem::transmute_copy(&ptrs)) } } pub unsafe fn get_many_unchecked_mut( &mut self, hashes: [u64; N], eq: impl FnMut(usize, &T) -> bool, ) -> Option<[&'_ mut T; N]> { let ptrs = self.get_many_mut_pointers(hashes, eq)?; Some(mem::transmute_copy(&ptrs)) } unsafe fn get_many_mut_pointers( &mut self, hashes: [u64; N], mut eq: impl FnMut(usize, &T) -> bool, ) -> Option<[*mut T; N]> { // TODO use `MaybeUninit::uninit_array` here instead once that's stable. let mut outs: MaybeUninit<[*mut T; N]> = MaybeUninit::uninit(); let outs_ptr = outs.as_mut_ptr(); for (i, &hash) in hashes.iter().enumerate() { let cur = self.find(hash, |k| eq(i, k))?; *(*outs_ptr).get_unchecked_mut(i) = cur.as_mut(); } // TODO use `MaybeUninit::array_assume_init` here instead once that's stable. Some(outs.assume_init()) } /// Returns the number of elements the map can hold without reallocating. /// /// This number is a lower bound; the table might be able to hold /// more, but is guaranteed to be able to hold at least this many. #[inline] pub fn capacity(&self) -> usize { self.table.items + self.table.growth_left } /// Returns the number of elements in the table. #[inline] pub fn len(&self) -> usize { self.table.items } /// Returns `true` if the table contains no elements. #[inline] pub fn is_empty(&self) -> bool { self.len() == 0 } /// Returns the number of buckets in the table. #[inline] pub fn buckets(&self) -> usize { self.table.bucket_mask + 1 } /// Checks whether the bucket at `index` is full. /// /// # Safety /// /// The caller must ensure `index` is less than the number of buckets. #[inline] pub unsafe fn is_bucket_full(&self, index: usize) -> bool { self.table.is_bucket_full(index) } /// Returns an iterator over every element in the table. It is up to /// the caller to ensure that the `RawTable` outlives the `RawIter`. /// Because we cannot make the `next` method unsafe on the `RawIter` /// struct, we have to make the `iter` method unsafe. #[inline] pub unsafe fn iter(&self) -> RawIter { // SAFETY: // 1. The caller must uphold the safety contract for `iter` method. // 2. The [`RawTableInner`] must already have properly initialized control bytes since // we will never expose RawTable::new_uninitialized in a public API. self.table.iter() } /// Returns an iterator over occupied buckets that could match a given hash. /// /// `RawTable` only stores 7 bits of the hash value, so this iterator may /// return items that have a hash value different than the one provided. You /// should always validate the returned values before using them. /// /// It is up to the caller to ensure that the `RawTable` outlives the /// `RawIterHash`. Because we cannot make the `next` method unsafe on the /// `RawIterHash` struct, we have to make the `iter_hash` method unsafe. #[cfg_attr(feature = "inline-more", inline)] #[cfg(feature = "raw")] pub unsafe fn iter_hash(&self, hash: u64) -> RawIterHash { RawIterHash::new(self, hash) } /// Returns an iterator which removes all elements from the table without /// freeing the memory. #[cfg_attr(feature = "inline-more", inline)] pub fn drain(&mut self) -> RawDrain<'_, T, A> { unsafe { let iter = self.iter(); self.drain_iter_from(iter) } } /// Returns an iterator which removes all elements from the table without /// freeing the memory. /// /// Iteration starts at the provided iterator's current location. /// /// It is up to the caller to ensure that the iterator is valid for this /// `RawTable` and covers all items that remain in the table. #[cfg_attr(feature = "inline-more", inline)] pub unsafe fn drain_iter_from(&mut self, iter: RawIter) -> RawDrain<'_, T, A> { debug_assert_eq!(iter.len(), self.len()); RawDrain { iter, table: mem::replace(&mut self.table, RawTableInner::NEW), orig_table: NonNull::from(&mut self.table), marker: PhantomData, } } /// Returns an iterator which consumes all elements from the table. /// /// Iteration starts at the provided iterator's current location. /// /// It is up to the caller to ensure that the iterator is valid for this /// `RawTable` and covers all items that remain in the table. pub unsafe fn into_iter_from(self, iter: RawIter) -> RawIntoIter { debug_assert_eq!(iter.len(), self.len()); let allocation = self.into_allocation(); RawIntoIter { iter, allocation, marker: PhantomData, } } /// Converts the table into a raw allocation. The contents of the table /// should be dropped using a `RawIter` before freeing the allocation. #[cfg_attr(feature = "inline-more", inline)] pub(crate) fn into_allocation(self) -> Option<(NonNull, Layout, A)> { let alloc = if self.table.is_empty_singleton() { None } else { // Avoid `Option::unwrap_or_else` because it bloats LLVM IR. let (layout, ctrl_offset) = match Self::TABLE_LAYOUT.calculate_layout_for(self.table.buckets()) { Some(lco) => lco, None => unsafe { hint::unreachable_unchecked() }, }; Some(( unsafe { NonNull::new_unchecked(self.table.ctrl.as_ptr().sub(ctrl_offset)) }, layout, unsafe { ptr::read(&self.alloc) }, )) }; mem::forget(self); alloc } } unsafe impl Send for RawTable where T: Send, A: Send, { } unsafe impl Sync for RawTable where T: Sync, A: Sync, { } impl RawTableInner { const NEW: Self = RawTableInner::new(); /// Creates a new empty hash table without allocating any memory. /// /// In effect this returns a table with exactly 1 bucket. However we can /// leave the data pointer dangling since that bucket is never accessed /// due to our load factor forcing us to always have at least 1 free bucket. #[inline] const fn new() -> Self { Self { // Be careful to cast the entire slice to a raw pointer. ctrl: unsafe { NonNull::new_unchecked(Group::static_empty() as *const _ as *mut u8) }, bucket_mask: 0, items: 0, growth_left: 0, } } } impl RawTableInner { /// Allocates a new [`RawTableInner`] with the given number of buckets. /// The control bytes and buckets are left uninitialized. /// /// # Safety /// /// The caller of this function must ensure that the `buckets` is power of two /// and also initialize all control bytes of the length `self.bucket_mask + 1 + /// Group::WIDTH` with the [`EMPTY`] bytes. /// /// See also [`Allocator`] API for other safety concerns. /// /// [`Allocator`]: https://doc.rust-lang.org/alloc/alloc/trait.Allocator.html #[cfg_attr(feature = "inline-more", inline)] unsafe fn new_uninitialized( alloc: &A, table_layout: TableLayout, buckets: usize, fallibility: Fallibility, ) -> Result where A: Allocator, { debug_assert!(buckets.is_power_of_two()); // Avoid `Option::ok_or_else` because it bloats LLVM IR. let (layout, ctrl_offset) = match table_layout.calculate_layout_for(buckets) { Some(lco) => lco, None => return Err(fallibility.capacity_overflow()), }; let ptr: NonNull = match do_alloc(alloc, layout) { Ok(block) => block.cast(), Err(_) => return Err(fallibility.alloc_err(layout)), }; // SAFETY: null pointer will be caught in above check let ctrl = NonNull::new_unchecked(ptr.as_ptr().add(ctrl_offset)); Ok(Self { ctrl, bucket_mask: buckets - 1, items: 0, growth_left: bucket_mask_to_capacity(buckets - 1), }) } /// Attempts to allocate a new [`RawTableInner`] with at least enough /// capacity for inserting the given number of elements without reallocating. /// /// All the control bytes are initialized with the [`EMPTY`] bytes. #[inline] fn fallible_with_capacity( alloc: &A, table_layout: TableLayout, capacity: usize, fallibility: Fallibility, ) -> Result where A: Allocator, { if capacity == 0 { Ok(Self::NEW) } else { // SAFETY: We checked that we could successfully allocate the new table, and then // initialized all control bytes with the constant `EMPTY` byte. unsafe { let buckets = capacity_to_buckets(capacity).ok_or_else(|| fallibility.capacity_overflow())?; let result = Self::new_uninitialized(alloc, table_layout, buckets, fallibility)?; // SAFETY: We checked that the table is allocated and therefore the table already has // `self.bucket_mask + 1 + Group::WIDTH` number of control bytes (see TableLayout::calculate_layout_for) // so writing `self.num_ctrl_bytes() == bucket_mask + 1 + Group::WIDTH` bytes is safe. result.ctrl(0).write_bytes(EMPTY, result.num_ctrl_bytes()); Ok(result) } } } /// Allocates a new [`RawTableInner`] with at least enough capacity for inserting /// the given number of elements without reallocating. /// /// Panics if the new capacity exceeds [`isize::MAX`] bytes and [`abort`] the program /// in case of allocation error. Use [`fallible_with_capacity`] instead if you want to /// handle memory allocation failure. /// /// All the control bytes are initialized with the [`EMPTY`] bytes. /// /// [`fallible_with_capacity`]: RawTableInner::fallible_with_capacity /// [`abort`]: https://doc.rust-lang.org/alloc/alloc/fn.handle_alloc_error.html fn with_capacity(alloc: &A, table_layout: TableLayout, capacity: usize) -> Self where A: Allocator, { // Avoid `Result::unwrap_or_else` because it bloats LLVM IR. match Self::fallible_with_capacity(alloc, table_layout, capacity, Fallibility::Infallible) { Ok(table_inner) => table_inner, // SAFETY: All allocation errors will be caught inside `RawTableInner::new_uninitialized`. Err(_) => unsafe { hint::unreachable_unchecked() }, } } /// Fixes up an insertion slot returned by the [`RawTableInner::find_insert_slot_in_group`] method. /// /// In tables smaller than the group width (`self.buckets() < Group::WIDTH`), trailing control /// bytes outside the range of the table are filled with [`EMPTY`] entries. These will unfortunately /// trigger a match of [`RawTableInner::find_insert_slot_in_group`] function. This is because /// the `Some(bit)` returned by `group.match_empty_or_deleted().lowest_set_bit()` after masking /// (`(probe_seq.pos + bit) & self.bucket_mask`) may point to a full bucket that is already occupied. /// We detect this situation here and perform a second scan starting at the beginning of the table. /// This second scan is guaranteed to find an empty slot (due to the load factor) before hitting the /// trailing control bytes (containing [`EMPTY`] bytes). /// /// If this function is called correctly, it is guaranteed to return [`InsertSlot`] with an /// index of an empty or deleted bucket in the range `0..self.buckets()` (see `Warning` and /// `Safety`). /// /// # Warning /// /// The table must have at least 1 empty or deleted `bucket`, otherwise if the table is less than /// the group width (`self.buckets() < Group::WIDTH`) this function returns an index outside of the /// table indices range `0..self.buckets()` (`0..=self.bucket_mask`). Attempt to write data at that /// index will cause immediate [`undefined behavior`]. /// /// # Safety /// /// The safety rules are directly derived from the safety rules for [`RawTableInner::ctrl`] method. /// Thus, in order to uphold those safety contracts, as well as for the correct logic of the work /// of this crate, the following rules are necessary and sufficient: /// /// * The [`RawTableInner`] must have properly initialized control bytes otherwise calling this /// function results in [`undefined behavior`]. /// /// * This function must only be used on insertion slots found by [`RawTableInner::find_insert_slot_in_group`] /// (after the `find_insert_slot_in_group` function, but before insertion into the table). /// /// * The `index` must not be greater than the `self.bucket_mask`, i.e. `(index + 1) <= self.buckets()` /// (this one is provided by the [`RawTableInner::find_insert_slot_in_group`] function). /// /// Calling this function with an index not provided by [`RawTableInner::find_insert_slot_in_group`] /// may result in [`undefined behavior`] even if the index satisfies the safety rules of the /// [`RawTableInner::ctrl`] function (`index < self.bucket_mask + 1 + Group::WIDTH`). /// /// [`RawTableInner::ctrl`]: RawTableInner::ctrl /// [`RawTableInner::find_insert_slot_in_group`]: RawTableInner::find_insert_slot_in_group /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn fix_insert_slot(&self, mut index: usize) -> InsertSlot { // SAFETY: The caller of this function ensures that `index` is in the range `0..=self.bucket_mask`. if unlikely(self.is_bucket_full(index)) { debug_assert!(self.bucket_mask < Group::WIDTH); // SAFETY: // // * Since the caller of this function ensures that the control bytes are properly // initialized and `ptr = self.ctrl(0)` points to the start of the array of control // bytes, therefore: `ctrl` is valid for reads, properly aligned to `Group::WIDTH` // and points to the properly initialized control bytes (see also // `TableLayout::calculate_layout_for` and `ptr::read`); // // * Because the caller of this function ensures that the index was provided by the // `self.find_insert_slot_in_group()` function, so for for tables larger than the // group width (self.buckets() >= Group::WIDTH), we will never end up in the given // branch, since `(probe_seq.pos + bit) & self.bucket_mask` in `find_insert_slot_in_group` // cannot return a full bucket index. For tables smaller than the group width, calling // the `unwrap_unchecked` function is also safe, as the trailing control bytes outside // the range of the table are filled with EMPTY bytes (and we know for sure that there // is at least one FULL bucket), so this second scan either finds an empty slot (due to // the load factor) or hits the trailing control bytes (containing EMPTY). index = Group::load_aligned(self.ctrl(0)) .match_empty_or_deleted() .lowest_set_bit() .unwrap_unchecked(); } InsertSlot { index } } /// Finds the position to insert something in a group. /// /// **This may have false positives and must be fixed up with `fix_insert_slot` /// before it's used.** /// /// The function is guaranteed to return the index of an empty or deleted [`Bucket`] /// in the range `0..self.buckets()` (`0..=self.bucket_mask`). #[inline] fn find_insert_slot_in_group(&self, group: &Group, probe_seq: &ProbeSeq) -> Option { let bit = group.match_empty_or_deleted().lowest_set_bit(); if likely(bit.is_some()) { // This is the same as `(probe_seq.pos + bit) % self.buckets()` because the number // of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. Some((probe_seq.pos + bit.unwrap()) & self.bucket_mask) } else { None } } /// Searches for an element in the table, or a potential slot where that element could /// be inserted (an empty or deleted [`Bucket`] index). /// /// This uses dynamic dispatch to reduce the amount of code generated, but that is /// eliminated by LLVM optimizations. /// /// This function does not make any changes to the `data` part of the table, or any /// changes to the `items` or `growth_left` field of the table. /// /// The table must have at least 1 empty or deleted `bucket`, otherwise, if the /// `eq: &mut dyn FnMut(usize) -> bool` function does not return `true`, this function /// will never return (will go into an infinite loop) for tables larger than the group /// width, or return an index outside of the table indices range if the table is less /// than the group width. /// /// This function is guaranteed to provide the `eq: &mut dyn FnMut(usize) -> bool` /// function with only `FULL` buckets' indices and return the `index` of the found /// element (as `Ok(index)`). If the element is not found and there is at least 1 /// empty or deleted [`Bucket`] in the table, the function is guaranteed to return /// [InsertSlot] with an index in the range `0..self.buckets()`, but in any case, /// if this function returns [`InsertSlot`], it will contain an index in the range /// `0..=self.buckets()`. /// /// # Safety /// /// The [`RawTableInner`] must have properly initialized control bytes otherwise calling /// this function results in [`undefined behavior`]. /// /// Attempt to write data at the [`InsertSlot`] returned by this function when the table is /// less than the group width and if there was not at least one empty or deleted bucket in /// the table will cause immediate [`undefined behavior`]. This is because in this case the /// function will return `self.bucket_mask + 1` as an index due to the trailing [`EMPTY] /// control bytes outside the table range. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn find_or_find_insert_slot_inner( &self, hash: u64, eq: &mut dyn FnMut(usize) -> bool, ) -> Result { let mut insert_slot = None; let h2_hash = h2(hash); let mut probe_seq = self.probe_seq(hash); loop { // SAFETY: // * Caller of this function ensures that the control bytes are properly initialized. // // * `ProbeSeq.pos` cannot be greater than `self.bucket_mask = self.buckets() - 1` // of the table due to masking with `self.bucket_mask` and also because mumber of // buckets is a power of two (see `self.probe_seq` function). // // * Even if `ProbeSeq.pos` returns `position == self.bucket_mask`, it is safe to // call `Group::load` due to the extended control bytes range, which is // `self.bucket_mask + 1 + Group::WIDTH` (in fact, this means that the last control // byte will never be read for the allocated table); // // * Also, even if `RawTableInner` is not already allocated, `ProbeSeq.pos` will // always return "0" (zero), so Group::load will read unaligned `Group::static_empty()` // bytes, which is safe (see RawTableInner::new). let group = unsafe { Group::load(self.ctrl(probe_seq.pos)) }; for bit in group.match_byte(h2_hash) { let index = (probe_seq.pos + bit) & self.bucket_mask; if likely(eq(index)) { return Ok(index); } } // We didn't find the element we were looking for in the group, try to get an // insertion slot from the group if we don't have one yet. if likely(insert_slot.is_none()) { insert_slot = self.find_insert_slot_in_group(&group, &probe_seq); } // Only stop the search if the group contains at least one empty element. // Otherwise, the element that we are looking for might be in a following group. if likely(group.match_empty().any_bit_set()) { // We must have found a insert slot by now, since the current group contains at // least one. For tables smaller than the group width, there will still be an // empty element in the current (and only) group due to the load factor. unsafe { // SAFETY: // * Caller of this function ensures that the control bytes are properly initialized. // // * We use this function with the slot / index found by `self.find_insert_slot_in_group` return Err(self.fix_insert_slot(insert_slot.unwrap_unchecked())); } } probe_seq.move_next(self.bucket_mask); } } /// Searches for an empty or deleted bucket which is suitable for inserting a new /// element and sets the hash for that slot. Returns an index of that slot and the /// old control byte stored in the found index. /// /// This function does not check if the given element exists in the table. Also, /// this function does not check if there is enough space in the table to insert /// a new element. Caller of the funtion must make ensure that the table has at /// least 1 empty or deleted `bucket`, otherwise this function will never return /// (will go into an infinite loop) for tables larger than the group width, or /// return an index outside of the table indices range if the table is less than /// the group width. /// /// If there is at least 1 empty or deleted `bucket` in the table, the function is /// guaranteed to return an `index` in the range `0..self.buckets()`, but in any case, /// if this function returns an `index` it will be in the range `0..=self.buckets()`. /// /// This function does not make any changes to the `data` parts of the table, /// or any changes to the `items` or `growth_left` field of the table. /// /// # Safety /// /// The safety rules are directly derived from the safety rules for the /// [`RawTableInner::set_ctrl_h2`] and [`RawTableInner::find_insert_slot`] methods. /// Thus, in order to uphold the safety contracts for that methods, as well as for /// the correct logic of the work of this crate, you must observe the following rules /// when calling this function: /// /// * The [`RawTableInner`] has already been allocated and has properly initialized /// control bytes otherwise calling this function results in [`undefined behavior`]. /// /// * The caller of this function must ensure that the "data" parts of the table /// will have an entry in the returned index (matching the given hash) right /// after calling this function. /// /// Attempt to write data at the `index` returned by this function when the table is /// less than the group width and if there was not at least one empty or deleted bucket in /// the table will cause immediate [`undefined behavior`]. This is because in this case the /// function will return `self.bucket_mask + 1` as an index due to the trailing [`EMPTY] /// control bytes outside the table range. /// /// The caller must independently increase the `items` field of the table, and also, /// if the old control byte was [`EMPTY`], then decrease the table's `growth_left` /// field, and do not change it if the old control byte was [`DELETED`]. /// /// See also [`Bucket::as_ptr`] method, for more information about of properly removing /// or saving `element` from / into the [`RawTable`] / [`RawTableInner`]. /// /// [`Bucket::as_ptr`]: Bucket::as_ptr /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// [`RawTableInner::ctrl`]: RawTableInner::ctrl /// [`RawTableInner::set_ctrl_h2`]: RawTableInner::set_ctrl_h2 /// [`RawTableInner::find_insert_slot`]: RawTableInner::find_insert_slot #[inline] unsafe fn prepare_insert_slot(&mut self, hash: u64) -> (usize, u8) { // SAFETY: Caller of this function ensures that the control bytes are properly initialized. let index: usize = self.find_insert_slot(hash).index; // SAFETY: // 1. The `find_insert_slot` function either returns an `index` less than or // equal to `self.buckets() = self.bucket_mask + 1` of the table, or never // returns if it cannot find an empty or deleted slot. // 2. The caller of this function guarantees that the table has already been // allocated let old_ctrl = *self.ctrl(index); self.set_ctrl_h2(index, hash); (index, old_ctrl) } /// Searches for an empty or deleted bucket which is suitable for inserting /// a new element, returning the `index` for the new [`Bucket`]. /// /// This function does not make any changes to the `data` part of the table, or any /// changes to the `items` or `growth_left` field of the table. /// /// The table must have at least 1 empty or deleted `bucket`, otherwise this function /// will never return (will go into an infinite loop) for tables larger than the group /// width, or return an index outside of the table indices range if the table is less /// than the group width. /// /// If there is at least 1 empty or deleted `bucket` in the table, the function is /// guaranteed to return [`InsertSlot`] with an index in the range `0..self.buckets()`, /// but in any case, if this function returns [`InsertSlot`], it will contain an index /// in the range `0..=self.buckets()`. /// /// # Safety /// /// The [`RawTableInner`] must have properly initialized control bytes otherwise calling /// this function results in [`undefined behavior`]. /// /// Attempt to write data at the [`InsertSlot`] returned by this function when the table is /// less than the group width and if there was not at least one empty or deleted bucket in /// the table will cause immediate [`undefined behavior`]. This is because in this case the /// function will return `self.bucket_mask + 1` as an index due to the trailing [`EMPTY] /// control bytes outside the table range. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn find_insert_slot(&self, hash: u64) -> InsertSlot { let mut probe_seq = self.probe_seq(hash); loop { // SAFETY: // * Caller of this function ensures that the control bytes are properly initialized. // // * `ProbeSeq.pos` cannot be greater than `self.bucket_mask = self.buckets() - 1` // of the table due to masking with `self.bucket_mask` and also because mumber of // buckets is a power of two (see `self.probe_seq` function). // // * Even if `ProbeSeq.pos` returns `position == self.bucket_mask`, it is safe to // call `Group::load` due to the extended control bytes range, which is // `self.bucket_mask + 1 + Group::WIDTH` (in fact, this means that the last control // byte will never be read for the allocated table); // // * Also, even if `RawTableInner` is not already allocated, `ProbeSeq.pos` will // always return "0" (zero), so Group::load will read unaligned `Group::static_empty()` // bytes, which is safe (see RawTableInner::new). let group = unsafe { Group::load(self.ctrl(probe_seq.pos)) }; let index = self.find_insert_slot_in_group(&group, &probe_seq); if likely(index.is_some()) { // SAFETY: // * Caller of this function ensures that the control bytes are properly initialized. // // * We use this function with the slot / index found by `self.find_insert_slot_in_group` unsafe { return self.fix_insert_slot(index.unwrap_unchecked()); } } probe_seq.move_next(self.bucket_mask); } } /// Searches for an element in a table, returning the `index` of the found element. /// This uses dynamic dispatch to reduce the amount of code generated, but it is /// eliminated by LLVM optimizations. /// /// This function does not make any changes to the `data` part of the table, or any /// changes to the `items` or `growth_left` field of the table. /// /// The table must have at least 1 empty `bucket`, otherwise, if the /// `eq: &mut dyn FnMut(usize) -> bool` function does not return `true`, /// this function will also never return (will go into an infinite loop). /// /// This function is guaranteed to provide the `eq: &mut dyn FnMut(usize) -> bool` /// function with only `FULL` buckets' indices and return the `index` of the found /// element as `Some(index)`, so the index will always be in the range /// `0..self.buckets()`. /// /// # Safety /// /// The [`RawTableInner`] must have properly initialized control bytes otherwise calling /// this function results in [`undefined behavior`]. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline(always)] unsafe fn find_inner(&self, hash: u64, eq: &mut dyn FnMut(usize) -> bool) -> Option { let h2_hash = h2(hash); let mut probe_seq = self.probe_seq(hash); loop { // SAFETY: // * Caller of this function ensures that the control bytes are properly initialized. // // * `ProbeSeq.pos` cannot be greater than `self.bucket_mask = self.buckets() - 1` // of the table due to masking with `self.bucket_mask`. // // * Even if `ProbeSeq.pos` returns `position == self.bucket_mask`, it is safe to // call `Group::load` due to the extended control bytes range, which is // `self.bucket_mask + 1 + Group::WIDTH` (in fact, this means that the last control // byte will never be read for the allocated table); // // * Also, even if `RawTableInner` is not already allocated, `ProbeSeq.pos` will // always return "0" (zero), so Group::load will read unaligned `Group::static_empty()` // bytes, which is safe (see RawTableInner::new_in). let group = unsafe { Group::load(self.ctrl(probe_seq.pos)) }; for bit in group.match_byte(h2_hash) { // This is the same as `(probe_seq.pos + bit) % self.buckets()` because the number // of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. let index = (probe_seq.pos + bit) & self.bucket_mask; if likely(eq(index)) { return Some(index); } } if likely(group.match_empty().any_bit_set()) { return None; } probe_seq.move_next(self.bucket_mask); } } /// Prepares for rehashing data in place (that is, without allocating new memory). /// Converts all full index `control bytes` to `DELETED` and all `DELETED` control /// bytes to `EMPTY`, i.e. performs the following conversion: /// /// - `EMPTY` control bytes -> `EMPTY`; /// - `DELETED` control bytes -> `EMPTY`; /// - `FULL` control bytes -> `DELETED`. /// /// This function does not make any changes to the `data` parts of the table, /// or any changes to the `items` or `growth_left` field of the table. /// /// # Safety /// /// You must observe the following safety rules when calling this function: /// /// * The [`RawTableInner`] has already been allocated; /// /// * The caller of this function must convert the `DELETED` bytes back to `FULL` /// bytes when re-inserting them into their ideal position (which was impossible /// to do during the first insert due to tombstones). If the caller does not do /// this, then calling this function may result in a memory leak. /// /// * The [`RawTableInner`] must have properly initialized control bytes otherwise /// calling this function results in [`undefined behavior`]. /// /// Calling this function on a table that has not been allocated results in /// [`undefined behavior`]. /// /// See also [`Bucket::as_ptr`] method, for more information about of properly removing /// or saving `data element` from / into the [`RawTable`] / [`RawTableInner`]. /// /// [`Bucket::as_ptr`]: Bucket::as_ptr /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[allow(clippy::mut_mut)] #[inline] unsafe fn prepare_rehash_in_place(&mut self) { // Bulk convert all full control bytes to DELETED, and all DELETED control bytes to EMPTY. // This effectively frees up all buckets containing a DELETED entry. // // SAFETY: // 1. `i` is guaranteed to be within bounds since we are iterating from zero to `buckets - 1`; // 2. Even if `i` will be `i == self.bucket_mask`, it is safe to call `Group::load_aligned` // due to the extended control bytes range, which is `self.bucket_mask + 1 + Group::WIDTH`; // 3. The caller of this function guarantees that [`RawTableInner`] has already been allocated; // 4. We can use `Group::load_aligned` and `Group::store_aligned` here since we start from 0 // and go to the end with a step equal to `Group::WIDTH` (see TableLayout::calculate_layout_for). for i in (0..self.buckets()).step_by(Group::WIDTH) { let group = Group::load_aligned(self.ctrl(i)); let group = group.convert_special_to_empty_and_full_to_deleted(); group.store_aligned(self.ctrl(i)); } // Fix up the trailing control bytes. See the comments in set_ctrl // for the handling of tables smaller than the group width. // // SAFETY: The caller of this function guarantees that [`RawTableInner`] // has already been allocated if unlikely(self.buckets() < Group::WIDTH) { // SAFETY: We have `self.bucket_mask + 1 + Group::WIDTH` number of control bytes, // so copying `self.buckets() == self.bucket_mask + 1` bytes with offset equal to // `Group::WIDTH` is safe self.ctrl(0) .copy_to(self.ctrl(Group::WIDTH), self.buckets()); } else { // SAFETY: We have `self.bucket_mask + 1 + Group::WIDTH` number of // control bytes,so copying `Group::WIDTH` bytes with offset equal // to `self.buckets() == self.bucket_mask + 1` is safe self.ctrl(0) .copy_to(self.ctrl(self.buckets()), Group::WIDTH); } } /// Returns an iterator over every element in the table. /// /// # Safety /// /// If any of the following conditions are violated, the result /// is [`undefined behavior`]: /// /// * The caller has to ensure that the `RawTableInner` outlives the /// `RawIter`. Because we cannot make the `next` method unsafe on /// the `RawIter` struct, we have to make the `iter` method unsafe. /// /// * The [`RawTableInner`] must have properly initialized control bytes. /// /// The type `T` must be the actual type of the elements stored in the table, /// otherwise using the returned [`RawIter`] results in [`undefined behavior`]. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn iter(&self) -> RawIter { // SAFETY: // 1. Since the caller of this function ensures that the control bytes // are properly initialized and `self.data_end()` points to the start // of the array of control bytes, therefore: `ctrl` is valid for reads, // properly aligned to `Group::WIDTH` and points to the properly initialized // control bytes. // 2. `data` bucket index in the table is equal to the `ctrl` index (i.e. // equal to zero). // 3. We pass the exact value of buckets of the table to the function. // // `ctrl` points here (to the start // of the first control byte `CT0`) // ∨ // [Pad], T_n, ..., T1, T0, |CT0, CT1, ..., CT_n|, CTa_0, CTa_1, ..., CTa_m // \________ ________/ // \/ // `n = buckets - 1`, i.e. `RawTableInner::buckets() - 1` // // where: T0...T_n - our stored data; // CT0...CT_n - control bytes or metadata for `data`. // CTa_0...CTa_m - additional control bytes, where `m = Group::WIDTH - 1` (so that the search // with loading `Group` bytes from the heap works properly, even if the result // of `h1(hash) & self.bucket_mask` is equal to `self.bucket_mask`). See also // `RawTableInner::set_ctrl` function. // // P.S. `h1(hash) & self.bucket_mask` is the same as `hash as usize % self.buckets()` because the number // of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. let data = Bucket::from_base_index(self.data_end(), 0); RawIter { // SAFETY: See explanation above iter: RawIterRange::new(self.ctrl.as_ptr(), data, self.buckets()), items: self.items, } } /// Executes the destructors (if any) of the values stored in the table. /// /// # Note /// /// This function does not erase the control bytes of the table and does /// not make any changes to the `items` or `growth_left` fields of the /// table. If necessary, the caller of this function must manually set /// up these table fields, for example using the [`clear_no_drop`] function. /// /// Be careful during calling this function, because drop function of /// the elements can panic, and this can leave table in an inconsistent /// state. /// /// # Safety /// /// The type `T` must be the actual type of the elements stored in the table, /// otherwise calling this function may result in [`undefined behavior`]. /// /// If `T` is a type that should be dropped and **the table is not empty**, /// calling this function more than once results in [`undefined behavior`]. /// /// If `T` is not [`Copy`], attempting to use values stored in the table after /// calling this function may result in [`undefined behavior`]. /// /// It is safe to call this function on a table that has not been allocated, /// on a table with uninitialized control bytes, and on a table with no actual /// data but with `Full` control bytes if `self.items == 0`. /// /// See also [`Bucket::drop`] / [`Bucket::as_ptr`] methods, for more information /// about of properly removing or saving `element` from / into the [`RawTable`] / /// [`RawTableInner`]. /// /// [`Bucket::drop`]: Bucket::drop /// [`Bucket::as_ptr`]: Bucket::as_ptr /// [`clear_no_drop`]: RawTableInner::clear_no_drop /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html unsafe fn drop_elements(&mut self) { // Check that `self.items != 0`. Protects against the possibility // of creating an iterator on an table with uninitialized control bytes. if T::NEEDS_DROP && self.items != 0 { // SAFETY: We know for sure that RawTableInner will outlive the // returned `RawIter` iterator, and the caller of this function // must uphold the safety contract for `drop_elements` method. for item in self.iter::() { // SAFETY: The caller must uphold the safety contract for // `drop_elements` method. item.drop(); } } } /// Executes the destructors (if any) of the values stored in the table and than /// deallocates the table. /// /// # Note /// /// Calling this function automatically makes invalid (dangling) all instances of /// buckets ([`Bucket`]) and makes invalid (dangling) the `ctrl` field of the table. /// /// This function does not make any changes to the `bucket_mask`, `items` or `growth_left` /// fields of the table. If necessary, the caller of this function must manually set /// up these table fields. /// /// # Safety /// /// If any of the following conditions are violated, the result is [`undefined behavior`]: /// /// * Calling this function more than once; /// /// * The type `T` must be the actual type of the elements stored in the table. /// /// * The `alloc` must be the same [`Allocator`] as the `Allocator` that was used /// to allocate this table. /// /// * The `table_layout` must be the same [`TableLayout`] as the `TableLayout` that /// was used to allocate this table. /// /// The caller of this function should pay attention to the possibility of the /// elements' drop function panicking, because this: /// /// * May leave the table in an inconsistent state; /// /// * Memory is never deallocated, so a memory leak may occur. /// /// Attempt to use the `ctrl` field of the table (dereference) after calling this /// function results in [`undefined behavior`]. /// /// It is safe to call this function on a table that has not been allocated, /// on a table with uninitialized control bytes, and on a table with no actual /// data but with `Full` control bytes if `self.items == 0`. /// /// See also [`RawTableInner::drop_elements`] or [`RawTableInner::free_buckets`] /// for more information. /// /// [`RawTableInner::drop_elements`]: RawTableInner::drop_elements /// [`RawTableInner::free_buckets`]: RawTableInner::free_buckets /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html unsafe fn drop_inner_table(&mut self, alloc: &A, table_layout: TableLayout) { if !self.is_empty_singleton() { unsafe { // SAFETY: The caller must uphold the safety contract for `drop_inner_table` method. self.drop_elements::(); // SAFETY: // 1. We have checked that our table is allocated. // 2. The caller must uphold the safety contract for `drop_inner_table` method. self.free_buckets(alloc, table_layout); } } } /// Returns a pointer to an element in the table (convenience for /// `Bucket::from_base_index(self.data_end::(), index)`). /// /// The caller must ensure that the `RawTableInner` outlives the returned [`Bucket`], /// otherwise using it may result in [`undefined behavior`]. /// /// # Safety /// /// If `mem::size_of::() != 0`, then the safety rules are directly derived from the /// safety rules of the [`Bucket::from_base_index`] function. Therefore, when calling /// this function, the following safety rules must be observed: /// /// * The table must already be allocated; /// /// * The `index` must not be greater than the number returned by the [`RawTableInner::buckets`] /// function, i.e. `(index + 1) <= self.buckets()`. /// /// * The type `T` must be the actual type of the elements stored in the table, otherwise /// using the returned [`Bucket`] may result in [`undefined behavior`]. /// /// It is safe to call this function with index of zero (`index == 0`) on a table that has /// not been allocated, but using the returned [`Bucket`] results in [`undefined behavior`]. /// /// If `mem::size_of::() == 0`, then the only requirement is that the `index` must /// not be greater than the number returned by the [`RawTable::buckets`] function, i.e. /// `(index + 1) <= self.buckets()`. /// /// ```none /// If mem::size_of::() != 0 then return a pointer to the `element` in the `data part` of the table /// (we start counting from "0", so that in the expression T[n], the "n" index actually one less than /// the "buckets" number of our `RawTableInner`, i.e. "n = RawTableInner::buckets() - 1"): /// /// `table.bucket(3).as_ptr()` returns a pointer that points here in the `data` /// part of the `RawTableInner`, i.e. to the start of T3 (see [`Bucket::as_ptr`]) /// | /// | `base = table.data_end::()` points here /// | (to the start of CT0 or to the end of T0) /// v v /// [Pad], T_n, ..., |T3|, T2, T1, T0, |CT0, CT1, CT2, CT3, ..., CT_n, CTa_0, CTa_1, ..., CTa_m /// ^ \__________ __________/ /// `table.bucket(3)` returns a pointer that points \/ /// here in the `data` part of the `RawTableInner` additional control bytes /// (to the end of T3) `m = Group::WIDTH - 1` /// /// where: T0...T_n - our stored data; /// CT0...CT_n - control bytes or metadata for `data`; /// CTa_0...CTa_m - additional control bytes (so that the search with loading `Group` bytes from /// the heap works properly, even if the result of `h1(hash) & self.bucket_mask` /// is equal to `self.bucket_mask`). See also `RawTableInner::set_ctrl` function. /// /// P.S. `h1(hash) & self.bucket_mask` is the same as `hash as usize % self.buckets()` because the number /// of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. /// ``` /// /// [`Bucket::from_base_index`]: Bucket::from_base_index /// [`RawTableInner::buckets`]: RawTableInner::buckets /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn bucket(&self, index: usize) -> Bucket { debug_assert_ne!(self.bucket_mask, 0); debug_assert!(index < self.buckets()); Bucket::from_base_index(self.data_end(), index) } /// Returns a raw `*mut u8` pointer to the start of the `data` element in the table /// (convenience for `self.data_end::().as_ptr().sub((index + 1) * size_of)`). /// /// The caller must ensure that the `RawTableInner` outlives the returned `*mut u8`, /// otherwise using it may result in [`undefined behavior`]. /// /// # Safety /// /// If any of the following conditions are violated, the result is [`undefined behavior`]: /// /// * The table must already be allocated; /// /// * The `index` must not be greater than the number returned by the [`RawTableInner::buckets`] /// function, i.e. `(index + 1) <= self.buckets()`; /// /// * The `size_of` must be equal to the size of the elements stored in the table; /// /// ```none /// If mem::size_of::() != 0 then return a pointer to the `element` in the `data part` of the table /// (we start counting from "0", so that in the expression T[n], the "n" index actually one less than /// the "buckets" number of our `RawTableInner`, i.e. "n = RawTableInner::buckets() - 1"): /// /// `table.bucket_ptr(3, mem::size_of::())` returns a pointer that points here in the /// `data` part of the `RawTableInner`, i.e. to the start of T3 /// | /// | `base = table.data_end::()` points here /// | (to the start of CT0 or to the end of T0) /// v v /// [Pad], T_n, ..., |T3|, T2, T1, T0, |CT0, CT1, CT2, CT3, ..., CT_n, CTa_0, CTa_1, ..., CTa_m /// \__________ __________/ /// \/ /// additional control bytes /// `m = Group::WIDTH - 1` /// /// where: T0...T_n - our stored data; /// CT0...CT_n - control bytes or metadata for `data`; /// CTa_0...CTa_m - additional control bytes (so that the search with loading `Group` bytes from /// the heap works properly, even if the result of `h1(hash) & self.bucket_mask` /// is equal to `self.bucket_mask`). See also `RawTableInner::set_ctrl` function. /// /// P.S. `h1(hash) & self.bucket_mask` is the same as `hash as usize % self.buckets()` because the number /// of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. /// ``` /// /// [`RawTableInner::buckets`]: RawTableInner::buckets /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn bucket_ptr(&self, index: usize, size_of: usize) -> *mut u8 { debug_assert_ne!(self.bucket_mask, 0); debug_assert!(index < self.buckets()); let base: *mut u8 = self.data_end().as_ptr(); base.sub((index + 1) * size_of) } /// Returns pointer to one past last `data` element in the table as viewed from /// the start point of the allocation (convenience for `self.ctrl.cast()`). /// /// This function actually returns a pointer to the end of the `data element` at /// index "0" (zero). /// /// The caller must ensure that the `RawTableInner` outlives the returned [`NonNull`], /// otherwise using it may result in [`undefined behavior`]. /// /// # Note /// /// The type `T` must be the actual type of the elements stored in the table, otherwise /// using the returned [`NonNull`] may result in [`undefined behavior`]. /// /// ```none /// `table.data_end::()` returns pointer that points here /// (to the end of `T0`) /// ∨ /// [Pad], T_n, ..., T1, T0, |CT0, CT1, ..., CT_n|, CTa_0, CTa_1, ..., CTa_m /// \________ ________/ /// \/ /// `n = buckets - 1`, i.e. `RawTableInner::buckets() - 1` /// /// where: T0...T_n - our stored data; /// CT0...CT_n - control bytes or metadata for `data`. /// CTa_0...CTa_m - additional control bytes, where `m = Group::WIDTH - 1` (so that the search /// with loading `Group` bytes from the heap works properly, even if the result /// of `h1(hash) & self.bucket_mask` is equal to `self.bucket_mask`). See also /// `RawTableInner::set_ctrl` function. /// /// P.S. `h1(hash) & self.bucket_mask` is the same as `hash as usize % self.buckets()` because the number /// of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. /// ``` /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] fn data_end(&self) -> NonNull { self.ctrl.cast() } /// Returns an iterator-like object for a probe sequence on the table. /// /// This iterator never terminates, but is guaranteed to visit each bucket /// group exactly once. The loop using `probe_seq` must terminate upon /// reaching a group containing an empty bucket. #[inline] fn probe_seq(&self, hash: u64) -> ProbeSeq { ProbeSeq { // This is the same as `hash as usize % self.buckets()` because the number // of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. pos: h1(hash) & self.bucket_mask, stride: 0, } } /// Returns the index of a bucket for which a value must be inserted if there is enough rooom /// in the table, otherwise returns error #[cfg(feature = "raw")] #[inline] unsafe fn prepare_insert_no_grow(&mut self, hash: u64) -> Result { let index = self.find_insert_slot(hash).index; let old_ctrl = *self.ctrl(index); if unlikely(self.growth_left == 0 && special_is_empty(old_ctrl)) { Err(()) } else { self.record_item_insert_at(index, old_ctrl, hash); Ok(index) } } #[inline] unsafe fn record_item_insert_at(&mut self, index: usize, old_ctrl: u8, hash: u64) { self.growth_left -= usize::from(special_is_empty(old_ctrl)); self.set_ctrl_h2(index, hash); self.items += 1; } #[inline] fn is_in_same_group(&self, i: usize, new_i: usize, hash: u64) -> bool { let probe_seq_pos = self.probe_seq(hash).pos; let probe_index = |pos: usize| (pos.wrapping_sub(probe_seq_pos) & self.bucket_mask) / Group::WIDTH; probe_index(i) == probe_index(new_i) } /// Sets a control byte to the hash, and possibly also the replicated control byte at /// the end of the array. /// /// This function does not make any changes to the `data` parts of the table, /// or any changes to the `items` or `growth_left` field of the table. /// /// # Safety /// /// The safety rules are directly derived from the safety rules for [`RawTableInner::set_ctrl`] /// method. Thus, in order to uphold the safety contracts for the method, you must observe the /// following rules when calling this function: /// /// * The [`RawTableInner`] has already been allocated; /// /// * The `index` must not be greater than the `RawTableInner.bucket_mask`, i.e. /// `index <= RawTableInner.bucket_mask` or, in other words, `(index + 1)` must /// be no greater than the number returned by the function [`RawTableInner::buckets`]. /// /// Calling this function on a table that has not been allocated results in [`undefined behavior`]. /// /// See also [`Bucket::as_ptr`] method, for more information about of properly removing /// or saving `data element` from / into the [`RawTable`] / [`RawTableInner`]. /// /// [`RawTableInner::set_ctrl`]: RawTableInner::set_ctrl /// [`RawTableInner::buckets`]: RawTableInner::buckets /// [`Bucket::as_ptr`]: Bucket::as_ptr /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn set_ctrl_h2(&mut self, index: usize, hash: u64) { // SAFETY: The caller must uphold the safety rules for the [`RawTableInner::set_ctrl_h2`] self.set_ctrl(index, h2(hash)); } /// Replaces the hash in the control byte at the given index with the provided one, /// and possibly also replicates the new control byte at the end of the array of control /// bytes, returning the old control byte. /// /// This function does not make any changes to the `data` parts of the table, /// or any changes to the `items` or `growth_left` field of the table. /// /// # Safety /// /// The safety rules are directly derived from the safety rules for [`RawTableInner::set_ctrl_h2`] /// and [`RawTableInner::ctrl`] methods. Thus, in order to uphold the safety contracts for both /// methods, you must observe the following rules when calling this function: /// /// * The [`RawTableInner`] has already been allocated; /// /// * The `index` must not be greater than the `RawTableInner.bucket_mask`, i.e. /// `index <= RawTableInner.bucket_mask` or, in other words, `(index + 1)` must /// be no greater than the number returned by the function [`RawTableInner::buckets`]. /// /// Calling this function on a table that has not been allocated results in [`undefined behavior`]. /// /// See also [`Bucket::as_ptr`] method, for more information about of properly removing /// or saving `data element` from / into the [`RawTable`] / [`RawTableInner`]. /// /// [`RawTableInner::set_ctrl_h2`]: RawTableInner::set_ctrl_h2 /// [`RawTableInner::buckets`]: RawTableInner::buckets /// [`Bucket::as_ptr`]: Bucket::as_ptr /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn replace_ctrl_h2(&mut self, index: usize, hash: u64) -> u8 { // SAFETY: The caller must uphold the safety rules for the [`RawTableInner::replace_ctrl_h2`] let prev_ctrl = *self.ctrl(index); self.set_ctrl_h2(index, hash); prev_ctrl } /// Sets a control byte, and possibly also the replicated control byte at /// the end of the array. /// /// This function does not make any changes to the `data` parts of the table, /// or any changes to the `items` or `growth_left` field of the table. /// /// # Safety /// /// You must observe the following safety rules when calling this function: /// /// * The [`RawTableInner`] has already been allocated; /// /// * The `index` must not be greater than the `RawTableInner.bucket_mask`, i.e. /// `index <= RawTableInner.bucket_mask` or, in other words, `(index + 1)` must /// be no greater than the number returned by the function [`RawTableInner::buckets`]. /// /// Calling this function on a table that has not been allocated results in [`undefined behavior`]. /// /// See also [`Bucket::as_ptr`] method, for more information about of properly removing /// or saving `data element` from / into the [`RawTable`] / [`RawTableInner`]. /// /// [`RawTableInner::buckets`]: RawTableInner::buckets /// [`Bucket::as_ptr`]: Bucket::as_ptr /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn set_ctrl(&mut self, index: usize, ctrl: u8) { // Replicate the first Group::WIDTH control bytes at the end of // the array without using a branch. If the tables smaller than // the group width (self.buckets() < Group::WIDTH), // `index2 = Group::WIDTH + index`, otherwise `index2` is: // // - If index >= Group::WIDTH then index == index2. // - Otherwise index2 == self.bucket_mask + 1 + index. // // The very last replicated control byte is never actually read because // we mask the initial index for unaligned loads, but we write it // anyways because it makes the set_ctrl implementation simpler. // // If there are fewer buckets than Group::WIDTH then this code will // replicate the buckets at the end of the trailing group. For example // with 2 buckets and a group size of 4, the control bytes will look // like this: // // Real | Replicated // --------------------------------------------- // | [A] | [B] | [EMPTY] | [EMPTY] | [A] | [B] | // --------------------------------------------- // This is the same as `(index.wrapping_sub(Group::WIDTH)) % self.buckets() + Group::WIDTH` // because the number of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. let index2 = ((index.wrapping_sub(Group::WIDTH)) & self.bucket_mask) + Group::WIDTH; // SAFETY: The caller must uphold the safety rules for the [`RawTableInner::set_ctrl`] *self.ctrl(index) = ctrl; *self.ctrl(index2) = ctrl; } /// Returns a pointer to a control byte. /// /// # Safety /// /// For the allocated [`RawTableInner`], the result is [`Undefined Behavior`], /// if the `index` is greater than the `self.bucket_mask + 1 + Group::WIDTH`. /// In that case, calling this function with `index == self.bucket_mask + 1 + Group::WIDTH` /// will return a pointer to the end of the allocated table and it is useless on its own. /// /// Calling this function with `index >= self.bucket_mask + 1 + Group::WIDTH` on a /// table that has not been allocated results in [`Undefined Behavior`]. /// /// So to satisfy both requirements you should always follow the rule that /// `index < self.bucket_mask + 1 + Group::WIDTH` /// /// Calling this function on [`RawTableInner`] that are not already allocated is safe /// for read-only purpose. /// /// See also [`Bucket::as_ptr()`] method, for more information about of properly removing /// or saving `data element` from / into the [`RawTable`] / [`RawTableInner`]. /// /// [`Bucket::as_ptr()`]: Bucket::as_ptr() /// [`Undefined Behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn ctrl(&self, index: usize) -> *mut u8 { debug_assert!(index < self.num_ctrl_bytes()); // SAFETY: The caller must uphold the safety rules for the [`RawTableInner::ctrl`] self.ctrl.as_ptr().add(index) } #[inline] fn buckets(&self) -> usize { self.bucket_mask + 1 } /// Checks whether the bucket at `index` is full. /// /// # Safety /// /// The caller must ensure `index` is less than the number of buckets. #[inline] unsafe fn is_bucket_full(&self, index: usize) -> bool { debug_assert!(index < self.buckets()); is_full(*self.ctrl(index)) } #[inline] fn num_ctrl_bytes(&self) -> usize { self.bucket_mask + 1 + Group::WIDTH } #[inline] fn is_empty_singleton(&self) -> bool { self.bucket_mask == 0 } /// Attempts to allocate a new hash table with at least enough capacity /// for inserting the given number of elements without reallocating, /// and return it inside ScopeGuard to protect against panic in the hash /// function. /// /// # Note /// /// It is recommended (but not required): /// /// * That the new table's `capacity` be greater than or equal to `self.items`. /// /// * The `alloc` is the same [`Allocator`] as the `Allocator` used /// to allocate this table. /// /// * The `table_layout` is the same [`TableLayout`] as the `TableLayout` used /// to allocate this table. /// /// If `table_layout` does not match the `TableLayout` that was used to allocate /// this table, then using `mem::swap` with the `self` and the new table returned /// by this function results in [`undefined behavior`]. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[allow(clippy::mut_mut)] #[inline] fn prepare_resize<'a, A>( &self, alloc: &'a A, table_layout: TableLayout, capacity: usize, fallibility: Fallibility, ) -> Result, TryReserveError> where A: Allocator, { debug_assert!(self.items <= capacity); // Allocate and initialize the new table. let new_table = RawTableInner::fallible_with_capacity(alloc, table_layout, capacity, fallibility)?; // The hash function may panic, in which case we simply free the new // table without dropping any elements that may have been copied into // it. // // This guard is also used to free the old table on success, see // the comment at the bottom of this function. Ok(guard(new_table, move |self_| { if !self_.is_empty_singleton() { // SAFETY: // 1. We have checked that our table is allocated. // 2. We know for sure that the `alloc` and `table_layout` matches the // [`Allocator`] and [`TableLayout`] used to allocate this table. unsafe { self_.free_buckets(alloc, table_layout) }; } })) } /// Reserves or rehashes to make room for `additional` more elements. /// /// This uses dynamic dispatch to reduce the amount of /// code generated, but it is eliminated by LLVM optimizations when inlined. /// /// # Safety /// /// If any of the following conditions are violated, the result is /// [`undefined behavior`]: /// /// * The `alloc` must be the same [`Allocator`] as the `Allocator` used /// to allocate this table. /// /// * The `layout` must be the same [`TableLayout`] as the `TableLayout` /// used to allocate this table. /// /// * The `drop` function (`fn(*mut u8)`) must be the actual drop function of /// the elements stored in the table. /// /// * The [`RawTableInner`] must have properly initialized control bytes. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[allow(clippy::inline_always)] #[inline(always)] unsafe fn reserve_rehash_inner( &mut self, alloc: &A, additional: usize, hasher: &dyn Fn(&mut Self, usize) -> u64, fallibility: Fallibility, layout: TableLayout, drop: Option, ) -> Result<(), TryReserveError> where A: Allocator, { // Avoid `Option::ok_or_else` because it bloats LLVM IR. let new_items = match self.items.checked_add(additional) { Some(new_items) => new_items, None => return Err(fallibility.capacity_overflow()), }; let full_capacity = bucket_mask_to_capacity(self.bucket_mask); if new_items <= full_capacity / 2 { // Rehash in-place without re-allocating if we have plenty of spare // capacity that is locked up due to DELETED entries. // SAFETY: // 1. We know for sure that `[`RawTableInner`]` has already been allocated // (since new_items <= full_capacity / 2); // 2. The caller ensures that `drop` function is the actual drop function of // the elements stored in the table. // 3. The caller ensures that `layout` matches the [`TableLayout`] that was // used to allocate this table. // 4. The caller ensures that the control bytes of the `RawTableInner` // are already initialized. self.rehash_in_place(hasher, layout.size, drop); Ok(()) } else { // Otherwise, conservatively resize to at least the next size up // to avoid churning deletes into frequent rehashes. // // SAFETY: // 1. We know for sure that `capacity >= self.items`. // 2. The caller ensures that `alloc` and `layout` matches the [`Allocator`] and // [`TableLayout`] that were used to allocate this table. // 3. The caller ensures that the control bytes of the `RawTableInner` // are already initialized. self.resize_inner( alloc, usize::max(new_items, full_capacity + 1), hasher, fallibility, layout, ) } } /// Returns an iterator over full buckets indices in the table. /// /// # Safety /// /// Behavior is undefined if any of the following conditions are violated: /// /// * The caller has to ensure that the `RawTableInner` outlives the /// `FullBucketsIndices`. Because we cannot make the `next` method /// unsafe on the `FullBucketsIndices` struct, we have to make the /// `full_buckets_indices` method unsafe. /// /// * The [`RawTableInner`] must have properly initialized control bytes. #[inline(always)] unsafe fn full_buckets_indices(&self) -> FullBucketsIndices { // SAFETY: // 1. Since the caller of this function ensures that the control bytes // are properly initialized and `self.ctrl(0)` points to the start // of the array of control bytes, therefore: `ctrl` is valid for reads, // properly aligned to `Group::WIDTH` and points to the properly initialized // control bytes. // 2. The value of `items` is equal to the amount of data (values) added // to the table. // // `ctrl` points here (to the start // of the first control byte `CT0`) // ∨ // [Pad], T_n, ..., T1, T0, |CT0, CT1, ..., CT_n|, Group::WIDTH // \________ ________/ // \/ // `n = buckets - 1`, i.e. `RawTableInner::buckets() - 1` // // where: T0...T_n - our stored data; // CT0...CT_n - control bytes or metadata for `data`. let ctrl = NonNull::new_unchecked(self.ctrl(0)); FullBucketsIndices { // Load the first group // SAFETY: See explanation above. current_group: Group::load_aligned(ctrl.as_ptr()).match_full().into_iter(), group_first_index: 0, ctrl, items: self.items, } } /// Allocates a new table of a different size and moves the contents of the /// current table into it. /// /// This uses dynamic dispatch to reduce the amount of /// code generated, but it is eliminated by LLVM optimizations when inlined. /// /// # Safety /// /// If any of the following conditions are violated, the result is /// [`undefined behavior`]: /// /// * The `alloc` must be the same [`Allocator`] as the `Allocator` used /// to allocate this table; /// /// * The `layout` must be the same [`TableLayout`] as the `TableLayout` /// used to allocate this table; /// /// * The [`RawTableInner`] must have properly initialized control bytes. /// /// The caller of this function must ensure that `capacity >= self.items` /// otherwise: /// /// * If `self.items != 0`, calling of this function with `capacity == 0` /// results in [`undefined behavior`]. /// /// * If `capacity_to_buckets(capacity) < Group::WIDTH` and /// `self.items > capacity_to_buckets(capacity)` calling this function /// results in [`undefined behavior`]. /// /// * If `capacity_to_buckets(capacity) >= Group::WIDTH` and /// `self.items > capacity_to_buckets(capacity)` calling this function /// are never return (will go into an infinite loop). /// /// Note: It is recommended (but not required) that the new table's `capacity` /// be greater than or equal to `self.items`. In case if `capacity <= self.items` /// this function can never return. See [`RawTableInner::find_insert_slot`] for /// more information. /// /// [`RawTableInner::find_insert_slot`]: RawTableInner::find_insert_slot /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[allow(clippy::inline_always)] #[inline(always)] unsafe fn resize_inner( &mut self, alloc: &A, capacity: usize, hasher: &dyn Fn(&mut Self, usize) -> u64, fallibility: Fallibility, layout: TableLayout, ) -> Result<(), TryReserveError> where A: Allocator, { // SAFETY: We know for sure that `alloc` and `layout` matches the [`Allocator`] and [`TableLayout`] // that were used to allocate this table. let mut new_table = self.prepare_resize(alloc, layout, capacity, fallibility)?; // SAFETY: We know for sure that RawTableInner will outlive the // returned `FullBucketsIndices` iterator, and the caller of this // function ensures that the control bytes are properly initialized. for full_byte_index in self.full_buckets_indices() { // This may panic. let hash = hasher(self, full_byte_index); // SAFETY: // We can use a simpler version of insert() here since: // 1. There are no DELETED entries. // 2. We know there is enough space in the table. // 3. All elements are unique. // 4. The caller of this function guarantees that `capacity > 0` // so `new_table` must already have some allocated memory. // 5. We set `growth_left` and `items` fields of the new table // after the loop. // 6. We insert into the table, at the returned index, the data // matching the given hash immediately after calling this function. let (new_index, _) = new_table.prepare_insert_slot(hash); // SAFETY: // // * `src` is valid for reads of `layout.size` bytes, since the // table is alive and the `full_byte_index` is guaranteed to be // within bounds (see `FullBucketsIndices::next_impl`); // // * `dst` is valid for writes of `layout.size` bytes, since the // caller ensures that `table_layout` matches the [`TableLayout`] // that was used to allocate old table and we have the `new_index` // returned by `prepare_insert_slot`. // // * Both `src` and `dst` are properly aligned. // // * Both `src` and `dst` point to different region of memory. ptr::copy_nonoverlapping( self.bucket_ptr(full_byte_index, layout.size), new_table.bucket_ptr(new_index, layout.size), layout.size, ); } // The hash function didn't panic, so we can safely set the // `growth_left` and `items` fields of the new table. new_table.growth_left -= self.items; new_table.items = self.items; // We successfully copied all elements without panicking. Now replace // self with the new table. The old table will have its memory freed but // the items will not be dropped (since they have been moved into the // new table). // SAFETY: The caller ensures that `table_layout` matches the [`TableLayout`] // that was used to allocate this table. mem::swap(self, &mut new_table); Ok(()) } /// Rehashes the contents of the table in place (i.e. without changing the /// allocation). /// /// If `hasher` panics then some the table's contents may be lost. /// /// This uses dynamic dispatch to reduce the amount of /// code generated, but it is eliminated by LLVM optimizations when inlined. /// /// # Safety /// /// If any of the following conditions are violated, the result is [`undefined behavior`]: /// /// * The `size_of` must be equal to the size of the elements stored in the table; /// /// * The `drop` function (`fn(*mut u8)`) must be the actual drop function of /// the elements stored in the table. /// /// * The [`RawTableInner`] has already been allocated; /// /// * The [`RawTableInner`] must have properly initialized control bytes. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[allow(clippy::inline_always)] #[cfg_attr(feature = "inline-more", inline(always))] #[cfg_attr(not(feature = "inline-more"), inline)] unsafe fn rehash_in_place( &mut self, hasher: &dyn Fn(&mut Self, usize) -> u64, size_of: usize, drop: Option, ) { // If the hash function panics then properly clean up any elements // that we haven't rehashed yet. We unfortunately can't preserve the // element since we lost their hash and have no way of recovering it // without risking another panic. self.prepare_rehash_in_place(); let mut guard = guard(self, move |self_| { if let Some(drop) = drop { for i in 0..self_.buckets() { if *self_.ctrl(i) == DELETED { self_.set_ctrl(i, EMPTY); drop(self_.bucket_ptr(i, size_of)); self_.items -= 1; } } } self_.growth_left = bucket_mask_to_capacity(self_.bucket_mask) - self_.items; }); // At this point, DELETED elements are elements that we haven't // rehashed yet. Find them and re-insert them at their ideal // position. 'outer: for i in 0..guard.buckets() { if *guard.ctrl(i) != DELETED { continue; } let i_p = guard.bucket_ptr(i, size_of); 'inner: loop { // Hash the current item let hash = hasher(*guard, i); // Search for a suitable place to put it // // SAFETY: Caller of this function ensures that the control bytes // are properly initialized. let new_i = guard.find_insert_slot(hash).index; // Probing works by scanning through all of the control // bytes in groups, which may not be aligned to the group // size. If both the new and old position fall within the // same unaligned group, then there is no benefit in moving // it and we can just continue to the next item. if likely(guard.is_in_same_group(i, new_i, hash)) { guard.set_ctrl_h2(i, hash); continue 'outer; } let new_i_p = guard.bucket_ptr(new_i, size_of); // We are moving the current item to a new position. Write // our H2 to the control byte of the new position. let prev_ctrl = guard.replace_ctrl_h2(new_i, hash); if prev_ctrl == EMPTY { guard.set_ctrl(i, EMPTY); // If the target slot is empty, simply move the current // element into the new slot and clear the old control // byte. ptr::copy_nonoverlapping(i_p, new_i_p, size_of); continue 'outer; } else { // If the target slot is occupied, swap the two elements // and then continue processing the element that we just // swapped into the old slot. debug_assert_eq!(prev_ctrl, DELETED); ptr::swap_nonoverlapping(i_p, new_i_p, size_of); continue 'inner; } } } guard.growth_left = bucket_mask_to_capacity(guard.bucket_mask) - guard.items; mem::forget(guard); } /// Deallocates the table without dropping any entries. /// /// # Note /// /// This function must be called only after [`drop_elements`](RawTableInner::drop_elements), /// else it can lead to leaking of memory. Also calling this function automatically /// makes invalid (dangling) all instances of buckets ([`Bucket`]) and makes invalid /// (dangling) the `ctrl` field of the table. /// /// # Safety /// /// If any of the following conditions are violated, the result is [`Undefined Behavior`]: /// /// * The [`RawTableInner`] has already been allocated; /// /// * The `alloc` must be the same [`Allocator`] as the `Allocator` that was used /// to allocate this table. /// /// * The `table_layout` must be the same [`TableLayout`] as the `TableLayout` that was used /// to allocate this table. /// /// See also [`GlobalAlloc::dealloc`] or [`Allocator::deallocate`] for more information. /// /// [`Undefined Behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// [`GlobalAlloc::dealloc`]: https://doc.rust-lang.org/alloc/alloc/trait.GlobalAlloc.html#tymethod.dealloc /// [`Allocator::deallocate`]: https://doc.rust-lang.org/alloc/alloc/trait.Allocator.html#tymethod.deallocate #[inline] unsafe fn free_buckets(&mut self, alloc: &A, table_layout: TableLayout) where A: Allocator, { // SAFETY: The caller must uphold the safety contract for `free_buckets` // method. let (ptr, layout) = self.allocation_info(table_layout); alloc.deallocate(ptr, layout); } /// Returns a pointer to the allocated memory and the layout that was used to /// allocate the table. /// /// # Safety /// /// Caller of this function must observe the following safety rules: /// /// * The [`RawTableInner`] has already been allocated, otherwise /// calling this function results in [`undefined behavior`] /// /// * The `table_layout` must be the same [`TableLayout`] as the `TableLayout` /// that was used to allocate this table. Failure to comply with this condition /// may result in [`undefined behavior`]. /// /// See also [`GlobalAlloc::dealloc`] or [`Allocator::deallocate`] for more information. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// [`GlobalAlloc::dealloc`]: https://doc.rust-lang.org/alloc/alloc/trait.GlobalAlloc.html#tymethod.dealloc /// [`Allocator::deallocate`]: https://doc.rust-lang.org/alloc/alloc/trait.Allocator.html#tymethod.deallocate #[inline] unsafe fn allocation_info(&self, table_layout: TableLayout) -> (NonNull, Layout) { debug_assert!( !self.is_empty_singleton(), "this function can only be called on non-empty tables" ); // Avoid `Option::unwrap_or_else` because it bloats LLVM IR. let (layout, ctrl_offset) = match table_layout.calculate_layout_for(self.buckets()) { Some(lco) => lco, None => unsafe { hint::unreachable_unchecked() }, }; ( // SAFETY: The caller must uphold the safety contract for `allocation_info` method. unsafe { NonNull::new_unchecked(self.ctrl.as_ptr().sub(ctrl_offset)) }, layout, ) } /// Returns a pointer to the allocated memory and the layout that was used to /// allocate the table. If [`RawTableInner`] has not been allocated, this /// function return `dangling` pointer and `()` (unit) layout. /// /// # Safety /// /// The `table_layout` must be the same [`TableLayout`] as the `TableLayout` /// that was used to allocate this table. Failure to comply with this condition /// may result in [`undefined behavior`]. /// /// See also [`GlobalAlloc::dealloc`] or [`Allocator::deallocate`] for more information. /// /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// [`GlobalAlloc::dealloc`]: https://doc.rust-lang.org/alloc/alloc/trait.GlobalAlloc.html#tymethod.dealloc /// [`Allocator::deallocate`]: https://doc.rust-lang.org/alloc/alloc/trait.Allocator.html#tymethod.deallocate #[cfg(feature = "raw")] unsafe fn allocation_info_or_zero(&self, table_layout: TableLayout) -> (NonNull, Layout) { if self.is_empty_singleton() { (NonNull::dangling(), Layout::new::<()>()) } else { // SAFETY: // 1. We have checked that our table is allocated. // 2. The caller ensures that `table_layout` matches the [`TableLayout`] // that was used to allocate this table. unsafe { self.allocation_info(table_layout) } } } /// Marks all table buckets as empty without dropping their contents. #[inline] fn clear_no_drop(&mut self) { if !self.is_empty_singleton() { unsafe { self.ctrl(0).write_bytes(EMPTY, self.num_ctrl_bytes()); } } self.items = 0; self.growth_left = bucket_mask_to_capacity(self.bucket_mask); } /// Erases the [`Bucket`]'s control byte at the given index so that it does not /// triggered as full, decreases the `items` of the table and, if it can be done, /// increases `self.growth_left`. /// /// This function does not actually erase / drop the [`Bucket`] itself, i.e. it /// does not make any changes to the `data` parts of the table. The caller of this /// function must take care to properly drop the `data`, otherwise calling this /// function may result in a memory leak. /// /// # Safety /// /// You must observe the following safety rules when calling this function: /// /// * The [`RawTableInner`] has already been allocated; /// /// * It must be the full control byte at the given position; /// /// * The `index` must not be greater than the `RawTableInner.bucket_mask`, i.e. /// `index <= RawTableInner.bucket_mask` or, in other words, `(index + 1)` must /// be no greater than the number returned by the function [`RawTableInner::buckets`]. /// /// Calling this function on a table that has not been allocated results in [`undefined behavior`]. /// /// Calling this function on a table with no elements is unspecified, but calling subsequent /// functions is likely to result in [`undefined behavior`] due to overflow subtraction /// (`self.items -= 1 cause overflow when self.items == 0`). /// /// See also [`Bucket::as_ptr`] method, for more information about of properly removing /// or saving `data element` from / into the [`RawTable`] / [`RawTableInner`]. /// /// [`RawTableInner::buckets`]: RawTableInner::buckets /// [`Bucket::as_ptr`]: Bucket::as_ptr /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline] unsafe fn erase(&mut self, index: usize) { debug_assert!(self.is_bucket_full(index)); // This is the same as `index.wrapping_sub(Group::WIDTH) % self.buckets()` because // the number of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`. let index_before = index.wrapping_sub(Group::WIDTH) & self.bucket_mask; // SAFETY: // - The caller must uphold the safety contract for `erase` method; // - `index_before` is guaranteed to be in range due to masking with `self.bucket_mask` let empty_before = Group::load(self.ctrl(index_before)).match_empty(); let empty_after = Group::load(self.ctrl(index)).match_empty(); // Inserting and searching in the map is performed by two key functions: // // - The `find_insert_slot` function that looks up the index of any `EMPTY` or `DELETED` // slot in a group to be able to insert. If it doesn't find an `EMPTY` or `DELETED` // slot immediately in the first group, it jumps to the next `Group` looking for it, // and so on until it has gone through all the groups in the control bytes. // // - The `find_inner` function that looks for the index of the desired element by looking // at all the `FULL` bytes in the group. If it did not find the element right away, and // there is no `EMPTY` byte in the group, then this means that the `find_insert_slot` // function may have found a suitable slot in the next group. Therefore, `find_inner` // jumps further, and if it does not find the desired element and again there is no `EMPTY` // byte, then it jumps further, and so on. The search stops only if `find_inner` function // finds the desired element or hits an `EMPTY` slot/byte. // // Accordingly, this leads to two consequences: // // - The map must have `EMPTY` slots (bytes); // // - You can't just mark the byte to be erased as `EMPTY`, because otherwise the `find_inner` // function may stumble upon an `EMPTY` byte before finding the desired element and stop // searching. // // Thus it is necessary to check all bytes after and before the erased element. If we are in // a contiguous `Group` of `FULL` or `DELETED` bytes (the number of `FULL` or `DELETED` bytes // before and after is greater than or equal to `Group::WIDTH`), then we must mark our byte as // `DELETED` in order for the `find_inner` function to go further. On the other hand, if there // is at least one `EMPTY` slot in the `Group`, then the `find_inner` function will still stumble // upon an `EMPTY` byte, so we can safely mark our erased byte as `EMPTY` as well. // // Finally, since `index_before == (index.wrapping_sub(Group::WIDTH) & self.bucket_mask) == index` // and given all of the above, tables smaller than the group width (self.buckets() < Group::WIDTH) // cannot have `DELETED` bytes. // // Note that in this context `leading_zeros` refers to the bytes at the end of a group, while // `trailing_zeros` refers to the bytes at the beginning of a group. let ctrl = if empty_before.leading_zeros() + empty_after.trailing_zeros() >= Group::WIDTH { DELETED } else { self.growth_left += 1; EMPTY }; // SAFETY: the caller must uphold the safety contract for `erase` method. self.set_ctrl(index, ctrl); self.items -= 1; } } impl Clone for RawTable { fn clone(&self) -> Self { if self.table.is_empty_singleton() { Self::new_in(self.alloc.clone()) } else { unsafe { // Avoid `Result::ok_or_else` because it bloats LLVM IR. // // SAFETY: This is safe as we are taking the size of an already allocated table // and therefore сapacity overflow cannot occur, `self.table.buckets()` is power // of two and all allocator errors will be caught inside `RawTableInner::new_uninitialized`. let mut new_table = match Self::new_uninitialized( self.alloc.clone(), self.table.buckets(), Fallibility::Infallible, ) { Ok(table) => table, Err(_) => hint::unreachable_unchecked(), }; // Cloning elements may fail (the clone function may panic). But we don't // need to worry about uninitialized control bits, since: // 1. The number of items (elements) in the table is zero, which means that // the control bits will not be readed by Drop function. // 2. The `clone_from_spec` method will first copy all control bits from // `self` (thus initializing them). But this will not affect the `Drop` // function, since the `clone_from_spec` function sets `items` only after // successfully clonning all elements. new_table.clone_from_spec(self); new_table } } } fn clone_from(&mut self, source: &Self) { if source.table.is_empty_singleton() { let mut old_inner = mem::replace(&mut self.table, RawTableInner::NEW); unsafe { // SAFETY: // 1. We call the function only once; // 2. We know for sure that `alloc` and `table_layout` matches the [`Allocator`] // and [`TableLayout`] that were used to allocate this table. // 3. If any elements' drop function panics, then there will only be a memory leak, // because we have replaced the inner table with a new one. old_inner.drop_inner_table::(&self.alloc, Self::TABLE_LAYOUT); } } else { unsafe { // Make sure that if any panics occurs, we clear the table and // leave it in an empty state. let mut self_ = guard(self, |self_| { self_.clear_no_drop(); }); // First, drop all our elements without clearing the control // bytes. If this panics then the scope guard will clear the // table, leaking any elements that were not dropped yet. // // This leak is unavoidable: we can't try dropping more elements // since this could lead to another panic and abort the process. // // SAFETY: If something gets wrong we clear our table right after // dropping the elements, so there is no double drop, since `items` // will be equal to zero. self_.table.drop_elements::(); // If necessary, resize our table to match the source. if self_.buckets() != source.buckets() { let new_inner = match RawTableInner::new_uninitialized( &self_.alloc, Self::TABLE_LAYOUT, source.buckets(), Fallibility::Infallible, ) { Ok(table) => table, Err(_) => hint::unreachable_unchecked(), }; // Replace the old inner with new uninitialized one. It's ok, since if something gets // wrong `ScopeGuard` will initialize all control bytes and leave empty table. let mut old_inner = mem::replace(&mut self_.table, new_inner); if !old_inner.is_empty_singleton() { // SAFETY: // 1. We have checked that our table is allocated. // 2. We know for sure that `alloc` and `table_layout` matches // the [`Allocator`] and [`TableLayout`] that were used to allocate this table. old_inner.free_buckets(&self_.alloc, Self::TABLE_LAYOUT); } } // Cloning elements may fail (the clone function may panic), but the `ScopeGuard` // inside the `clone_from_impl` function will take care of that, dropping all // cloned elements if necessary. Our `ScopeGuard` will clear the table. self_.clone_from_spec(source); // Disarm the scope guard if cloning was successful. ScopeGuard::into_inner(self_); } } } } /// Specialization of `clone_from` for `Copy` types trait RawTableClone { unsafe fn clone_from_spec(&mut self, source: &Self); } impl RawTableClone for RawTable { default_fn! { #[cfg_attr(feature = "inline-more", inline)] unsafe fn clone_from_spec(&mut self, source: &Self) { self.clone_from_impl(source); } } } #[cfg(feature = "nightly")] impl RawTableClone for RawTable { #[cfg_attr(feature = "inline-more", inline)] unsafe fn clone_from_spec(&mut self, source: &Self) { source .table .ctrl(0) .copy_to_nonoverlapping(self.table.ctrl(0), self.table.num_ctrl_bytes()); source .data_start() .as_ptr() .copy_to_nonoverlapping(self.data_start().as_ptr(), self.table.buckets()); self.table.items = source.table.items; self.table.growth_left = source.table.growth_left; } } impl RawTable { /// Common code for clone and clone_from. Assumes: /// - `self.buckets() == source.buckets()`. /// - Any existing elements have been dropped. /// - The control bytes are not initialized yet. #[cfg_attr(feature = "inline-more", inline)] unsafe fn clone_from_impl(&mut self, source: &Self) { // Copy the control bytes unchanged. We do this in a single pass source .table .ctrl(0) .copy_to_nonoverlapping(self.table.ctrl(0), self.table.num_ctrl_bytes()); // The cloning of elements may panic, in which case we need // to make sure we drop only the elements that have been // cloned so far. let mut guard = guard((0, &mut *self), |(index, self_)| { if T::NEEDS_DROP { for i in 0..*index { if self_.is_bucket_full(i) { self_.bucket(i).drop(); } } } }); for from in source.iter() { let index = source.bucket_index(&from); let to = guard.1.bucket(index); to.write(from.as_ref().clone()); // Update the index in case we need to unwind. guard.0 = index + 1; } // Successfully cloned all items, no need to clean up. mem::forget(guard); self.table.items = source.table.items; self.table.growth_left = source.table.growth_left; } /// Variant of `clone_from` to use when a hasher is available. #[cfg(feature = "raw")] pub fn clone_from_with_hasher(&mut self, source: &Self, hasher: impl Fn(&T) -> u64) { // If we have enough capacity in the table, just clear it and insert // elements one by one. We don't do this if we have the same number of // buckets as the source since we can just copy the contents directly // in that case. if self.table.buckets() != source.table.buckets() && bucket_mask_to_capacity(self.table.bucket_mask) >= source.len() { self.clear(); let mut guard_self = guard(&mut *self, |self_| { // Clear the partially copied table if a panic occurs, otherwise // items and growth_left will be out of sync with the contents // of the table. self_.clear(); }); unsafe { for item in source.iter() { // This may panic. let item = item.as_ref().clone(); let hash = hasher(&item); // We can use a simpler version of insert() here since: // - there are no DELETED entries. // - we know there is enough space in the table. // - all elements are unique. let (index, _) = guard_self.table.prepare_insert_slot(hash); guard_self.bucket(index).write(item); } } // Successfully cloned all items, no need to clean up. mem::forget(guard_self); self.table.items = source.table.items; self.table.growth_left -= source.table.items; } else { self.clone_from(source); } } } impl Default for RawTable { #[inline] fn default() -> Self { Self::new_in(Default::default()) } } #[cfg(feature = "nightly")] unsafe impl<#[may_dangle] T, A: Allocator> Drop for RawTable { #[cfg_attr(feature = "inline-more", inline)] fn drop(&mut self) { unsafe { // SAFETY: // 1. We call the function only once; // 2. We know for sure that `alloc` and `table_layout` matches the [`Allocator`] // and [`TableLayout`] that were used to allocate this table. // 3. If the drop function of any elements fails, then only a memory leak will occur, // and we don't care because we are inside the `Drop` function of the `RawTable`, // so there won't be any table left in an inconsistent state. self.table .drop_inner_table::(&self.alloc, Self::TABLE_LAYOUT); } } } #[cfg(not(feature = "nightly"))] impl Drop for RawTable { #[cfg_attr(feature = "inline-more", inline)] fn drop(&mut self) { unsafe { // SAFETY: // 1. We call the function only once; // 2. We know for sure that `alloc` and `table_layout` matches the [`Allocator`] // and [`TableLayout`] that were used to allocate this table. // 3. If the drop function of any elements fails, then only a memory leak will occur, // and we don't care because we are inside the `Drop` function of the `RawTable`, // so there won't be any table left in an inconsistent state. self.table .drop_inner_table::(&self.alloc, Self::TABLE_LAYOUT); } } } impl IntoIterator for RawTable { type Item = T; type IntoIter = RawIntoIter; #[cfg_attr(feature = "inline-more", inline)] fn into_iter(self) -> RawIntoIter { unsafe { let iter = self.iter(); self.into_iter_from(iter) } } } /// Iterator over a sub-range of a table. Unlike `RawIter` this iterator does /// not track an item count. pub(crate) struct RawIterRange { // Mask of full buckets in the current group. Bits are cleared from this // mask as each element is processed. current_group: BitMaskIter, // Pointer to the buckets for the current group. data: Bucket, // Pointer to the next group of control bytes, // Must be aligned to the group size. next_ctrl: *const u8, // Pointer one past the last control byte of this range. end: *const u8, } impl RawIterRange { /// Returns a `RawIterRange` covering a subset of a table. /// /// # Safety /// /// If any of the following conditions are violated, the result is /// [`undefined behavior`]: /// /// * `ctrl` must be [valid] for reads, i.e. table outlives the `RawIterRange`; /// /// * `ctrl` must be properly aligned to the group size (Group::WIDTH); /// /// * `ctrl` must point to the array of properly initialized control bytes; /// /// * `data` must be the [`Bucket`] at the `ctrl` index in the table; /// /// * the value of `len` must be less than or equal to the number of table buckets, /// and the returned value of `ctrl.as_ptr().add(len).offset_from(ctrl.as_ptr())` /// must be positive. /// /// * The `ctrl.add(len)` pointer must be either in bounds or one /// byte past the end of the same [allocated table]. /// /// * The `len` must be a power of two. /// /// [valid]: https://doc.rust-lang.org/std/ptr/index.html#safety /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[cfg_attr(feature = "inline-more", inline)] unsafe fn new(ctrl: *const u8, data: Bucket, len: usize) -> Self { debug_assert_ne!(len, 0); debug_assert_eq!(ctrl as usize % Group::WIDTH, 0); // SAFETY: The caller must uphold the safety rules for the [`RawIterRange::new`] let end = ctrl.add(len); // Load the first group and advance ctrl to point to the next group // SAFETY: The caller must uphold the safety rules for the [`RawIterRange::new`] let current_group = Group::load_aligned(ctrl).match_full(); let next_ctrl = ctrl.add(Group::WIDTH); Self { current_group: current_group.into_iter(), data, next_ctrl, end, } } /// Splits a `RawIterRange` into two halves. /// /// Returns `None` if the remaining range is smaller than or equal to the /// group width. #[cfg_attr(feature = "inline-more", inline)] #[cfg(feature = "rayon")] pub(crate) fn split(mut self) -> (Self, Option>) { unsafe { if self.end <= self.next_ctrl { // Nothing to split if the group that we are current processing // is the last one. (self, None) } else { // len is the remaining number of elements after the group that // we are currently processing. It must be a multiple of the // group size (small tables are caught by the check above). let len = offset_from(self.end, self.next_ctrl); debug_assert_eq!(len % Group::WIDTH, 0); // Split the remaining elements into two halves, but round the // midpoint down in case there is an odd number of groups // remaining. This ensures that: // - The tail is at least 1 group long. // - The split is roughly even considering we still have the // current group to process. let mid = (len / 2) & !(Group::WIDTH - 1); let tail = Self::new( self.next_ctrl.add(mid), self.data.next_n(Group::WIDTH).next_n(mid), len - mid, ); debug_assert_eq!( self.data.next_n(Group::WIDTH).next_n(mid).ptr, tail.data.ptr ); debug_assert_eq!(self.end, tail.end); self.end = self.next_ctrl.add(mid); debug_assert_eq!(self.end.add(Group::WIDTH), tail.next_ctrl); (self, Some(tail)) } } } /// # Safety /// If DO_CHECK_PTR_RANGE is false, caller must ensure that we never try to iterate /// after yielding all elements. #[cfg_attr(feature = "inline-more", inline)] unsafe fn next_impl(&mut self) -> Option> { loop { if let Some(index) = self.current_group.next() { return Some(self.data.next_n(index)); } if DO_CHECK_PTR_RANGE && self.next_ctrl >= self.end { return None; } // We might read past self.end up to the next group boundary, // but this is fine because it only occurs on tables smaller // than the group size where the trailing control bytes are all // EMPTY. On larger tables self.end is guaranteed to be aligned // to the group size (since tables are power-of-two sized). self.current_group = Group::load_aligned(self.next_ctrl).match_full().into_iter(); self.data = self.data.next_n(Group::WIDTH); self.next_ctrl = self.next_ctrl.add(Group::WIDTH); } } /// Folds every element into an accumulator by applying an operation, /// returning the final result. /// /// `fold_impl()` takes three arguments: the number of items remaining in /// the iterator, an initial value, and a closure with two arguments: an /// 'accumulator', and an element. The closure returns the value that the /// accumulator should have for the next iteration. /// /// The initial value is the value the accumulator will have on the first call. /// /// After applying this closure to every element of the iterator, `fold_impl()` /// returns the accumulator. /// /// # Safety /// /// If any of the following conditions are violated, the result is /// [`Undefined Behavior`]: /// /// * The [`RawTableInner`] / [`RawTable`] must be alive and not moved, /// i.e. table outlives the `RawIterRange`; /// /// * The provided `n` value must match the actual number of items /// in the table. /// /// [`Undefined Behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[allow(clippy::while_let_on_iterator)] #[cfg_attr(feature = "inline-more", inline)] unsafe fn fold_impl(mut self, mut n: usize, mut acc: B, mut f: F) -> B where F: FnMut(B, Bucket) -> B, { loop { while let Some(index) = self.current_group.next() { // The returned `index` will always be in the range `0..Group::WIDTH`, // so that calling `self.data.next_n(index)` is safe (see detailed explanation below). debug_assert!(n != 0); let bucket = self.data.next_n(index); acc = f(acc, bucket); n -= 1; } if n == 0 { return acc; } // SAFETY: The caller of this function ensures that: // // 1. The provided `n` value matches the actual number of items in the table; // 2. The table is alive and did not moved. // // Taking the above into account, we always stay within the bounds, because: // // 1. For tables smaller than the group width (self.buckets() <= Group::WIDTH), // we will never end up in the given branch, since we should have already // yielded all the elements of the table. // // 2. For tables larger than the group width. The number of buckets is a // power of two (2 ^ n), Group::WIDTH is also power of two (2 ^ k). Since // `(2 ^ n) > (2 ^ k)`, than `(2 ^ n) % (2 ^ k) = 0`. As we start from the // start of the array of control bytes, and never try to iterate after // getting all the elements, the last `self.current_group` will read bytes // from the `self.buckets() - Group::WIDTH` index. We know also that // `self.current_group.next()` will always retun indices within the range // `0..Group::WIDTH`. // // Knowing all of the above and taking into account that we are synchronizing // the `self.data` index with the index we used to read the `self.current_group`, // the subsequent `self.data.next_n(index)` will always return a bucket with // an index number less than `self.buckets()`. // // The last `self.next_ctrl`, whose index would be `self.buckets()`, will never // actually be read, since we should have already yielded all the elements of // the table. self.current_group = Group::load_aligned(self.next_ctrl).match_full().into_iter(); self.data = self.data.next_n(Group::WIDTH); self.next_ctrl = self.next_ctrl.add(Group::WIDTH); } } } // We make raw iterators unconditionally Send and Sync, and let the PhantomData // in the actual iterator implementations determine the real Send/Sync bounds. unsafe impl Send for RawIterRange {} unsafe impl Sync for RawIterRange {} impl Clone for RawIterRange { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Self { data: self.data.clone(), next_ctrl: self.next_ctrl, current_group: self.current_group, end: self.end, } } } impl Iterator for RawIterRange { type Item = Bucket; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option> { unsafe { // SAFETY: We set checker flag to true. self.next_impl::() } } #[inline] fn size_hint(&self) -> (usize, Option) { // We don't have an item count, so just guess based on the range size. let remaining_buckets = if self.end > self.next_ctrl { unsafe { offset_from(self.end, self.next_ctrl) } } else { 0 }; // Add a group width to include the group we are currently processing. (0, Some(Group::WIDTH + remaining_buckets)) } } impl FusedIterator for RawIterRange {} /// Iterator which returns a raw pointer to every full bucket in the table. /// /// For maximum flexibility this iterator is not bound by a lifetime, but you /// must observe several rules when using it: /// - You must not free the hash table while iterating (including via growing/shrinking). /// - It is fine to erase a bucket that has been yielded by the iterator. /// - Erasing a bucket that has not yet been yielded by the iterator may still /// result in the iterator yielding that bucket (unless `reflect_remove` is called). /// - It is unspecified whether an element inserted after the iterator was /// created will be yielded by that iterator (unless `reflect_insert` is called). /// - The order in which the iterator yields bucket is unspecified and may /// change in the future. pub struct RawIter { pub(crate) iter: RawIterRange, items: usize, } impl RawIter { /// Refresh the iterator so that it reflects a removal from the given bucket. /// /// For the iterator to remain valid, this method must be called once /// for each removed bucket before `next` is called again. /// /// This method should be called _before_ the removal is made. It is not necessary to call this /// method if you are removing an item that this iterator yielded in the past. #[cfg(feature = "raw")] pub unsafe fn reflect_remove(&mut self, b: &Bucket) { self.reflect_toggle_full(b, false); } /// Refresh the iterator so that it reflects an insertion into the given bucket. /// /// For the iterator to remain valid, this method must be called once /// for each insert before `next` is called again. /// /// This method does not guarantee that an insertion of a bucket with a greater /// index than the last one yielded will be reflected in the iterator. /// /// This method should be called _after_ the given insert is made. #[cfg(feature = "raw")] pub unsafe fn reflect_insert(&mut self, b: &Bucket) { self.reflect_toggle_full(b, true); } /// Refresh the iterator so that it reflects a change to the state of the given bucket. #[cfg(feature = "raw")] unsafe fn reflect_toggle_full(&mut self, b: &Bucket, is_insert: bool) { if b.as_ptr() > self.iter.data.as_ptr() { // The iterator has already passed the bucket's group. // So the toggle isn't relevant to this iterator. return; } if self.iter.next_ctrl < self.iter.end && b.as_ptr() <= self.iter.data.next_n(Group::WIDTH).as_ptr() { // The iterator has not yet reached the bucket's group. // We don't need to reload anything, but we do need to adjust the item count. if cfg!(debug_assertions) { // Double-check that the user isn't lying to us by checking the bucket state. // To do that, we need to find its control byte. We know that self.iter.data is // at self.iter.next_ctrl - Group::WIDTH, so we work from there: let offset = offset_from(self.iter.data.as_ptr(), b.as_ptr()); let ctrl = self.iter.next_ctrl.sub(Group::WIDTH).add(offset); // This method should be called _before_ a removal, or _after_ an insert, // so in both cases the ctrl byte should indicate that the bucket is full. assert!(is_full(*ctrl)); } if is_insert { self.items += 1; } else { self.items -= 1; } return; } // The iterator is at the bucket group that the toggled bucket is in. // We need to do two things: // // - Determine if the iterator already yielded the toggled bucket. // If it did, we're done. // - Otherwise, update the iterator cached group so that it won't // yield a to-be-removed bucket, or _will_ yield a to-be-added bucket. // We'll also need to update the item count accordingly. if let Some(index) = self.iter.current_group.0.lowest_set_bit() { let next_bucket = self.iter.data.next_n(index); if b.as_ptr() > next_bucket.as_ptr() { // The toggled bucket is "before" the bucket the iterator would yield next. We // therefore don't need to do anything --- the iterator has already passed the // bucket in question. // // The item count must already be correct, since a removal or insert "prior" to // the iterator's position wouldn't affect the item count. } else { // The removed bucket is an upcoming bucket. We need to make sure it does _not_ // get yielded, and also that it's no longer included in the item count. // // NOTE: We can't just reload the group here, both since that might reflect // inserts we've already passed, and because that might inadvertently unset the // bits for _other_ removals. If we do that, we'd have to also decrement the // item count for those other bits that we unset. But the presumably subsequent // call to reflect for those buckets might _also_ decrement the item count. // Instead, we _just_ flip the bit for the particular bucket the caller asked // us to reflect. let our_bit = offset_from(self.iter.data.as_ptr(), b.as_ptr()); let was_full = self.iter.current_group.flip(our_bit); debug_assert_ne!(was_full, is_insert); if is_insert { self.items += 1; } else { self.items -= 1; } if cfg!(debug_assertions) { if b.as_ptr() == next_bucket.as_ptr() { // The removed bucket should no longer be next debug_assert_ne!(self.iter.current_group.0.lowest_set_bit(), Some(index)); } else { // We should not have changed what bucket comes next. debug_assert_eq!(self.iter.current_group.0.lowest_set_bit(), Some(index)); } } } } else { // We must have already iterated past the removed item. } } unsafe fn drop_elements(&mut self) { if T::NEEDS_DROP && self.items != 0 { for item in self { item.drop(); } } } } impl Clone for RawIter { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Self { iter: self.iter.clone(), items: self.items, } } } impl Iterator for RawIter { type Item = Bucket; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option> { // Inner iterator iterates over buckets // so it can do unnecessary work if we already yielded all items. if self.items == 0 { return None; } let nxt = unsafe { // SAFETY: We check number of items to yield using `items` field. self.iter.next_impl::() }; debug_assert!(nxt.is_some()); self.items -= 1; nxt } #[inline] fn size_hint(&self) -> (usize, Option) { (self.items, Some(self.items)) } #[inline] fn fold(self, init: B, f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { unsafe { self.iter.fold_impl(self.items, init, f) } } } impl ExactSizeIterator for RawIter {} impl FusedIterator for RawIter {} /// Iterator which returns an index of every full bucket in the table. /// /// For maximum flexibility this iterator is not bound by a lifetime, but you /// must observe several rules when using it: /// - You must not free the hash table while iterating (including via growing/shrinking). /// - It is fine to erase a bucket that has been yielded by the iterator. /// - Erasing a bucket that has not yet been yielded by the iterator may still /// result in the iterator yielding index of that bucket. /// - It is unspecified whether an element inserted after the iterator was /// created will be yielded by that iterator. /// - The order in which the iterator yields indices of the buckets is unspecified /// and may change in the future. pub(crate) struct FullBucketsIndices { // Mask of full buckets in the current group. Bits are cleared from this // mask as each element is processed. current_group: BitMaskIter, // Initial value of the bytes' indices of the current group (relative // to the start of the control bytes). group_first_index: usize, // Pointer to the current group of control bytes, // Must be aligned to the group size (Group::WIDTH). ctrl: NonNull, // Number of elements in the table. items: usize, } impl FullBucketsIndices { /// Advances the iterator and returns the next value. /// /// # Safety /// /// If any of the following conditions are violated, the result is /// [`Undefined Behavior`]: /// /// * The [`RawTableInner`] / [`RawTable`] must be alive and not moved, /// i.e. table outlives the `FullBucketsIndices`; /// /// * It never tries to iterate after getting all elements. /// /// [`Undefined Behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[inline(always)] unsafe fn next_impl(&mut self) -> Option { loop { if let Some(index) = self.current_group.next() { // The returned `self.group_first_index + index` will always // be in the range `0..self.buckets()`. See explanation below. return Some(self.group_first_index + index); } // SAFETY: The caller of this function ensures that: // // 1. It never tries to iterate after getting all the elements; // 2. The table is alive and did not moved; // 3. The first `self.ctrl` pointed to the start of the array of control bytes. // // Taking the above into account, we always stay within the bounds, because: // // 1. For tables smaller than the group width (self.buckets() <= Group::WIDTH), // we will never end up in the given branch, since we should have already // yielded all the elements of the table. // // 2. For tables larger than the group width. The number of buckets is a // power of two (2 ^ n), Group::WIDTH is also power of two (2 ^ k). Since // `(2 ^ n) > (2 ^ k)`, than `(2 ^ n) % (2 ^ k) = 0`. As we start from the // the start of the array of control bytes, and never try to iterate after // getting all the elements, the last `self.ctrl` will be equal to // the `self.buckets() - Group::WIDTH`, so `self.current_group.next()` // will always contains indices within the range `0..Group::WIDTH`, // and subsequent `self.group_first_index + index` will always return a // number less than `self.buckets()`. self.ctrl = NonNull::new_unchecked(self.ctrl.as_ptr().add(Group::WIDTH)); // SAFETY: See explanation above. self.current_group = Group::load_aligned(self.ctrl.as_ptr()) .match_full() .into_iter(); self.group_first_index += Group::WIDTH; } } } impl Iterator for FullBucketsIndices { type Item = usize; /// Advances the iterator and returns the next value. It is up to /// the caller to ensure that the `RawTable` outlives the `FullBucketsIndices`, /// because we cannot make the `next` method unsafe. #[inline(always)] fn next(&mut self) -> Option { // Return if we already yielded all items. if self.items == 0 { return None; } let nxt = unsafe { // SAFETY: // 1. We check number of items to yield using `items` field. // 2. The caller ensures that the table is alive and has not moved. self.next_impl() }; debug_assert!(nxt.is_some()); self.items -= 1; nxt } #[inline(always)] fn size_hint(&self) -> (usize, Option) { (self.items, Some(self.items)) } } impl ExactSizeIterator for FullBucketsIndices {} impl FusedIterator for FullBucketsIndices {} /// Iterator which consumes a table and returns elements. pub struct RawIntoIter { iter: RawIter, allocation: Option<(NonNull, Layout, A)>, marker: PhantomData, } impl RawIntoIter { #[cfg_attr(feature = "inline-more", inline)] pub fn iter(&self) -> RawIter { self.iter.clone() } } unsafe impl Send for RawIntoIter where T: Send, A: Send, { } unsafe impl Sync for RawIntoIter where T: Sync, A: Sync, { } #[cfg(feature = "nightly")] unsafe impl<#[may_dangle] T, A: Allocator> Drop for RawIntoIter { #[cfg_attr(feature = "inline-more", inline)] fn drop(&mut self) { unsafe { // Drop all remaining elements self.iter.drop_elements(); // Free the table if let Some((ptr, layout, ref alloc)) = self.allocation { alloc.deallocate(ptr, layout); } } } } #[cfg(not(feature = "nightly"))] impl Drop for RawIntoIter { #[cfg_attr(feature = "inline-more", inline)] fn drop(&mut self) { unsafe { // Drop all remaining elements self.iter.drop_elements(); // Free the table if let Some((ptr, layout, ref alloc)) = self.allocation { alloc.deallocate(ptr, layout); } } } } impl Iterator for RawIntoIter { type Item = T; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option { unsafe { Some(self.iter.next()?.read()) } } #[inline] fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } } impl ExactSizeIterator for RawIntoIter {} impl FusedIterator for RawIntoIter {} /// Iterator which consumes elements without freeing the table storage. pub struct RawDrain<'a, T, A: Allocator = Global> { iter: RawIter, // The table is moved into the iterator for the duration of the drain. This // ensures that an empty table is left if the drain iterator is leaked // without dropping. table: RawTableInner, orig_table: NonNull, // We don't use a &'a mut RawTable because we want RawDrain to be // covariant over T. marker: PhantomData<&'a RawTable>, } impl RawDrain<'_, T, A> { #[cfg_attr(feature = "inline-more", inline)] pub fn iter(&self) -> RawIter { self.iter.clone() } } unsafe impl Send for RawDrain<'_, T, A> where T: Send, A: Send, { } unsafe impl Sync for RawDrain<'_, T, A> where T: Sync, A: Sync, { } impl Drop for RawDrain<'_, T, A> { #[cfg_attr(feature = "inline-more", inline)] fn drop(&mut self) { unsafe { // Drop all remaining elements. Note that this may panic. self.iter.drop_elements(); // Reset the contents of the table now that all elements have been // dropped. self.table.clear_no_drop(); // Move the now empty table back to its original location. self.orig_table .as_ptr() .copy_from_nonoverlapping(&self.table, 1); } } } impl Iterator for RawDrain<'_, T, A> { type Item = T; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option { unsafe { let item = self.iter.next()?; Some(item.read()) } } #[inline] fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } } impl ExactSizeIterator for RawDrain<'_, T, A> {} impl FusedIterator for RawDrain<'_, T, A> {} /// Iterator over occupied buckets that could match a given hash. /// /// `RawTable` only stores 7 bits of the hash value, so this iterator may return /// items that have a hash value different than the one provided. You should /// always validate the returned values before using them. /// /// For maximum flexibility this iterator is not bound by a lifetime, but you /// must observe several rules when using it: /// - You must not free the hash table while iterating (including via growing/shrinking). /// - It is fine to erase a bucket that has been yielded by the iterator. /// - Erasing a bucket that has not yet been yielded by the iterator may still /// result in the iterator yielding that bucket. /// - It is unspecified whether an element inserted after the iterator was /// created will be yielded by that iterator. /// - The order in which the iterator yields buckets is unspecified and may /// change in the future. pub struct RawIterHash { inner: RawIterHashInner, _marker: PhantomData, } struct RawIterHashInner { // See `RawTableInner`'s corresponding fields for details. // We can't store a `*const RawTableInner` as it would get // invalidated by the user calling `&mut` methods on `RawTable`. bucket_mask: usize, ctrl: NonNull, // The top 7 bits of the hash. h2_hash: u8, // The sequence of groups to probe in the search. probe_seq: ProbeSeq, group: Group, // The elements within the group with a matching h2-hash. bitmask: BitMaskIter, } impl RawIterHash { #[cfg_attr(feature = "inline-more", inline)] #[cfg(feature = "raw")] unsafe fn new(table: &RawTable, hash: u64) -> Self { RawIterHash { inner: RawIterHashInner::new(&table.table, hash), _marker: PhantomData, } } } impl RawIterHashInner { #[cfg_attr(feature = "inline-more", inline)] #[cfg(feature = "raw")] unsafe fn new(table: &RawTableInner, hash: u64) -> Self { let h2_hash = h2(hash); let probe_seq = table.probe_seq(hash); let group = Group::load(table.ctrl(probe_seq.pos)); let bitmask = group.match_byte(h2_hash).into_iter(); RawIterHashInner { bucket_mask: table.bucket_mask, ctrl: table.ctrl, h2_hash, probe_seq, group, bitmask, } } } impl Iterator for RawIterHash { type Item = Bucket; fn next(&mut self) -> Option> { unsafe { match self.inner.next() { Some(index) => { // Can't use `RawTable::bucket` here as we don't have // an actual `RawTable` reference to use. debug_assert!(index <= self.inner.bucket_mask); let bucket = Bucket::from_base_index(self.inner.ctrl.cast(), index); Some(bucket) } None => None, } } } } impl Iterator for RawIterHashInner { type Item = usize; fn next(&mut self) -> Option { unsafe { loop { if let Some(bit) = self.bitmask.next() { let index = (self.probe_seq.pos + bit) & self.bucket_mask; return Some(index); } if likely(self.group.match_empty().any_bit_set()) { return None; } self.probe_seq.move_next(self.bucket_mask); // Can't use `RawTableInner::ctrl` here as we don't have // an actual `RawTableInner` reference to use. let index = self.probe_seq.pos; debug_assert!(index < self.bucket_mask + 1 + Group::WIDTH); let group_ctrl = self.ctrl.as_ptr().add(index); self.group = Group::load(group_ctrl); self.bitmask = self.group.match_byte(self.h2_hash).into_iter(); } } } } pub(crate) struct RawExtractIf<'a, T, A: Allocator> { pub iter: RawIter, pub table: &'a mut RawTable, } impl RawExtractIf<'_, T, A> { #[cfg_attr(feature = "inline-more", inline)] pub(crate) fn next(&mut self, mut f: F) -> Option where F: FnMut(&mut T) -> bool, { unsafe { for item in &mut self.iter { if f(item.as_mut()) { return Some(self.table.remove(item).0); } } } None } } #[cfg(test)] mod test_map { use super::*; fn rehash_in_place(table: &mut RawTable, hasher: impl Fn(&T) -> u64) { unsafe { table.table.rehash_in_place( &|table, index| hasher(table.bucket::(index).as_ref()), mem::size_of::(), if mem::needs_drop::() { Some(mem::transmute(ptr::drop_in_place:: as unsafe fn(*mut T))) } else { None }, ); } } #[test] fn rehash() { let mut table = RawTable::new(); let hasher = |i: &u64| *i; for i in 0..100 { table.insert(i, i, hasher); } for i in 0..100 { unsafe { assert_eq!(table.find(i, |x| *x == i).map(|b| b.read()), Some(i)); } assert!(table.find(i + 100, |x| *x == i + 100).is_none()); } rehash_in_place(&mut table, hasher); for i in 0..100 { unsafe { assert_eq!(table.find(i, |x| *x == i).map(|b| b.read()), Some(i)); } assert!(table.find(i + 100, |x| *x == i + 100).is_none()); } } /// CHECKING THAT WE ARE NOT TRYING TO READ THE MEMORY OF /// AN UNINITIALIZED TABLE DURING THE DROP #[test] fn test_drop_uninitialized() { use ::alloc::vec::Vec; let table = unsafe { // SAFETY: The `buckets` is power of two and we're not // trying to actually use the returned RawTable. RawTable::<(u64, Vec)>::new_uninitialized(Global, 8, Fallibility::Infallible) .unwrap() }; drop(table); } /// CHECKING THAT WE DON'T TRY TO DROP DATA IF THE `ITEMS` /// ARE ZERO, EVEN IF WE HAVE `FULL` CONTROL BYTES. #[test] fn test_drop_zero_items() { use ::alloc::vec::Vec; unsafe { // SAFETY: The `buckets` is power of two and we're not // trying to actually use the returned RawTable. let table = RawTable::<(u64, Vec)>::new_uninitialized(Global, 8, Fallibility::Infallible) .unwrap(); // WE SIMULATE, AS IT WERE, A FULL TABLE. // SAFETY: We checked that the table is allocated and therefore the table already has // `self.bucket_mask + 1 + Group::WIDTH` number of control bytes (see TableLayout::calculate_layout_for) // so writing `table.table.num_ctrl_bytes() == bucket_mask + 1 + Group::WIDTH` bytes is safe. table .table .ctrl(0) .write_bytes(EMPTY, table.table.num_ctrl_bytes()); // SAFETY: table.capacity() is guaranteed to be smaller than table.buckets() table.table.ctrl(0).write_bytes(0, table.capacity()); // Fix up the trailing control bytes. See the comments in set_ctrl // for the handling of tables smaller than the group width. if table.buckets() < Group::WIDTH { // SAFETY: We have `self.bucket_mask + 1 + Group::WIDTH` number of control bytes, // so copying `self.buckets() == self.bucket_mask + 1` bytes with offset equal to // `Group::WIDTH` is safe table .table .ctrl(0) .copy_to(table.table.ctrl(Group::WIDTH), table.table.buckets()); } else { // SAFETY: We have `self.bucket_mask + 1 + Group::WIDTH` number of // control bytes,so copying `Group::WIDTH` bytes with offset equal // to `self.buckets() == self.bucket_mask + 1` is safe table .table .ctrl(0) .copy_to(table.table.ctrl(table.table.buckets()), Group::WIDTH); } drop(table); } } /// CHECKING THAT WE DON'T TRY TO DROP DATA IF THE `ITEMS` /// ARE ZERO, EVEN IF WE HAVE `FULL` CONTROL BYTES. #[test] fn test_catch_panic_clone_from() { use ::alloc::sync::Arc; use ::alloc::vec::Vec; use allocator_api2::alloc::{AllocError, Allocator, Global}; use core::sync::atomic::{AtomicI8, Ordering}; use std::thread; struct MyAllocInner { drop_count: Arc, } #[derive(Clone)] struct MyAlloc { _inner: Arc, } impl Drop for MyAllocInner { fn drop(&mut self) { println!("MyAlloc freed."); self.drop_count.fetch_sub(1, Ordering::SeqCst); } } unsafe impl Allocator for MyAlloc { fn allocate(&self, layout: Layout) -> std::result::Result, AllocError> { let g = Global; g.allocate(layout) } unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { let g = Global; g.deallocate(ptr, layout) } } const DISARMED: bool = false; const ARMED: bool = true; struct CheckedCloneDrop { panic_in_clone: bool, dropped: bool, need_drop: Vec, } impl Clone for CheckedCloneDrop { fn clone(&self) -> Self { if self.panic_in_clone { panic!("panic in clone") } Self { panic_in_clone: self.panic_in_clone, dropped: self.dropped, need_drop: self.need_drop.clone(), } } } impl Drop for CheckedCloneDrop { fn drop(&mut self) { if self.dropped { panic!("double drop"); } self.dropped = true; } } let dropped: Arc = Arc::new(AtomicI8::new(2)); let mut table = RawTable::new_in(MyAlloc { _inner: Arc::new(MyAllocInner { drop_count: dropped.clone(), }), }); for (idx, panic_in_clone) in core::iter::repeat(DISARMED).take(7).enumerate() { let idx = idx as u64; table.insert( idx, ( idx, CheckedCloneDrop { panic_in_clone, dropped: false, need_drop: vec![idx], }, ), |(k, _)| *k, ); } assert_eq!(table.len(), 7); thread::scope(|s| { let result = s.spawn(|| { let armed_flags = [ DISARMED, DISARMED, ARMED, DISARMED, DISARMED, DISARMED, DISARMED, ]; let mut scope_table = RawTable::new_in(MyAlloc { _inner: Arc::new(MyAllocInner { drop_count: dropped.clone(), }), }); for (idx, &panic_in_clone) in armed_flags.iter().enumerate() { let idx = idx as u64; scope_table.insert( idx, ( idx, CheckedCloneDrop { panic_in_clone, dropped: false, need_drop: vec![idx + 100], }, ), |(k, _)| *k, ); } table.clone_from(&scope_table); }); assert!(result.join().is_err()); }); // Let's check that all iterators work fine and do not return elements // (especially `RawIterRange`, which does not depend on the number of // elements in the table, but looks directly at the control bytes) // // SAFETY: We know for sure that `RawTable` will outlive // the returned `RawIter / RawIterRange` iterator. assert_eq!(table.len(), 0); assert_eq!(unsafe { table.iter().count() }, 0); assert_eq!(unsafe { table.iter().iter.count() }, 0); for idx in 0..table.buckets() { let idx = idx as u64; assert!( table.find(idx, |(k, _)| *k == idx).is_none(), "Index: {idx}" ); } // All allocator clones should already be dropped. assert_eq!(dropped.load(Ordering::SeqCst), 1); } } hashbrown-0.14.5/src/raw/neon.rs000064400000000000000000000103571046102023000146010ustar 00000000000000use super::bitmask::BitMask; use super::EMPTY; use core::arch::aarch64 as neon; use core::mem; use core::num::NonZeroU64; pub(crate) type BitMaskWord = u64; pub(crate) type NonZeroBitMaskWord = NonZeroU64; pub(crate) const BITMASK_STRIDE: usize = 8; pub(crate) const BITMASK_MASK: BitMaskWord = !0; pub(crate) const BITMASK_ITER_MASK: BitMaskWord = 0x8080_8080_8080_8080; /// Abstraction over a group of control bytes which can be scanned in /// parallel. /// /// This implementation uses a 64-bit NEON value. #[derive(Copy, Clone)] pub(crate) struct Group(neon::uint8x8_t); #[allow(clippy::use_self)] impl Group { /// Number of bytes in the group. pub(crate) const WIDTH: usize = mem::size_of::(); /// Returns a full group of empty bytes, suitable for use as the initial /// value for an empty hash table. /// /// This is guaranteed to be aligned to the group size. #[inline] pub(crate) const fn static_empty() -> &'static [u8; Group::WIDTH] { #[repr(C)] struct AlignedBytes { _align: [Group; 0], bytes: [u8; Group::WIDTH], } const ALIGNED_BYTES: AlignedBytes = AlignedBytes { _align: [], bytes: [EMPTY; Group::WIDTH], }; &ALIGNED_BYTES.bytes } /// Loads a group of bytes starting at the given address. #[inline] #[allow(clippy::cast_ptr_alignment)] // unaligned load pub(crate) unsafe fn load(ptr: *const u8) -> Self { Group(neon::vld1_u8(ptr)) } /// Loads a group of bytes starting at the given address, which must be /// aligned to `mem::align_of::()`. #[inline] #[allow(clippy::cast_ptr_alignment)] pub(crate) unsafe fn load_aligned(ptr: *const u8) -> Self { // FIXME: use align_offset once it stabilizes debug_assert_eq!(ptr as usize & (mem::align_of::() - 1), 0); Group(neon::vld1_u8(ptr)) } /// Stores the group of bytes to the given address, which must be /// aligned to `mem::align_of::()`. #[inline] #[allow(clippy::cast_ptr_alignment)] pub(crate) unsafe fn store_aligned(self, ptr: *mut u8) { // FIXME: use align_offset once it stabilizes debug_assert_eq!(ptr as usize & (mem::align_of::() - 1), 0); neon::vst1_u8(ptr, self.0); } /// Returns a `BitMask` indicating all bytes in the group which *may* /// have the given value. #[inline] pub(crate) fn match_byte(self, byte: u8) -> BitMask { unsafe { let cmp = neon::vceq_u8(self.0, neon::vdup_n_u8(byte)); BitMask(neon::vget_lane_u64(neon::vreinterpret_u64_u8(cmp), 0)) } } /// Returns a `BitMask` indicating all bytes in the group which are /// `EMPTY`. #[inline] pub(crate) fn match_empty(self) -> BitMask { self.match_byte(EMPTY) } /// Returns a `BitMask` indicating all bytes in the group which are /// `EMPTY` or `DELETED`. #[inline] pub(crate) fn match_empty_or_deleted(self) -> BitMask { unsafe { let cmp = neon::vcltz_s8(neon::vreinterpret_s8_u8(self.0)); BitMask(neon::vget_lane_u64(neon::vreinterpret_u64_u8(cmp), 0)) } } /// Returns a `BitMask` indicating all bytes in the group which are full. #[inline] pub(crate) fn match_full(self) -> BitMask { unsafe { let cmp = neon::vcgez_s8(neon::vreinterpret_s8_u8(self.0)); BitMask(neon::vget_lane_u64(neon::vreinterpret_u64_u8(cmp), 0)) } } /// Performs the following transformation on all bytes in the group: /// - `EMPTY => EMPTY` /// - `DELETED => EMPTY` /// - `FULL => DELETED` #[inline] pub(crate) fn convert_special_to_empty_and_full_to_deleted(self) -> Self { // Map high_bit = 1 (EMPTY or DELETED) to 1111_1111 // and high_bit = 0 (FULL) to 1000_0000 // // Here's this logic expanded to concrete values: // let special = 0 > byte = 1111_1111 (true) or 0000_0000 (false) // 1111_1111 | 1000_0000 = 1111_1111 // 0000_0000 | 1000_0000 = 1000_0000 unsafe { let special = neon::vcltz_s8(neon::vreinterpret_s8_u8(self.0)); Group(neon::vorr_u8(special, neon::vdup_n_u8(0x80))) } } } hashbrown-0.14.5/src/raw/sse2.rs000064400000000000000000000120661046102023000145150ustar 00000000000000use super::bitmask::BitMask; use super::EMPTY; use core::mem; use core::num::NonZeroU16; #[cfg(target_arch = "x86")] use core::arch::x86; #[cfg(target_arch = "x86_64")] use core::arch::x86_64 as x86; pub(crate) type BitMaskWord = u16; pub(crate) type NonZeroBitMaskWord = NonZeroU16; pub(crate) const BITMASK_STRIDE: usize = 1; pub(crate) const BITMASK_MASK: BitMaskWord = 0xffff; pub(crate) const BITMASK_ITER_MASK: BitMaskWord = !0; /// Abstraction over a group of control bytes which can be scanned in /// parallel. /// /// This implementation uses a 128-bit SSE value. #[derive(Copy, Clone)] pub(crate) struct Group(x86::__m128i); // FIXME: https://github.com/rust-lang/rust-clippy/issues/3859 #[allow(clippy::use_self)] impl Group { /// Number of bytes in the group. pub(crate) const WIDTH: usize = mem::size_of::(); /// Returns a full group of empty bytes, suitable for use as the initial /// value for an empty hash table. /// /// This is guaranteed to be aligned to the group size. #[inline] #[allow(clippy::items_after_statements)] pub(crate) const fn static_empty() -> &'static [u8; Group::WIDTH] { #[repr(C)] struct AlignedBytes { _align: [Group; 0], bytes: [u8; Group::WIDTH], } const ALIGNED_BYTES: AlignedBytes = AlignedBytes { _align: [], bytes: [EMPTY; Group::WIDTH], }; &ALIGNED_BYTES.bytes } /// Loads a group of bytes starting at the given address. #[inline] #[allow(clippy::cast_ptr_alignment)] // unaligned load pub(crate) unsafe fn load(ptr: *const u8) -> Self { Group(x86::_mm_loadu_si128(ptr.cast())) } /// Loads a group of bytes starting at the given address, which must be /// aligned to `mem::align_of::()`. #[inline] #[allow(clippy::cast_ptr_alignment)] pub(crate) unsafe fn load_aligned(ptr: *const u8) -> Self { // FIXME: use align_offset once it stabilizes debug_assert_eq!(ptr as usize & (mem::align_of::() - 1), 0); Group(x86::_mm_load_si128(ptr.cast())) } /// Stores the group of bytes to the given address, which must be /// aligned to `mem::align_of::()`. #[inline] #[allow(clippy::cast_ptr_alignment)] pub(crate) unsafe fn store_aligned(self, ptr: *mut u8) { // FIXME: use align_offset once it stabilizes debug_assert_eq!(ptr as usize & (mem::align_of::() - 1), 0); x86::_mm_store_si128(ptr.cast(), self.0); } /// Returns a `BitMask` indicating all bytes in the group which have /// the given value. #[inline] pub(crate) fn match_byte(self, byte: u8) -> BitMask { #[allow( clippy::cast_possible_wrap, // byte: u8 as i8 // byte: i32 as u16 // note: _mm_movemask_epi8 returns a 16-bit mask in a i32, the // upper 16-bits of the i32 are zeroed: clippy::cast_sign_loss, clippy::cast_possible_truncation )] unsafe { let cmp = x86::_mm_cmpeq_epi8(self.0, x86::_mm_set1_epi8(byte as i8)); BitMask(x86::_mm_movemask_epi8(cmp) as u16) } } /// Returns a `BitMask` indicating all bytes in the group which are /// `EMPTY`. #[inline] pub(crate) fn match_empty(self) -> BitMask { self.match_byte(EMPTY) } /// Returns a `BitMask` indicating all bytes in the group which are /// `EMPTY` or `DELETED`. #[inline] pub(crate) fn match_empty_or_deleted(self) -> BitMask { #[allow( // byte: i32 as u16 // note: _mm_movemask_epi8 returns a 16-bit mask in a i32, the // upper 16-bits of the i32 are zeroed: clippy::cast_sign_loss, clippy::cast_possible_truncation )] unsafe { // A byte is EMPTY or DELETED iff the high bit is set BitMask(x86::_mm_movemask_epi8(self.0) as u16) } } /// Returns a `BitMask` indicating all bytes in the group which are full. #[inline] pub(crate) fn match_full(&self) -> BitMask { self.match_empty_or_deleted().invert() } /// Performs the following transformation on all bytes in the group: /// - `EMPTY => EMPTY` /// - `DELETED => EMPTY` /// - `FULL => DELETED` #[inline] pub(crate) fn convert_special_to_empty_and_full_to_deleted(self) -> Self { // Map high_bit = 1 (EMPTY or DELETED) to 1111_1111 // and high_bit = 0 (FULL) to 1000_0000 // // Here's this logic expanded to concrete values: // let special = 0 > byte = 1111_1111 (true) or 0000_0000 (false) // 1111_1111 | 1000_0000 = 1111_1111 // 0000_0000 | 1000_0000 = 1000_0000 #[allow( clippy::cast_possible_wrap, // byte: 0x80_u8 as i8 )] unsafe { let zero = x86::_mm_setzero_si128(); let special = x86::_mm_cmpgt_epi8(zero, self.0); Group(x86::_mm_or_si128( special, x86::_mm_set1_epi8(0x80_u8 as i8), )) } } } hashbrown-0.14.5/src/rustc_entry.rs000064400000000000000000000442011046102023000154250ustar 00000000000000use self::RustcEntry::*; use crate::map::{make_hash, Drain, HashMap, IntoIter, Iter, IterMut}; use crate::raw::{Allocator, Bucket, Global, RawTable}; use core::fmt::{self, Debug}; use core::hash::{BuildHasher, Hash}; use core::mem; impl HashMap where K: Eq + Hash, S: BuildHasher, A: Allocator, { /// Gets the given key's corresponding entry in the map for in-place manipulation. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut letters = HashMap::new(); /// /// for ch in "a short treatise on fungi".chars() { /// let counter = letters.rustc_entry(ch).or_insert(0); /// *counter += 1; /// } /// /// assert_eq!(letters[&'s'], 2); /// assert_eq!(letters[&'t'], 3); /// assert_eq!(letters[&'u'], 1); /// assert_eq!(letters.get(&'y'), None); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn rustc_entry(&mut self, key: K) -> RustcEntry<'_, K, V, A> { let hash = make_hash(&self.hash_builder, &key); if let Some(elem) = self.table.find(hash, |q| q.0.eq(&key)) { RustcEntry::Occupied(RustcOccupiedEntry { key: Some(key), elem, table: &mut self.table, }) } else { // Ideally we would put this in VacantEntry::insert, but Entry is not // generic over the BuildHasher and adding a generic parameter would be // a breaking change. self.reserve(1); RustcEntry::Vacant(RustcVacantEntry { hash, key, table: &mut self.table, }) } } } /// A view into a single entry in a map, which may either be vacant or occupied. /// /// This `enum` is constructed from the [`rustc_entry`] method on [`HashMap`]. /// /// [`HashMap`]: struct.HashMap.html /// [`rustc_entry`]: struct.HashMap.html#method.rustc_entry pub enum RustcEntry<'a, K, V, A = Global> where A: Allocator, { /// An occupied entry. Occupied(RustcOccupiedEntry<'a, K, V, A>), /// A vacant entry. Vacant(RustcVacantEntry<'a, K, V, A>), } impl Debug for RustcEntry<'_, K, V, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match *self { Vacant(ref v) => f.debug_tuple("Entry").field(v).finish(), Occupied(ref o) => f.debug_tuple("Entry").field(o).finish(), } } } /// A view into an occupied entry in a `HashMap`. /// It is part of the [`RustcEntry`] enum. /// /// [`RustcEntry`]: enum.RustcEntry.html pub struct RustcOccupiedEntry<'a, K, V, A = Global> where A: Allocator, { key: Option, elem: Bucket<(K, V)>, table: &'a mut RawTable<(K, V), A>, } unsafe impl Send for RustcOccupiedEntry<'_, K, V, A> where K: Send, V: Send, A: Allocator + Send, { } unsafe impl Sync for RustcOccupiedEntry<'_, K, V, A> where K: Sync, V: Sync, A: Allocator + Sync, { } impl Debug for RustcOccupiedEntry<'_, K, V, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("OccupiedEntry") .field("key", self.key()) .field("value", self.get()) .finish() } } /// A view into a vacant entry in a `HashMap`. /// It is part of the [`RustcEntry`] enum. /// /// [`RustcEntry`]: enum.RustcEntry.html pub struct RustcVacantEntry<'a, K, V, A = Global> where A: Allocator, { hash: u64, key: K, table: &'a mut RawTable<(K, V), A>, } impl Debug for RustcVacantEntry<'_, K, V, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_tuple("VacantEntry").field(self.key()).finish() } } impl<'a, K, V, A: Allocator> RustcEntry<'a, K, V, A> { /// Sets the value of the entry, and returns a RustcOccupiedEntry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// let entry = map.rustc_entry("horseyland").insert(37); /// /// assert_eq!(entry.key(), &"horseyland"); /// ``` pub fn insert(self, value: V) -> RustcOccupiedEntry<'a, K, V, A> { match self { Vacant(entry) => entry.insert_entry(value), Occupied(mut entry) => { entry.insert(value); entry } } } /// Ensures a value is in the entry by inserting the default if empty, and returns /// a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// map.rustc_entry("poneyland").or_insert(3); /// assert_eq!(map["poneyland"], 3); /// /// *map.rustc_entry("poneyland").or_insert(10) *= 2; /// assert_eq!(map["poneyland"], 6); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert(self, default: V) -> &'a mut V where K: Hash, { match self { Occupied(entry) => entry.into_mut(), Vacant(entry) => entry.insert(default), } } /// Ensures a value is in the entry by inserting the result of the default function if empty, /// and returns a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, String> = HashMap::new(); /// let s = "hoho".to_string(); /// /// map.rustc_entry("poneyland").or_insert_with(|| s); /// /// assert_eq!(map["poneyland"], "hoho".to_string()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert_with V>(self, default: F) -> &'a mut V where K: Hash, { match self { Occupied(entry) => entry.into_mut(), Vacant(entry) => entry.insert(default()), } } /// Returns a reference to this entry's key. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// assert_eq!(map.rustc_entry("poneyland").key(), &"poneyland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &K { match *self { Occupied(ref entry) => entry.key(), Vacant(ref entry) => entry.key(), } } /// Provides in-place mutable access to an occupied entry before any /// potential inserts into the map. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// map.rustc_entry("poneyland") /// .and_modify(|e| { *e += 1 }) /// .or_insert(42); /// assert_eq!(map["poneyland"], 42); /// /// map.rustc_entry("poneyland") /// .and_modify(|e| { *e += 1 }) /// .or_insert(42); /// assert_eq!(map["poneyland"], 43); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn and_modify(self, f: F) -> Self where F: FnOnce(&mut V), { match self { Occupied(mut entry) => { f(entry.get_mut()); Occupied(entry) } Vacant(entry) => Vacant(entry), } } } impl<'a, K, V: Default, A: Allocator> RustcEntry<'a, K, V, A> { /// Ensures a value is in the entry by inserting the default value if empty, /// and returns a mutable reference to the value in the entry. /// /// # Examples /// /// ``` /// # fn main() { /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, Option> = HashMap::new(); /// map.rustc_entry("poneyland").or_default(); /// /// assert_eq!(map["poneyland"], None); /// # } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_default(self) -> &'a mut V where K: Hash, { match self { Occupied(entry) => entry.into_mut(), Vacant(entry) => entry.insert(Default::default()), } } } impl<'a, K, V, A: Allocator> RustcOccupiedEntry<'a, K, V, A> { /// Gets a reference to the key in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.rustc_entry("poneyland").or_insert(12); /// assert_eq!(map.rustc_entry("poneyland").key(), &"poneyland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &K { unsafe { &self.elem.as_ref().0 } } /// Take the ownership of the key and value from the map. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RustcEntry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.rustc_entry("poneyland").or_insert(12); /// /// if let RustcEntry::Occupied(o) = map.rustc_entry("poneyland") { /// // We delete the entry from the map. /// o.remove_entry(); /// } /// /// assert_eq!(map.contains_key("poneyland"), false); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove_entry(self) -> (K, V) { unsafe { self.table.remove(self.elem).0 } } /// Gets a reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RustcEntry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.rustc_entry("poneyland").or_insert(12); /// /// if let RustcEntry::Occupied(o) = map.rustc_entry("poneyland") { /// assert_eq!(o.get(), &12); /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get(&self) -> &V { unsafe { &self.elem.as_ref().1 } } /// Gets a mutable reference to the value in the entry. /// /// If you need a reference to the `RustcOccupiedEntry` which may outlive the /// destruction of the `RustcEntry` value, see [`into_mut`]. /// /// [`into_mut`]: #method.into_mut /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RustcEntry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.rustc_entry("poneyland").or_insert(12); /// /// assert_eq!(map["poneyland"], 12); /// if let RustcEntry::Occupied(mut o) = map.rustc_entry("poneyland") { /// *o.get_mut() += 10; /// assert_eq!(*o.get(), 22); /// /// // We can use the same RustcEntry multiple times. /// *o.get_mut() += 2; /// } /// /// assert_eq!(map["poneyland"], 24); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get_mut(&mut self) -> &mut V { unsafe { &mut self.elem.as_mut().1 } } /// Converts the RustcOccupiedEntry into a mutable reference to the value in the entry /// with a lifetime bound to the map itself. /// /// If you need multiple references to the `RustcOccupiedEntry`, see [`get_mut`]. /// /// [`get_mut`]: #method.get_mut /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RustcEntry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.rustc_entry("poneyland").or_insert(12); /// /// assert_eq!(map["poneyland"], 12); /// if let RustcEntry::Occupied(o) = map.rustc_entry("poneyland") { /// *o.into_mut() += 10; /// } /// /// assert_eq!(map["poneyland"], 22); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_mut(self) -> &'a mut V { unsafe { &mut self.elem.as_mut().1 } } /// Sets the value of the entry, and returns the entry's old value. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RustcEntry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.rustc_entry("poneyland").or_insert(12); /// /// if let RustcEntry::Occupied(mut o) = map.rustc_entry("poneyland") { /// assert_eq!(o.insert(15), 12); /// } /// /// assert_eq!(map["poneyland"], 15); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(&mut self, value: V) -> V { mem::replace(self.get_mut(), value) } /// Takes the value out of the entry, and returns it. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RustcEntry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// map.rustc_entry("poneyland").or_insert(12); /// /// if let RustcEntry::Occupied(o) = map.rustc_entry("poneyland") { /// assert_eq!(o.remove(), 12); /// } /// /// assert_eq!(map.contains_key("poneyland"), false); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove(self) -> V { self.remove_entry().1 } /// Replaces the entry, returning the old key and value. The new key in the hash map will be /// the key used to create this entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{RustcEntry, HashMap}; /// use std::rc::Rc; /// /// let mut map: HashMap, u32> = HashMap::new(); /// map.insert(Rc::new("Stringthing".to_string()), 15); /// /// let my_key = Rc::new("Stringthing".to_string()); /// /// if let RustcEntry::Occupied(entry) = map.rustc_entry(my_key) { /// // Also replace the key with a handle to our other key. /// let (old_key, old_value): (Rc, u32) = entry.replace_entry(16); /// } /// /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace_entry(self, value: V) -> (K, V) { let entry = unsafe { self.elem.as_mut() }; let old_key = mem::replace(&mut entry.0, self.key.unwrap()); let old_value = mem::replace(&mut entry.1, value); (old_key, old_value) } /// Replaces the key in the hash map with the key used to create this entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_map::{RustcEntry, HashMap}; /// use std::rc::Rc; /// /// let mut map: HashMap, u32> = HashMap::new(); /// let mut known_strings: Vec> = Vec::new(); /// /// // Initialise known strings, run program, etc. /// /// reclaim_memory(&mut map, &known_strings); /// /// fn reclaim_memory(map: &mut HashMap, u32>, known_strings: &[Rc] ) { /// for s in known_strings { /// if let RustcEntry::Occupied(entry) = map.rustc_entry(s.clone()) { /// // Replaces the entry's key with our version of it in `known_strings`. /// entry.replace_key(); /// } /// } /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace_key(self) -> K { let entry = unsafe { self.elem.as_mut() }; mem::replace(&mut entry.0, self.key.unwrap()) } } impl<'a, K, V, A: Allocator> RustcVacantEntry<'a, K, V, A> { /// Gets a reference to the key that would be used when inserting a value /// through the `RustcVacantEntry`. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// assert_eq!(map.rustc_entry("poneyland").key(), &"poneyland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn key(&self) -> &K { &self.key } /// Take ownership of the key. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RustcEntry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// if let RustcEntry::Vacant(v) = map.rustc_entry("poneyland") { /// v.into_key(); /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_key(self) -> K { self.key } /// Sets the value of the entry with the RustcVacantEntry's key, /// and returns a mutable reference to it. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RustcEntry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// if let RustcEntry::Vacant(o) = map.rustc_entry("poneyland") { /// o.insert(37); /// } /// assert_eq!(map["poneyland"], 37); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(self, value: V) -> &'a mut V { unsafe { let bucket = self.table.insert_no_grow(self.hash, (self.key, value)); &mut bucket.as_mut().1 } } /// Sets the value of the entry with the RustcVacantEntry's key, /// and returns a RustcOccupiedEntry. /// /// # Examples /// /// ``` /// use hashbrown::HashMap; /// use hashbrown::hash_map::RustcEntry; /// /// let mut map: HashMap<&str, u32> = HashMap::new(); /// /// if let RustcEntry::Vacant(v) = map.rustc_entry("poneyland") { /// let o = v.insert_entry(37); /// assert_eq!(o.get(), &37); /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert_entry(self, value: V) -> RustcOccupiedEntry<'a, K, V, A> { let bucket = unsafe { self.table.insert_no_grow(self.hash, (self.key, value)) }; RustcOccupiedEntry { key: None, elem: bucket, table: self.table, } } } impl IterMut<'_, K, V> { /// Returns a iterator of references over the remaining items. #[cfg_attr(feature = "inline-more", inline)] pub fn rustc_iter(&self) -> Iter<'_, K, V> { self.iter() } } impl IntoIter { /// Returns a iterator of references over the remaining items. #[cfg_attr(feature = "inline-more", inline)] pub fn rustc_iter(&self) -> Iter<'_, K, V> { self.iter() } } impl Drain<'_, K, V> { /// Returns a iterator of references over the remaining items. #[cfg_attr(feature = "inline-more", inline)] pub fn rustc_iter(&self) -> Iter<'_, K, V> { self.iter() } } hashbrown-0.14.5/src/scopeguard.rs000064400000000000000000000025151046102023000152020ustar 00000000000000// Extracted from the scopeguard crate use core::{ mem::ManuallyDrop, ops::{Deref, DerefMut}, ptr, }; pub struct ScopeGuard where F: FnMut(&mut T), { dropfn: F, value: T, } #[inline] pub fn guard(value: T, dropfn: F) -> ScopeGuard where F: FnMut(&mut T), { ScopeGuard { dropfn, value } } impl ScopeGuard where F: FnMut(&mut T), { #[inline] pub fn into_inner(guard: Self) -> T { // Cannot move out of Drop-implementing types, so // ptr::read the value out of a ManuallyDrop // Don't use mem::forget as that might invalidate value let guard = ManuallyDrop::new(guard); unsafe { let value = ptr::read(&guard.value); // read the closure so that it is dropped let _ = ptr::read(&guard.dropfn); value } } } impl Deref for ScopeGuard where F: FnMut(&mut T), { type Target = T; #[inline] fn deref(&self) -> &T { &self.value } } impl DerefMut for ScopeGuard where F: FnMut(&mut T), { #[inline] fn deref_mut(&mut self) -> &mut T { &mut self.value } } impl Drop for ScopeGuard where F: FnMut(&mut T), { #[inline] fn drop(&mut self) { (self.dropfn)(&mut self.value); } } hashbrown-0.14.5/src/set.rs000064400000000000000000002540271046102023000136500ustar 00000000000000#[cfg(feature = "raw")] use crate::raw::RawTable; use crate::{Equivalent, TryReserveError}; use alloc::borrow::ToOwned; use core::fmt; use core::hash::{BuildHasher, Hash}; use core::iter::{Chain, FusedIterator}; use core::ops::{BitAnd, BitOr, BitXor, Sub}; use super::map::{self, DefaultHashBuilder, HashMap, Keys}; use crate::raw::{Allocator, Global, RawExtractIf}; // Future Optimization (FIXME!) // ============================= // // Iteration over zero sized values is a noop. There is no need // 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 `()`. /// /// As with the [`HashMap`] type, a `HashSet` requires that the elements /// implement the [`Eq`] and [`Hash`] traits. This can frequently be achieved by /// using `#[derive(PartialEq, Eq, Hash)]`. If you implement these yourself, /// it is important that the following property holds: /// /// ```text /// k1 == k2 -> hash(k1) == hash(k2) /// ``` /// /// In other words, if two keys are equal, their hashes must be equal. /// /// /// It is a logic error for an item to be modified in such a way that the /// item's hash, as determined by the [`Hash`] trait, or its equality, as /// determined by the [`Eq`] trait, changes while it is in the set. This is /// normally only possible through [`Cell`], [`RefCell`], global state, I/O, or /// unsafe code. /// /// It is also a logic error for the [`Hash`] implementation of a key to panic. /// This is generally only possible if the trait is implemented manually. If a /// panic does occur then the contents of the `HashSet` may become corrupted and /// some items may be dropped from the table. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// // Type inference lets us omit an explicit type signature (which /// // would be `HashSet` in this example). /// let mut books = HashSet::new(); /// /// // Add some books. /// books.insert("A Dance With Dragons".to_string()); /// books.insert("To Kill a Mockingbird".to_string()); /// books.insert("The Odyssey".to_string()); /// books.insert("The Great Gatsby".to_string()); /// /// // Check for a specific one. /// if !books.contains("The Winds of Winter") { /// println!("We have {} books, but The Winds of Winter ain't one.", /// books.len()); /// } /// /// // Remove a book. /// books.remove("The Odyssey"); /// /// // Iterate over everything. /// for book in &books { /// println!("{}", book); /// } /// ``` /// /// The easiest way to use `HashSet` with a custom type is to derive /// [`Eq`] and [`Hash`]. We must also derive [`PartialEq`]. This will in the /// future be implied by [`Eq`]. /// /// ``` /// use hashbrown::HashSet; /// #[derive(Hash, Eq, PartialEq, Debug)] /// struct Viking { /// name: String, /// power: usize, /// } /// /// let mut vikings = HashSet::new(); /// /// vikings.insert(Viking { name: "Einar".to_string(), power: 9 }); /// vikings.insert(Viking { name: "Einar".to_string(), power: 9 }); /// vikings.insert(Viking { name: "Olaf".to_string(), power: 4 }); /// vikings.insert(Viking { name: "Harald".to_string(), power: 8 }); /// /// // Use derived implementation to print the vikings. /// for x in &vikings { /// println!("{:?}", x); /// } /// ``` /// /// A `HashSet` with fixed list of elements can be initialized from an array: /// /// ``` /// use hashbrown::HashSet; /// /// let viking_names: HashSet<&'static str> = /// [ "Einar", "Olaf", "Harald" ].into_iter().collect(); /// // use the values stored in the set /// ``` /// /// [`Cell`]: https://doc.rust-lang.org/std/cell/struct.Cell.html /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html /// [`HashMap`]: struct.HashMap.html /// [`PartialEq`]: https://doc.rust-lang.org/std/cmp/trait.PartialEq.html /// [`RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.html pub struct HashSet { pub(crate) map: HashMap, } impl Clone for HashSet { fn clone(&self) -> Self { HashSet { map: self.map.clone(), } } fn clone_from(&mut self, source: &Self) { self.map.clone_from(&source.map); } } #[cfg(feature = "ahash")] impl HashSet { /// Creates an empty `HashSet`. /// /// The hash set is initially created with a capacity of 0, so it will not allocate until it /// is first inserted into. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashSet` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashSet`], for example with /// [`with_hasher`](HashSet::with_hasher) method. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let set: HashSet = HashSet::new(); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn new() -> Self { Self { map: HashMap::new(), } } /// Creates an empty `HashSet` with the specified capacity. /// /// The hash set will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash set will not allocate. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashSet` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashSet`], for example with /// [`with_capacity_and_hasher`](HashSet::with_capacity_and_hasher) method. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let set: HashSet = HashSet::with_capacity(10); /// assert!(set.capacity() >= 10); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn with_capacity(capacity: usize) -> Self { Self { map: HashMap::with_capacity(capacity), } } } #[cfg(feature = "ahash")] impl HashSet { /// Creates an empty `HashSet`. /// /// The hash set is initially created with a capacity of 0, so it will not allocate until it /// is first inserted into. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashSet` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashSet`], for example with /// [`with_hasher_in`](HashSet::with_hasher_in) method. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let set: HashSet = HashSet::new(); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn new_in(alloc: A) -> Self { Self { map: HashMap::new_in(alloc), } } /// Creates an empty `HashSet` with the specified capacity. /// /// The hash set will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash set will not allocate. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashSet` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashSet`], for example with /// [`with_capacity_and_hasher_in`](HashSet::with_capacity_and_hasher_in) method. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let set: HashSet = HashSet::with_capacity(10); /// assert!(set.capacity() >= 10); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn with_capacity_in(capacity: usize, alloc: A) -> Self { Self { map: HashMap::with_capacity_in(capacity, alloc), } } } impl HashSet { /// Returns the number of elements the set can hold without reallocating. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let set: HashSet = HashSet::with_capacity(100); /// assert!(set.capacity() >= 100); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn capacity(&self) -> usize { self.map.capacity() } /// An iterator visiting all elements in arbitrary order. /// The iterator element type is `&'a T`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let mut set = HashSet::new(); /// set.insert("a"); /// set.insert("b"); /// /// // Will print in an arbitrary order. /// for x in set.iter() { /// println!("{}", x); /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn iter(&self) -> Iter<'_, T> { Iter { iter: self.map.keys(), } } /// Returns the number of elements in the set. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut v = HashSet::new(); /// assert_eq!(v.len(), 0); /// v.insert(1); /// assert_eq!(v.len(), 1); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn len(&self) -> usize { self.map.len() } /// Returns `true` if the set contains no elements. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut v = HashSet::new(); /// assert!(v.is_empty()); /// v.insert(1); /// assert!(!v.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn is_empty(&self) -> bool { self.map.is_empty() } /// Clears the set, returning all elements in an iterator. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet<_> = [1, 2, 3].into_iter().collect(); /// assert!(!set.is_empty()); /// /// // print 1, 2, 3 in an arbitrary order /// for i in set.drain() { /// println!("{}", i); /// } /// /// assert!(set.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn drain(&mut self) -> Drain<'_, T, A> { Drain { iter: self.map.drain(), } } /// Retains only the elements specified by the predicate. /// /// In other words, remove all elements `e` such that `f(&e)` returns `false`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let xs = [1,2,3,4,5,6]; /// let mut set: HashSet = xs.into_iter().collect(); /// set.retain(|&k| k % 2 == 0); /// assert_eq!(set.len(), 3); /// ``` pub fn retain(&mut self, mut f: F) where F: FnMut(&T) -> bool, { self.map.retain(|k, _| f(k)); } /// Drains elements which are true under the given predicate, /// and returns an iterator over the removed items. /// /// In other words, move all elements `e` such that `f(&e)` returns `true` out /// into another iterator. /// /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating /// or the iteration short-circuits, then the remaining elements will be retained. /// Use [`retain()`] with a negated predicate if you do not need the returned iterator. /// /// [`retain()`]: HashSet::retain /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet = (0..8).collect(); /// let drained: HashSet = set.extract_if(|v| v % 2 == 0).collect(); /// /// let mut evens = drained.into_iter().collect::>(); /// let mut odds = set.into_iter().collect::>(); /// evens.sort(); /// odds.sort(); /// /// assert_eq!(evens, vec![0, 2, 4, 6]); /// assert_eq!(odds, vec![1, 3, 5, 7]); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn extract_if(&mut self, f: F) -> ExtractIf<'_, T, F, A> where F: FnMut(&T) -> bool, { ExtractIf { f, inner: RawExtractIf { iter: unsafe { self.map.table.iter() }, table: &mut self.map.table, }, } } /// Clears the set, removing all values. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut v = HashSet::new(); /// v.insert(1); /// v.clear(); /// assert!(v.is_empty()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn clear(&mut self) { self.map.clear(); } } impl HashSet { /// Creates a new empty hash set which will use the given hasher to hash /// keys. /// /// The hash set is initially created with a capacity of 0, so it will not /// allocate until it is first inserted into. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashSet` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashSet`]. /// /// The `hash_builder` passed should implement the [`BuildHasher`] trait for /// the HashSet to be useful, see its documentation for details. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// [`BuildHasher`]: https://doc.rust-lang.org/std/hash/trait.BuildHasher.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let s = DefaultHashBuilder::default(); /// let mut set = HashSet::with_hasher(s); /// set.insert(2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub const fn with_hasher(hasher: S) -> Self { Self { map: HashMap::with_hasher(hasher), } } /// Creates an empty `HashSet` with the specified capacity, using /// `hasher` to hash the keys. /// /// The hash set will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash set will not allocate. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashSet` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashSet`]. /// /// The `hash_builder` passed should implement the [`BuildHasher`] trait for /// the HashSet to be useful, see its documentation for details. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// [`BuildHasher`]: https://doc.rust-lang.org/std/hash/trait.BuildHasher.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let s = DefaultHashBuilder::default(); /// let mut set = HashSet::with_capacity_and_hasher(10, s); /// set.insert(1); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn with_capacity_and_hasher(capacity: usize, hasher: S) -> Self { Self { map: HashMap::with_capacity_and_hasher(capacity, hasher), } } } impl HashSet where A: Allocator, { /// Returns a reference to the underlying allocator. #[inline] pub fn allocator(&self) -> &A { self.map.allocator() } /// Creates a new empty hash set which will use the given hasher to hash /// keys. /// /// The hash set is initially created with a capacity of 0, so it will not /// allocate until it is first inserted into. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashSet` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashSet`]. /// /// The `hash_builder` passed should implement the [`BuildHasher`] trait for /// the HashSet to be useful, see its documentation for details. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// [`BuildHasher`]: https://doc.rust-lang.org/std/hash/trait.BuildHasher.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let s = DefaultHashBuilder::default(); /// let mut set = HashSet::with_hasher(s); /// set.insert(2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub const fn with_hasher_in(hasher: S, alloc: A) -> Self { Self { map: HashMap::with_hasher_in(hasher, alloc), } } /// Creates an empty `HashSet` with the specified capacity, using /// `hasher` to hash the keys. /// /// The hash set will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash set will not allocate. /// /// # HashDoS resistance /// /// The `hash_builder` normally use a fixed key by default and that does /// not allow the `HashSet` to be protected against attacks such as [`HashDoS`]. /// Users who require HashDoS resistance should explicitly use /// [`ahash::RandomState`] or [`std::collections::hash_map::RandomState`] /// as the hasher when creating a [`HashSet`]. /// /// The `hash_builder` passed should implement the [`BuildHasher`] trait for /// the HashSet to be useful, see its documentation for details. /// /// [`HashDoS`]: https://en.wikipedia.org/wiki/Collision_attack /// [`std::collections::hash_map::RandomState`]: https://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html /// [`BuildHasher`]: https://doc.rust-lang.org/std/hash/trait.BuildHasher.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let s = DefaultHashBuilder::default(); /// let mut set = HashSet::with_capacity_and_hasher(10, s); /// set.insert(1); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn with_capacity_and_hasher_in(capacity: usize, hasher: S, alloc: A) -> Self { Self { map: HashMap::with_capacity_and_hasher_in(capacity, hasher, alloc), } } /// Returns a reference to the set's [`BuildHasher`]. /// /// [`BuildHasher`]: https://doc.rust-lang.org/std/hash/trait.BuildHasher.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// use hashbrown::hash_map::DefaultHashBuilder; /// /// let hasher = DefaultHashBuilder::default(); /// let set: HashSet = HashSet::with_hasher(hasher); /// let hasher: &DefaultHashBuilder = set.hasher(); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn hasher(&self) -> &S { self.map.hasher() } } impl HashSet where T: Eq + Hash, S: BuildHasher, A: Allocator, { /// Reserves capacity for at least `additional` more elements to be inserted /// in the `HashSet`. The collection may reserve more space to avoid /// frequent reallocations. /// /// # Panics /// /// Panics if the new capacity exceeds [`isize::MAX`] bytes and [`abort`] the program /// in case of allocation error. Use [`try_reserve`](HashSet::try_reserve) instead /// if you want to handle memory allocation failure. /// /// [`isize::MAX`]: https://doc.rust-lang.org/std/primitive.isize.html /// [`abort`]: https://doc.rust-lang.org/alloc/alloc/fn.handle_alloc_error.html /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let mut set: HashSet = HashSet::new(); /// set.reserve(10); /// assert!(set.capacity() >= 10); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn reserve(&mut self, additional: usize) { self.map.reserve(additional); } /// Tries to reserve capacity for at least `additional` more elements to be inserted /// in the given `HashSet`. The collection may reserve more space to avoid /// frequent reallocations. /// /// # Errors /// /// If the capacity overflows, or the allocator reports a failure, then an error /// is returned. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let mut set: HashSet = HashSet::new(); /// set.try_reserve(10).expect("why is the test harness OOMing on 10 bytes?"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { self.map.try_reserve(additional) } /// Shrinks the capacity of the set as much as possible. It will drop /// down as much as possible while maintaining the internal rules /// and possibly leaving some space in accordance with the resize policy. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set = HashSet::with_capacity(100); /// set.insert(1); /// set.insert(2); /// assert!(set.capacity() >= 100); /// set.shrink_to_fit(); /// assert!(set.capacity() >= 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn shrink_to_fit(&mut self) { self.map.shrink_to_fit(); } /// Shrinks the capacity of the set with a lower limit. It will drop /// down no lower than the supplied limit while maintaining the internal rules /// and possibly leaving some space in accordance with the resize policy. /// /// Panics if the current capacity is smaller than the supplied /// minimum capacity. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set = HashSet::with_capacity(100); /// set.insert(1); /// set.insert(2); /// assert!(set.capacity() >= 100); /// set.shrink_to(10); /// assert!(set.capacity() >= 10); /// set.shrink_to(0); /// assert!(set.capacity() >= 2); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn shrink_to(&mut self, min_capacity: usize) { self.map.shrink_to(min_capacity); } /// Visits the values representing the difference, /// i.e., the values that are in `self` but not in `other`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let a: HashSet<_> = [1, 2, 3].into_iter().collect(); /// let b: HashSet<_> = [4, 2, 3, 4].into_iter().collect(); /// /// // Can be seen as `a - b`. /// for x in a.difference(&b) { /// println!("{}", x); // Print 1 /// } /// /// let diff: HashSet<_> = a.difference(&b).collect(); /// assert_eq!(diff, [1].iter().collect()); /// /// // Note that difference is not symmetric, /// // and `b - a` means something else: /// let diff: HashSet<_> = b.difference(&a).collect(); /// assert_eq!(diff, [4].iter().collect()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn difference<'a>(&'a self, other: &'a Self) -> Difference<'a, T, S, A> { Difference { iter: self.iter(), other, } } /// Visits the values representing the symmetric difference, /// i.e., the values that are in `self` or in `other` but not in both. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let a: HashSet<_> = [1, 2, 3].into_iter().collect(); /// let b: HashSet<_> = [4, 2, 3, 4].into_iter().collect(); /// /// // Print 1, 4 in arbitrary order. /// for x in a.symmetric_difference(&b) { /// println!("{}", x); /// } /// /// let diff1: HashSet<_> = a.symmetric_difference(&b).collect(); /// let diff2: HashSet<_> = b.symmetric_difference(&a).collect(); /// /// assert_eq!(diff1, diff2); /// assert_eq!(diff1, [1, 4].iter().collect()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn symmetric_difference<'a>(&'a self, other: &'a Self) -> SymmetricDifference<'a, T, S, A> { SymmetricDifference { iter: self.difference(other).chain(other.difference(self)), } } /// Visits the values representing the intersection, /// i.e., the values that are both in `self` and `other`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let a: HashSet<_> = [1, 2, 3].into_iter().collect(); /// let b: HashSet<_> = [4, 2, 3, 4].into_iter().collect(); /// /// // Print 2, 3 in arbitrary order. /// for x in a.intersection(&b) { /// println!("{}", x); /// } /// /// let intersection: HashSet<_> = a.intersection(&b).collect(); /// assert_eq!(intersection, [2, 3].iter().collect()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn intersection<'a>(&'a self, other: &'a Self) -> Intersection<'a, T, S, A> { let (smaller, larger) = if self.len() <= other.len() { (self, other) } else { (other, self) }; Intersection { iter: smaller.iter(), other: larger, } } /// Visits the values representing the union, /// i.e., all the values in `self` or `other`, without duplicates. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let a: HashSet<_> = [1, 2, 3].into_iter().collect(); /// let b: HashSet<_> = [4, 2, 3, 4].into_iter().collect(); /// /// // Print 1, 2, 3, 4 in arbitrary order. /// for x in a.union(&b) { /// println!("{}", x); /// } /// /// let union: HashSet<_> = a.union(&b).collect(); /// assert_eq!(union, [1, 2, 3, 4].iter().collect()); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn union<'a>(&'a self, other: &'a Self) -> Union<'a, T, S, A> { // We'll iterate one set in full, and only the remaining difference from the other. // Use the smaller set for the difference in order to reduce hash lookups. let (smaller, larger) = if self.len() <= other.len() { (self, other) } else { (other, self) }; Union { iter: larger.iter().chain(smaller.difference(larger)), } } /// Returns `true` if the set contains a value. /// /// The value may be any borrowed form of the set's value type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the value type. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let set: HashSet<_> = [1, 2, 3].into_iter().collect(); /// assert_eq!(set.contains(&1), true); /// assert_eq!(set.contains(&4), false); /// ``` /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html #[cfg_attr(feature = "inline-more", inline)] pub fn contains(&self, value: &Q) -> bool where Q: Hash + Equivalent, { self.map.contains_key(value) } /// Returns a reference to the value in the set, if any, that is equal to the given value. /// /// The value may be any borrowed form of the set's value type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the value type. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let set: HashSet<_> = [1, 2, 3].into_iter().collect(); /// assert_eq!(set.get(&2), Some(&2)); /// assert_eq!(set.get(&4), None); /// ``` /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html #[cfg_attr(feature = "inline-more", inline)] pub fn get(&self, value: &Q) -> Option<&T> where Q: Hash + Equivalent, { // Avoid `Option::map` because it bloats LLVM IR. match self.map.get_key_value(value) { Some((k, _)) => Some(k), None => None, } } /// Inserts the given `value` into the set if it is not present, then /// returns a reference to the value in the set. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet<_> = [1, 2, 3].into_iter().collect(); /// assert_eq!(set.len(), 3); /// assert_eq!(set.get_or_insert(2), &2); /// assert_eq!(set.get_or_insert(100), &100); /// assert_eq!(set.len(), 4); // 100 was inserted /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get_or_insert(&mut self, value: T) -> &T { // Although the raw entry gives us `&mut T`, we only return `&T` to be consistent with // `get`. Key mutation is "raw" because you're not supposed to affect `Eq` or `Hash`. self.map .raw_entry_mut() .from_key(&value) .or_insert(value, ()) .0 } /// Inserts an owned copy of the given `value` into the set if it is not /// present, then returns a reference to the value in the set. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet = ["cat", "dog", "horse"] /// .iter().map(|&pet| pet.to_owned()).collect(); /// /// assert_eq!(set.len(), 3); /// for &pet in &["cat", "dog", "fish"] { /// let value = set.get_or_insert_owned(pet); /// assert_eq!(value, pet); /// } /// assert_eq!(set.len(), 4); // a new "fish" was inserted /// ``` #[inline] pub fn get_or_insert_owned(&mut self, value: &Q) -> &T where Q: Hash + Equivalent + ToOwned, { // Although the raw entry gives us `&mut T`, we only return `&T` to be consistent with // `get`. Key mutation is "raw" because you're not supposed to affect `Eq` or `Hash`. self.map .raw_entry_mut() .from_key(value) .or_insert_with(|| (value.to_owned(), ())) .0 } /// Inserts a value computed from `f` into the set if the given `value` is /// not present, then returns a reference to the value in the set. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet = ["cat", "dog", "horse"] /// .iter().map(|&pet| pet.to_owned()).collect(); /// /// assert_eq!(set.len(), 3); /// for &pet in &["cat", "dog", "fish"] { /// let value = set.get_or_insert_with(pet, str::to_owned); /// assert_eq!(value, pet); /// } /// assert_eq!(set.len(), 4); // a new "fish" was inserted /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get_or_insert_with(&mut self, value: &Q, f: F) -> &T where Q: Hash + Equivalent, F: FnOnce(&Q) -> T, { // Although the raw entry gives us `&mut T`, we only return `&T` to be consistent with // `get`. Key mutation is "raw" because you're not supposed to affect `Eq` or `Hash`. self.map .raw_entry_mut() .from_key(value) .or_insert_with(|| (f(value), ())) .0 } /// Gets the given value's corresponding entry in the set for in-place manipulation. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// use hashbrown::hash_set::Entry::*; /// /// let mut singles = HashSet::new(); /// let mut dupes = HashSet::new(); /// /// for ch in "a short treatise on fungi".chars() { /// if let Vacant(dupe_entry) = dupes.entry(ch) { /// // We haven't already seen a duplicate, so /// // check if we've at least seen it once. /// match singles.entry(ch) { /// Vacant(single_entry) => { /// // We found a new character for the first time. /// single_entry.insert() /// } /// Occupied(single_entry) => { /// // We've already seen this once, "move" it to dupes. /// single_entry.remove(); /// dupe_entry.insert(); /// } /// } /// } /// } /// /// assert!(!singles.contains(&'t') && dupes.contains(&'t')); /// assert!(singles.contains(&'u') && !dupes.contains(&'u')); /// assert!(!singles.contains(&'v') && !dupes.contains(&'v')); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn entry(&mut self, value: T) -> Entry<'_, T, S, A> { match self.map.entry(value) { map::Entry::Occupied(entry) => Entry::Occupied(OccupiedEntry { inner: entry }), map::Entry::Vacant(entry) => Entry::Vacant(VacantEntry { inner: entry }), } } /// Returns `true` if `self` has no elements in common with `other`. /// This is equivalent to checking for an empty intersection. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let a: HashSet<_> = [1, 2, 3].into_iter().collect(); /// let mut b = HashSet::new(); /// /// assert_eq!(a.is_disjoint(&b), true); /// b.insert(4); /// assert_eq!(a.is_disjoint(&b), true); /// b.insert(1); /// assert_eq!(a.is_disjoint(&b), false); /// ``` pub fn is_disjoint(&self, other: &Self) -> bool { self.iter().all(|v| !other.contains(v)) } /// Returns `true` if the set is a subset of another, /// i.e., `other` contains at least all the values in `self`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let sup: HashSet<_> = [1, 2, 3].into_iter().collect(); /// let mut set = HashSet::new(); /// /// assert_eq!(set.is_subset(&sup), true); /// set.insert(2); /// assert_eq!(set.is_subset(&sup), true); /// set.insert(4); /// assert_eq!(set.is_subset(&sup), false); /// ``` pub fn is_subset(&self, other: &Self) -> bool { self.len() <= other.len() && self.iter().all(|v| other.contains(v)) } /// Returns `true` if the set is a superset of another, /// i.e., `self` contains at least all the values in `other`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let sub: HashSet<_> = [1, 2].into_iter().collect(); /// let mut set = HashSet::new(); /// /// assert_eq!(set.is_superset(&sub), false); /// /// set.insert(0); /// set.insert(1); /// assert_eq!(set.is_superset(&sub), false); /// /// set.insert(2); /// assert_eq!(set.is_superset(&sub), true); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn is_superset(&self, other: &Self) -> bool { other.is_subset(self) } /// Adds a value to the set. /// /// If the set did not have this value present, `true` is returned. /// /// If the set did have this value present, `false` is returned. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set = HashSet::new(); /// /// assert_eq!(set.insert(2), true); /// assert_eq!(set.insert(2), false); /// assert_eq!(set.len(), 1); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(&mut self, value: T) -> bool { self.map.insert(value, ()).is_none() } /// Insert a value the set without checking if the value already exists in the set. /// /// Returns a reference to the value just inserted. /// /// This operation is safe if a value does not exist in the set. /// /// However, if a value exists in the set already, the behavior is unspecified: /// this operation may panic, loop forever, or any following operation with the set /// may panic, loop forever or return arbitrary result. /// /// That said, this operation (and following operations) are guaranteed to /// not violate memory safety. /// /// This operation is faster than regular insert, because it does not perform /// lookup before insertion. /// /// This operation is useful during initial population of the set. /// For example, when constructing a set from another set, we know /// that values are unique. #[cfg_attr(feature = "inline-more", inline)] pub fn insert_unique_unchecked(&mut self, value: T) -> &T { self.map.insert_unique_unchecked(value, ()).0 } /// Adds a value to the set, replacing the existing value, if any, that is equal to the given /// one. Returns the replaced value. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set = HashSet::new(); /// set.insert(Vec::::new()); /// /// assert_eq!(set.get(&[][..]).unwrap().capacity(), 0); /// set.replace(Vec::with_capacity(10)); /// assert_eq!(set.get(&[][..]).unwrap().capacity(), 10); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace(&mut self, value: T) -> Option { match self.map.entry(value) { map::Entry::Occupied(occupied) => Some(occupied.replace_key()), map::Entry::Vacant(vacant) => { vacant.insert(()); None } } } /// Removes a value from the set. Returns whether the value was /// present in the set. /// /// The value may be any borrowed form of the set's value type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the value type. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set = HashSet::new(); /// /// set.insert(2); /// assert_eq!(set.remove(&2), true); /// assert_eq!(set.remove(&2), false); /// ``` /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html #[cfg_attr(feature = "inline-more", inline)] pub fn remove(&mut self, value: &Q) -> bool where Q: Hash + Equivalent, { self.map.remove(value).is_some() } /// Removes and returns the value in the set, if any, that is equal to the given one. /// /// The value may be any borrowed form of the set's value type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the value type. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet<_> = [1, 2, 3].into_iter().collect(); /// assert_eq!(set.take(&2), Some(2)); /// assert_eq!(set.take(&2), None); /// ``` /// /// [`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html /// [`Hash`]: https://doc.rust-lang.org/std/hash/trait.Hash.html #[cfg_attr(feature = "inline-more", inline)] pub fn take(&mut self, value: &Q) -> Option where Q: Hash + Equivalent, { // Avoid `Option::map` because it bloats LLVM IR. match self.map.remove_entry(value) { Some((k, _)) => Some(k), None => None, } } } impl HashSet { /// Returns a reference to the [`RawTable`] used underneath [`HashSet`]. /// This function is only available if the `raw` feature of the crate is enabled. /// /// # Note /// /// Calling this function is safe, but using the raw hash table API may require /// unsafe functions or blocks. /// /// `RawTable` API gives the lowest level of control under the set that can be useful /// for extending the HashSet's API, but may lead to *[undefined behavior]*. /// /// [`HashSet`]: struct.HashSet.html /// [`RawTable`]: crate::raw::RawTable /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[cfg(feature = "raw")] #[cfg_attr(feature = "inline-more", inline)] pub fn raw_table(&self) -> &RawTable<(T, ()), A> { self.map.raw_table() } /// Returns a mutable reference to the [`RawTable`] used underneath [`HashSet`]. /// This function is only available if the `raw` feature of the crate is enabled. /// /// # Note /// /// Calling this function is safe, but using the raw hash table API may require /// unsafe functions or blocks. /// /// `RawTable` API gives the lowest level of control under the set that can be useful /// for extending the HashSet's API, but may lead to *[undefined behavior]*. /// /// [`HashSet`]: struct.HashSet.html /// [`RawTable`]: crate::raw::RawTable /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html #[cfg(feature = "raw")] #[cfg_attr(feature = "inline-more", inline)] pub fn raw_table_mut(&mut self) -> &mut RawTable<(T, ()), A> { self.map.raw_table_mut() } } impl PartialEq for HashSet where T: Eq + Hash, S: BuildHasher, A: Allocator, { fn eq(&self, other: &Self) -> bool { if self.len() != other.len() { return false; } self.iter().all(|key| other.contains(key)) } } impl Eq for HashSet where T: Eq + Hash, S: BuildHasher, A: Allocator, { } impl fmt::Debug for HashSet where T: fmt::Debug, A: Allocator, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_set().entries(self.iter()).finish() } } impl From> for HashSet where A: Allocator, { fn from(map: HashMap) -> Self { Self { map } } } impl FromIterator for HashSet where T: Eq + Hash, S: BuildHasher + Default, A: Default + Allocator, { #[cfg_attr(feature = "inline-more", inline)] fn from_iter>(iter: I) -> Self { let mut set = Self::with_hasher_in(Default::default(), Default::default()); set.extend(iter); set } } // The default hasher is used to match the std implementation signature #[cfg(feature = "ahash")] impl From<[T; N]> for HashSet where T: Eq + Hash, A: Default + Allocator, { /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let set1 = HashSet::from([1, 2, 3, 4]); /// let set2: HashSet<_> = [1, 2, 3, 4].into(); /// assert_eq!(set1, set2); /// ``` fn from(arr: [T; N]) -> Self { arr.into_iter().collect() } } impl Extend for HashSet where T: Eq + Hash, S: BuildHasher, A: Allocator, { #[cfg_attr(feature = "inline-more", inline)] fn extend>(&mut self, iter: I) { self.map.extend(iter.into_iter().map(|k| (k, ()))); } #[inline] #[cfg(feature = "nightly")] fn extend_one(&mut self, k: T) { self.map.insert(k, ()); } #[inline] #[cfg(feature = "nightly")] fn extend_reserve(&mut self, additional: usize) { Extend::<(T, ())>::extend_reserve(&mut self.map, additional); } } impl<'a, T, S, A> Extend<&'a T> for HashSet where T: 'a + Eq + Hash + Copy, S: BuildHasher, A: Allocator, { #[cfg_attr(feature = "inline-more", inline)] fn extend>(&mut self, iter: I) { self.extend(iter.into_iter().copied()); } #[inline] #[cfg(feature = "nightly")] fn extend_one(&mut self, k: &'a T) { self.map.insert(*k, ()); } #[inline] #[cfg(feature = "nightly")] fn extend_reserve(&mut self, additional: usize) { Extend::<(T, ())>::extend_reserve(&mut self.map, additional); } } impl Default for HashSet where S: Default, A: Default + Allocator, { /// Creates an empty `HashSet` with the `Default` value for the hasher. #[cfg_attr(feature = "inline-more", inline)] fn default() -> Self { Self { map: HashMap::default(), } } } impl BitOr<&HashSet> for &HashSet where T: Eq + Hash + Clone, S: BuildHasher + Default, A: Allocator, { type Output = HashSet; /// Returns the union of `self` and `rhs` as a new `HashSet`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let a: HashSet<_> = vec![1, 2, 3].into_iter().collect(); /// let b: HashSet<_> = vec![3, 4, 5].into_iter().collect(); /// /// let set = &a | &b; /// /// let mut i = 0; /// let expected = [1, 2, 3, 4, 5]; /// for x in &set { /// assert!(expected.contains(x)); /// i += 1; /// } /// assert_eq!(i, expected.len()); /// ``` fn bitor(self, rhs: &HashSet) -> HashSet { self.union(rhs).cloned().collect() } } impl BitAnd<&HashSet> for &HashSet where T: Eq + Hash + Clone, S: BuildHasher + Default, A: Allocator, { type Output = HashSet; /// Returns the intersection of `self` and `rhs` as a new `HashSet`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let a: HashSet<_> = vec![1, 2, 3].into_iter().collect(); /// let b: HashSet<_> = vec![2, 3, 4].into_iter().collect(); /// /// let set = &a & &b; /// /// let mut i = 0; /// let expected = [2, 3]; /// for x in &set { /// assert!(expected.contains(x)); /// i += 1; /// } /// assert_eq!(i, expected.len()); /// ``` fn bitand(self, rhs: &HashSet) -> HashSet { self.intersection(rhs).cloned().collect() } } impl BitXor<&HashSet> for &HashSet where T: Eq + Hash + Clone, S: BuildHasher + Default, { type Output = HashSet; /// Returns the symmetric difference of `self` and `rhs` as a new `HashSet`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let a: HashSet<_> = vec![1, 2, 3].into_iter().collect(); /// let b: HashSet<_> = vec![3, 4, 5].into_iter().collect(); /// /// let set = &a ^ &b; /// /// let mut i = 0; /// let expected = [1, 2, 4, 5]; /// for x in &set { /// assert!(expected.contains(x)); /// i += 1; /// } /// assert_eq!(i, expected.len()); /// ``` fn bitxor(self, rhs: &HashSet) -> HashSet { self.symmetric_difference(rhs).cloned().collect() } } impl Sub<&HashSet> for &HashSet where T: Eq + Hash + Clone, S: BuildHasher + Default, { type Output = HashSet; /// Returns the difference of `self` and `rhs` as a new `HashSet`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let a: HashSet<_> = vec![1, 2, 3].into_iter().collect(); /// let b: HashSet<_> = vec![3, 4, 5].into_iter().collect(); /// /// let set = &a - &b; /// /// let mut i = 0; /// let expected = [1, 2]; /// for x in &set { /// assert!(expected.contains(x)); /// i += 1; /// } /// assert_eq!(i, expected.len()); /// ``` fn sub(self, rhs: &HashSet) -> HashSet { self.difference(rhs).cloned().collect() } } /// An iterator over the items of a `HashSet`. /// /// This `struct` is created by the [`iter`] method on [`HashSet`]. /// See its documentation for more. /// /// [`HashSet`]: struct.HashSet.html /// [`iter`]: struct.HashSet.html#method.iter pub struct Iter<'a, K> { iter: Keys<'a, K, ()>, } /// An owning iterator over the items of a `HashSet`. /// /// This `struct` is created by the [`into_iter`] method on [`HashSet`] /// (provided by the `IntoIterator` trait). See its documentation for more. /// /// [`HashSet`]: struct.HashSet.html /// [`into_iter`]: struct.HashSet.html#method.into_iter pub struct IntoIter { iter: map::IntoIter, } /// A draining iterator over the items of a `HashSet`. /// /// This `struct` is created by the [`drain`] method on [`HashSet`]. /// See its documentation for more. /// /// [`HashSet`]: struct.HashSet.html /// [`drain`]: struct.HashSet.html#method.drain pub struct Drain<'a, K, A: Allocator = Global> { iter: map::Drain<'a, K, (), A>, } /// A draining iterator over entries of a `HashSet` which don't satisfy the predicate `f`. /// /// This `struct` is created by the [`extract_if`] method on [`HashSet`]. See its /// documentation for more. /// /// [`extract_if`]: struct.HashSet.html#method.extract_if /// [`HashSet`]: struct.HashSet.html #[must_use = "Iterators are lazy unless consumed"] pub struct ExtractIf<'a, K, F, A: Allocator = Global> where F: FnMut(&K) -> bool, { f: F, inner: RawExtractIf<'a, (K, ()), A>, } /// A lazy iterator producing elements in the intersection of `HashSet`s. /// /// This `struct` is created by the [`intersection`] method on [`HashSet`]. /// See its documentation for more. /// /// [`HashSet`]: struct.HashSet.html /// [`intersection`]: struct.HashSet.html#method.intersection pub struct Intersection<'a, T, S, A: Allocator = Global> { // iterator of the first set iter: Iter<'a, T>, // the second set other: &'a HashSet, } /// A lazy iterator producing elements in the difference of `HashSet`s. /// /// This `struct` is created by the [`difference`] method on [`HashSet`]. /// See its documentation for more. /// /// [`HashSet`]: struct.HashSet.html /// [`difference`]: struct.HashSet.html#method.difference pub struct Difference<'a, T, S, A: Allocator = Global> { // iterator of the first set iter: Iter<'a, T>, // the second set other: &'a HashSet, } /// A lazy iterator producing elements in the symmetric difference of `HashSet`s. /// /// This `struct` is created by the [`symmetric_difference`] method on /// [`HashSet`]. See its documentation for more. /// /// [`HashSet`]: struct.HashSet.html /// [`symmetric_difference`]: struct.HashSet.html#method.symmetric_difference pub struct SymmetricDifference<'a, T, S, A: Allocator = Global> { iter: Chain, Difference<'a, T, S, A>>, } /// A lazy iterator producing elements in the union of `HashSet`s. /// /// This `struct` is created by the [`union`] method on [`HashSet`]. /// See its documentation for more. /// /// [`HashSet`]: struct.HashSet.html /// [`union`]: struct.HashSet.html#method.union pub struct Union<'a, T, S, A: Allocator = Global> { iter: Chain, Difference<'a, T, S, A>>, } impl<'a, T, S, A: Allocator> IntoIterator for &'a HashSet { type Item = &'a T; type IntoIter = Iter<'a, T>; #[cfg_attr(feature = "inline-more", inline)] fn into_iter(self) -> Iter<'a, T> { self.iter() } } impl IntoIterator for HashSet { type Item = T; type IntoIter = IntoIter; /// Creates a consuming iterator, that is, one that moves each value out /// of the set in arbitrary order. The set cannot be used after calling /// this. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// let mut set = HashSet::new(); /// set.insert("a".to_string()); /// set.insert("b".to_string()); /// /// // Not possible to collect to a Vec with a regular `.iter()`. /// let v: Vec = set.into_iter().collect(); /// /// // Will print in an arbitrary order. /// for x in &v { /// println!("{}", x); /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] fn into_iter(self) -> IntoIter { IntoIter { iter: self.map.into_iter(), } } } impl Clone for Iter<'_, K> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Iter { iter: self.iter.clone(), } } } impl<'a, K> Iterator for Iter<'a, K> { type Item = &'a K; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<&'a K> { self.iter.next() } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.iter.fold(init, f) } } impl<'a, K> ExactSizeIterator for Iter<'a, K> { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.iter.len() } } impl FusedIterator for Iter<'_, K> {} impl fmt::Debug for Iter<'_, K> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.clone()).finish() } } impl Iterator for IntoIter { type Item = K; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option { // Avoid `Option::map` because it bloats LLVM IR. match self.iter.next() { Some((k, _)) => Some(k), None => None, } } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.iter.fold(init, |acc, (k, ())| f(acc, k)) } } impl ExactSizeIterator for IntoIter { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.iter.len() } } impl FusedIterator for IntoIter {} impl fmt::Debug for IntoIter { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let entries_iter = self.iter.iter().map(|(k, _)| k); f.debug_list().entries(entries_iter).finish() } } impl Iterator for Drain<'_, K, A> { type Item = K; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option { // Avoid `Option::map` because it bloats LLVM IR. match self.iter.next() { Some((k, _)) => Some(k), None => None, } } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.iter.fold(init, |acc, (k, ())| f(acc, k)) } } impl ExactSizeIterator for Drain<'_, K, A> { #[cfg_attr(feature = "inline-more", inline)] fn len(&self) -> usize { self.iter.len() } } impl FusedIterator for Drain<'_, K, A> {} impl fmt::Debug for Drain<'_, K, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let entries_iter = self.iter.iter().map(|(k, _)| k); f.debug_list().entries(entries_iter).finish() } } impl Iterator for ExtractIf<'_, K, F, A> where F: FnMut(&K) -> bool, { type Item = K; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option { self.inner .next(|&mut (ref k, ())| (self.f)(k)) .map(|(k, ())| k) } #[inline] fn size_hint(&self) -> (usize, Option) { (0, self.inner.iter.size_hint().1) } } impl FusedIterator for ExtractIf<'_, K, F, A> where F: FnMut(&K) -> bool {} impl Clone for Intersection<'_, T, S, A> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Intersection { iter: self.iter.clone(), ..*self } } } impl<'a, T, S, A> Iterator for Intersection<'a, T, S, A> where T: Eq + Hash, S: BuildHasher, A: Allocator, { type Item = &'a T; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<&'a T> { loop { let elt = self.iter.next()?; if self.other.contains(elt) { return Some(elt); } } } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { let (_, upper) = self.iter.size_hint(); (0, upper) } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.iter.fold(init, |acc, elt| { if self.other.contains(elt) { f(acc, elt) } else { acc } }) } } impl fmt::Debug for Intersection<'_, T, S, A> where T: fmt::Debug + Eq + Hash, S: BuildHasher, A: Allocator, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.clone()).finish() } } impl FusedIterator for Intersection<'_, T, S, A> where T: Eq + Hash, S: BuildHasher, A: Allocator, { } impl Clone for Difference<'_, T, S, A> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Difference { iter: self.iter.clone(), ..*self } } } impl<'a, T, S, A> Iterator for Difference<'a, T, S, A> where T: Eq + Hash, S: BuildHasher, A: Allocator, { type Item = &'a T; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<&'a T> { loop { let elt = self.iter.next()?; if !self.other.contains(elt) { return Some(elt); } } } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { let (_, upper) = self.iter.size_hint(); (0, upper) } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.iter.fold(init, |acc, elt| { if self.other.contains(elt) { acc } else { f(acc, elt) } }) } } impl FusedIterator for Difference<'_, T, S, A> where T: Eq + Hash, S: BuildHasher, A: Allocator, { } impl fmt::Debug for Difference<'_, T, S, A> where T: fmt::Debug + Eq + Hash, S: BuildHasher, A: Allocator, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.clone()).finish() } } impl Clone for SymmetricDifference<'_, T, S, A> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { SymmetricDifference { iter: self.iter.clone(), } } } impl<'a, T, S, A> Iterator for SymmetricDifference<'a, T, S, A> where T: Eq + Hash, S: BuildHasher, A: Allocator, { type Item = &'a T; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<&'a T> { self.iter.next() } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.iter.fold(init, f) } } impl FusedIterator for SymmetricDifference<'_, T, S, A> where T: Eq + Hash, S: BuildHasher, A: Allocator, { } impl fmt::Debug for SymmetricDifference<'_, T, S, A> where T: fmt::Debug + Eq + Hash, S: BuildHasher, A: Allocator, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.clone()).finish() } } impl Clone for Union<'_, T, S, A> { #[cfg_attr(feature = "inline-more", inline)] fn clone(&self) -> Self { Union { iter: self.iter.clone(), } } } impl FusedIterator for Union<'_, T, S, A> where T: Eq + Hash, S: BuildHasher, A: Allocator, { } impl fmt::Debug for Union<'_, T, S, A> where T: fmt::Debug + Eq + Hash, S: BuildHasher, A: Allocator, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.clone()).finish() } } impl<'a, T, S, A> Iterator for Union<'a, T, S, A> where T: Eq + Hash, S: BuildHasher, A: Allocator, { type Item = &'a T; #[cfg_attr(feature = "inline-more", inline)] fn next(&mut self) -> Option<&'a T> { self.iter.next() } #[cfg_attr(feature = "inline-more", inline)] fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } #[cfg_attr(feature = "inline-more", inline)] fn fold(self, init: B, f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.iter.fold(init, f) } } /// A view into a single entry in a set, which may either be vacant or occupied. /// /// This `enum` is constructed from the [`entry`] method on [`HashSet`]. /// /// [`HashSet`]: struct.HashSet.html /// [`entry`]: struct.HashSet.html#method.entry /// /// # Examples /// /// ``` /// use hashbrown::hash_set::{Entry, HashSet, OccupiedEntry}; /// /// let mut set = HashSet::new(); /// set.extend(["a", "b", "c"]); /// assert_eq!(set.len(), 3); /// /// // Existing value (insert) /// let entry: Entry<_, _> = set.entry("a"); /// let _raw_o: OccupiedEntry<_, _> = entry.insert(); /// assert_eq!(set.len(), 3); /// // Nonexistent value (insert) /// set.entry("d").insert(); /// /// // Existing value (or_insert) /// set.entry("b").or_insert(); /// // Nonexistent value (or_insert) /// set.entry("e").or_insert(); /// /// println!("Our HashSet: {:?}", set); /// /// let mut vec: Vec<_> = set.iter().copied().collect(); /// // The `Iter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, ["a", "b", "c", "d", "e"]); /// ``` pub enum Entry<'a, T, S, A = Global> where A: Allocator, { /// An occupied entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_set::{Entry, HashSet}; /// let mut set: HashSet<_> = ["a", "b"].into(); /// /// match set.entry("a") { /// Entry::Vacant(_) => unreachable!(), /// Entry::Occupied(_) => { } /// } /// ``` Occupied(OccupiedEntry<'a, T, S, A>), /// A vacant entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_set::{Entry, HashSet}; /// let mut set: HashSet<&str> = HashSet::new(); /// /// match set.entry("a") { /// Entry::Occupied(_) => unreachable!(), /// Entry::Vacant(_) => { } /// } /// ``` Vacant(VacantEntry<'a, T, S, A>), } impl fmt::Debug for Entry<'_, T, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match *self { Entry::Vacant(ref v) => f.debug_tuple("Entry").field(v).finish(), Entry::Occupied(ref o) => f.debug_tuple("Entry").field(o).finish(), } } } /// A view into an occupied entry in a `HashSet`. /// It is part of the [`Entry`] enum. /// /// [`Entry`]: enum.Entry.html /// /// # Examples /// /// ``` /// use hashbrown::hash_set::{Entry, HashSet, OccupiedEntry}; /// /// let mut set = HashSet::new(); /// set.extend(["a", "b", "c"]); /// /// let _entry_o: OccupiedEntry<_, _> = set.entry("a").insert(); /// assert_eq!(set.len(), 3); /// /// // Existing key /// match set.entry("a") { /// Entry::Vacant(_) => unreachable!(), /// Entry::Occupied(view) => { /// assert_eq!(view.get(), &"a"); /// } /// } /// /// assert_eq!(set.len(), 3); /// /// // Existing key (take) /// match set.entry("c") { /// Entry::Vacant(_) => unreachable!(), /// Entry::Occupied(view) => { /// assert_eq!(view.remove(), "c"); /// } /// } /// assert_eq!(set.get(&"c"), None); /// assert_eq!(set.len(), 2); /// ``` pub struct OccupiedEntry<'a, T, S, A: Allocator = Global> { inner: map::OccupiedEntry<'a, T, (), S, A>, } impl fmt::Debug for OccupiedEntry<'_, T, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("OccupiedEntry") .field("value", self.get()) .finish() } } /// A view into a vacant entry in a `HashSet`. /// It is part of the [`Entry`] enum. /// /// [`Entry`]: enum.Entry.html /// /// # Examples /// /// ``` /// use hashbrown::hash_set::{Entry, HashSet, VacantEntry}; /// /// let mut set = HashSet::<&str>::new(); /// /// let entry_v: VacantEntry<_, _> = match set.entry("a") { /// Entry::Vacant(view) => view, /// Entry::Occupied(_) => unreachable!(), /// }; /// entry_v.insert(); /// assert!(set.contains("a") && set.len() == 1); /// /// // Nonexistent key (insert) /// match set.entry("b") { /// Entry::Vacant(view) => view.insert(), /// Entry::Occupied(_) => unreachable!(), /// } /// assert!(set.contains("b") && set.len() == 2); /// ``` pub struct VacantEntry<'a, T, S, A: Allocator = Global> { inner: map::VacantEntry<'a, T, (), S, A>, } impl fmt::Debug for VacantEntry<'_, T, S, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_tuple("VacantEntry").field(self.get()).finish() } } impl<'a, T, S, A: Allocator> Entry<'a, T, S, A> { /// Sets the value of the entry, and returns an OccupiedEntry. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet<&str> = HashSet::new(); /// let entry = set.entry("horseyland").insert(); /// /// assert_eq!(entry.get(), &"horseyland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(self) -> OccupiedEntry<'a, T, S, A> where T: Hash, S: BuildHasher, { match self { Entry::Occupied(entry) => entry, Entry::Vacant(entry) => entry.insert_entry(), } } /// Ensures a value is in the entry by inserting if it was vacant. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet<&str> = HashSet::new(); /// /// // nonexistent key /// set.entry("poneyland").or_insert(); /// assert!(set.contains("poneyland")); /// /// // existing key /// set.entry("poneyland").or_insert(); /// assert!(set.contains("poneyland")); /// assert_eq!(set.len(), 1); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn or_insert(self) where T: Hash, S: BuildHasher, { if let Entry::Vacant(entry) = self { entry.insert(); } } /// Returns a reference to this entry's value. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet<&str> = HashSet::new(); /// set.entry("poneyland").or_insert(); /// // existing key /// assert_eq!(set.entry("poneyland").get(), &"poneyland"); /// // nonexistent key /// assert_eq!(set.entry("horseland").get(), &"horseland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get(&self) -> &T { match *self { Entry::Occupied(ref entry) => entry.get(), Entry::Vacant(ref entry) => entry.get(), } } } impl OccupiedEntry<'_, T, S, A> { /// Gets a reference to the value in the entry. /// /// # Examples /// /// ``` /// use hashbrown::hash_set::{Entry, HashSet}; /// /// let mut set: HashSet<&str> = HashSet::new(); /// set.entry("poneyland").or_insert(); /// /// match set.entry("poneyland") { /// Entry::Vacant(_) => panic!(), /// Entry::Occupied(entry) => assert_eq!(entry.get(), &"poneyland"), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get(&self) -> &T { self.inner.key() } /// Takes the value out of the entry, and returns it. /// Keeps the allocated memory for reuse. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// use hashbrown::hash_set::Entry; /// /// let mut set: HashSet<&str> = HashSet::new(); /// // The set is empty /// assert!(set.is_empty() && set.capacity() == 0); /// /// set.entry("poneyland").or_insert(); /// let capacity_before_remove = set.capacity(); /// /// if let Entry::Occupied(o) = set.entry("poneyland") { /// assert_eq!(o.remove(), "poneyland"); /// } /// /// assert_eq!(set.contains("poneyland"), false); /// // Now set hold none elements but capacity is equal to the old one /// assert!(set.len() == 0 && set.capacity() == capacity_before_remove); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove(self) -> T { self.inner.remove_entry().0 } /// Replaces the entry, returning the old value. The new value in the hash map will be /// the value used to create this entry. /// /// # Panics /// /// Will panic if this OccupiedEntry was created through [`Entry::insert`]. /// /// # Examples /// /// ``` /// use hashbrown::hash_set::{Entry, HashSet}; /// use std::rc::Rc; /// /// let mut set: HashSet> = HashSet::new(); /// let key_one = Rc::new("Stringthing".to_string()); /// let key_two = Rc::new("Stringthing".to_string()); /// /// set.insert(key_one.clone()); /// assert!(Rc::strong_count(&key_one) == 2 && Rc::strong_count(&key_two) == 1); /// /// match set.entry(key_two.clone()) { /// Entry::Occupied(entry) => { /// let old_key: Rc = entry.replace(); /// assert!(Rc::ptr_eq(&key_one, &old_key)); /// } /// Entry::Vacant(_) => panic!(), /// } /// /// assert!(Rc::strong_count(&key_one) == 1 && Rc::strong_count(&key_two) == 2); /// assert!(set.contains(&"Stringthing".to_owned())); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn replace(self) -> T { self.inner.replace_key() } } impl<'a, T, S, A: Allocator> VacantEntry<'a, T, S, A> { /// Gets a reference to the value that would be used when inserting /// through the `VacantEntry`. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// /// let mut set: HashSet<&str> = HashSet::new(); /// assert_eq!(set.entry("poneyland").get(), &"poneyland"); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn get(&self) -> &T { self.inner.key() } /// Take ownership of the value. /// /// # Examples /// /// ``` /// use hashbrown::hash_set::{Entry, HashSet}; /// /// let mut set: HashSet<&str> = HashSet::new(); /// /// match set.entry("poneyland") { /// Entry::Occupied(_) => panic!(), /// Entry::Vacant(v) => assert_eq!(v.into_value(), "poneyland"), /// } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn into_value(self) -> T { self.inner.into_key() } /// Sets the value of the entry with the VacantEntry's value. /// /// # Examples /// /// ``` /// use hashbrown::HashSet; /// use hashbrown::hash_set::Entry; /// /// let mut set: HashSet<&str> = HashSet::new(); /// /// if let Entry::Vacant(o) = set.entry("poneyland") { /// o.insert(); /// } /// assert!(set.contains("poneyland")); /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn insert(self) where T: Hash, S: BuildHasher, { self.inner.insert(()); } #[cfg_attr(feature = "inline-more", inline)] fn insert_entry(self) -> OccupiedEntry<'a, T, S, A> where T: Hash, S: BuildHasher, { OccupiedEntry { inner: self.inner.insert_entry(()), } } } #[allow(dead_code)] fn assert_covariance() { fn set<'new>(v: HashSet<&'static str>) -> HashSet<&'new str> { v } fn iter<'a, 'new>(v: Iter<'a, &'static str>) -> Iter<'a, &'new str> { v } fn into_iter<'new, A: Allocator>(v: IntoIter<&'static str, A>) -> IntoIter<&'new str, A> { v } fn difference<'a, 'new, A: Allocator>( v: Difference<'a, &'static str, DefaultHashBuilder, A>, ) -> Difference<'a, &'new str, DefaultHashBuilder, A> { v } fn symmetric_difference<'a, 'new, A: Allocator>( v: SymmetricDifference<'a, &'static str, DefaultHashBuilder, A>, ) -> SymmetricDifference<'a, &'new str, DefaultHashBuilder, A> { v } fn intersection<'a, 'new, A: Allocator>( v: Intersection<'a, &'static str, DefaultHashBuilder, A>, ) -> Intersection<'a, &'new str, DefaultHashBuilder, A> { v } fn union<'a, 'new, A: Allocator>( v: Union<'a, &'static str, DefaultHashBuilder, A>, ) -> Union<'a, &'new str, DefaultHashBuilder, A> { v } fn drain<'new, A: Allocator>(d: Drain<'static, &'static str, A>) -> Drain<'new, &'new str, A> { d } } #[cfg(test)] mod test_set { use super::super::map::DefaultHashBuilder; use super::HashSet; use std::vec::Vec; #[test] fn test_zero_capacities() { type HS = HashSet; let s = HS::new(); assert_eq!(s.capacity(), 0); let s = HS::default(); assert_eq!(s.capacity(), 0); let s = HS::with_hasher(DefaultHashBuilder::default()); assert_eq!(s.capacity(), 0); let s = HS::with_capacity(0); assert_eq!(s.capacity(), 0); let s = HS::with_capacity_and_hasher(0, DefaultHashBuilder::default()); assert_eq!(s.capacity(), 0); let mut s = HS::new(); s.insert(1); s.insert(2); s.remove(&1); s.remove(&2); s.shrink_to_fit(); assert_eq!(s.capacity(), 0); let mut s = HS::new(); s.reserve(0); assert_eq!(s.capacity(), 0); } #[test] fn test_disjoint() { let mut xs = HashSet::new(); let mut ys = HashSet::new(); assert!(xs.is_disjoint(&ys)); assert!(ys.is_disjoint(&xs)); assert!(xs.insert(5)); assert!(ys.insert(11)); assert!(xs.is_disjoint(&ys)); assert!(ys.is_disjoint(&xs)); assert!(xs.insert(7)); assert!(xs.insert(19)); assert!(xs.insert(4)); assert!(ys.insert(2)); assert!(ys.insert(-11)); assert!(xs.is_disjoint(&ys)); assert!(ys.is_disjoint(&xs)); assert!(ys.insert(7)); assert!(!xs.is_disjoint(&ys)); assert!(!ys.is_disjoint(&xs)); } #[test] fn test_subset_and_superset() { let mut a = HashSet::new(); assert!(a.insert(0)); assert!(a.insert(5)); assert!(a.insert(11)); assert!(a.insert(7)); let mut b = HashSet::new(); assert!(b.insert(0)); assert!(b.insert(7)); assert!(b.insert(19)); assert!(b.insert(250)); assert!(b.insert(11)); assert!(b.insert(200)); assert!(!a.is_subset(&b)); assert!(!a.is_superset(&b)); assert!(!b.is_subset(&a)); assert!(!b.is_superset(&a)); assert!(b.insert(5)); assert!(a.is_subset(&b)); assert!(!a.is_superset(&b)); assert!(!b.is_subset(&a)); assert!(b.is_superset(&a)); } #[test] fn test_iterate() { let mut a = HashSet::new(); for i in 0..32 { assert!(a.insert(i)); } let mut observed: u32 = 0; for k in &a { observed |= 1 << *k; } assert_eq!(observed, 0xFFFF_FFFF); } #[test] fn test_intersection() { let mut a = HashSet::new(); let mut b = HashSet::new(); assert!(a.insert(11)); assert!(a.insert(1)); assert!(a.insert(3)); assert!(a.insert(77)); assert!(a.insert(103)); assert!(a.insert(5)); assert!(a.insert(-5)); assert!(b.insert(2)); assert!(b.insert(11)); assert!(b.insert(77)); assert!(b.insert(-9)); assert!(b.insert(-42)); assert!(b.insert(5)); assert!(b.insert(3)); let mut i = 0; let expected = [3, 5, 11, 77]; for x in a.intersection(&b) { assert!(expected.contains(x)); i += 1; } assert_eq!(i, expected.len()); } #[test] fn test_difference() { let mut a = HashSet::new(); let mut b = HashSet::new(); assert!(a.insert(1)); assert!(a.insert(3)); assert!(a.insert(5)); assert!(a.insert(9)); assert!(a.insert(11)); assert!(b.insert(3)); assert!(b.insert(9)); let mut i = 0; let expected = [1, 5, 11]; for x in a.difference(&b) { assert!(expected.contains(x)); i += 1; } assert_eq!(i, expected.len()); } #[test] fn test_symmetric_difference() { let mut a = HashSet::new(); let mut b = HashSet::new(); assert!(a.insert(1)); assert!(a.insert(3)); assert!(a.insert(5)); assert!(a.insert(9)); assert!(a.insert(11)); assert!(b.insert(-2)); assert!(b.insert(3)); assert!(b.insert(9)); assert!(b.insert(14)); assert!(b.insert(22)); let mut i = 0; let expected = [-2, 1, 5, 11, 14, 22]; for x in a.symmetric_difference(&b) { assert!(expected.contains(x)); i += 1; } assert_eq!(i, expected.len()); } #[test] fn test_union() { let mut a = HashSet::new(); let mut b = HashSet::new(); assert!(a.insert(1)); assert!(a.insert(3)); assert!(a.insert(5)); assert!(a.insert(9)); assert!(a.insert(11)); assert!(a.insert(16)); assert!(a.insert(19)); assert!(a.insert(24)); assert!(b.insert(-2)); assert!(b.insert(1)); assert!(b.insert(5)); assert!(b.insert(9)); assert!(b.insert(13)); assert!(b.insert(19)); let mut i = 0; let expected = [-2, 1, 3, 5, 9, 11, 13, 16, 19, 24]; for x in a.union(&b) { assert!(expected.contains(x)); i += 1; } assert_eq!(i, expected.len()); } #[test] fn test_from_map() { let mut a = crate::HashMap::new(); a.insert(1, ()); a.insert(2, ()); a.insert(3, ()); a.insert(4, ()); let a: HashSet<_> = a.into(); assert_eq!(a.len(), 4); assert!(a.contains(&1)); assert!(a.contains(&2)); assert!(a.contains(&3)); assert!(a.contains(&4)); } #[test] fn test_from_iter() { let xs = [1, 2, 2, 3, 4, 5, 6, 7, 8, 9]; let set: HashSet<_> = xs.iter().copied().collect(); for x in &xs { assert!(set.contains(x)); } assert_eq!(set.iter().len(), xs.len() - 1); } #[test] fn test_move_iter() { let hs = { let mut hs = HashSet::new(); hs.insert('a'); hs.insert('b'); hs }; let v = hs.into_iter().collect::>(); assert!(v == ['a', 'b'] || v == ['b', 'a']); } #[test] fn test_eq() { // These constants once happened to expose a bug in insert(). // I'm keeping them around to prevent a regression. let mut s1 = HashSet::new(); s1.insert(1); s1.insert(2); s1.insert(3); let mut s2 = HashSet::new(); s2.insert(1); s2.insert(2); assert!(s1 != s2); s2.insert(3); assert_eq!(s1, s2); } #[test] fn test_show() { let mut set = HashSet::new(); let empty = HashSet::::new(); set.insert(1); set.insert(2); let set_str = format!("{set:?}"); assert!(set_str == "{1, 2}" || set_str == "{2, 1}"); assert_eq!(format!("{empty:?}"), "{}"); } #[test] fn test_trivial_drain() { let mut s = HashSet::::new(); for _ in s.drain() {} assert!(s.is_empty()); drop(s); let mut s = HashSet::::new(); drop(s.drain()); assert!(s.is_empty()); } #[test] fn test_drain() { let mut s: HashSet<_> = (1..100).collect(); // try this a bunch of times to make sure we don't screw up internal state. for _ in 0..20 { assert_eq!(s.len(), 99); { let mut last_i = 0; let mut d = s.drain(); for (i, x) in d.by_ref().take(50).enumerate() { last_i = i; assert!(x != 0); } assert_eq!(last_i, 49); } if !s.is_empty() { panic!("s should be empty!"); } // reset to try again. s.extend(1..100); } } #[test] fn test_replace() { use core::hash; #[derive(Debug)] #[allow(dead_code)] struct Foo(&'static str, i32); impl PartialEq for Foo { fn eq(&self, other: &Self) -> bool { self.0 == other.0 } } impl Eq for Foo {} impl hash::Hash for Foo { fn hash(&self, h: &mut H) { self.0.hash(h); } } let mut s = HashSet::new(); assert_eq!(s.replace(Foo("a", 1)), None); assert_eq!(s.len(), 1); assert_eq!(s.replace(Foo("a", 2)), Some(Foo("a", 1))); assert_eq!(s.len(), 1); let mut it = s.iter(); assert_eq!(it.next(), Some(&Foo("a", 2))); assert_eq!(it.next(), None); } #[test] #[allow(clippy::needless_borrow)] fn test_extend_ref() { let mut a = HashSet::new(); a.insert(1); a.extend([2, 3, 4]); assert_eq!(a.len(), 4); assert!(a.contains(&1)); assert!(a.contains(&2)); assert!(a.contains(&3)); assert!(a.contains(&4)); let mut b = HashSet::new(); b.insert(5); b.insert(6); a.extend(&b); assert_eq!(a.len(), 6); assert!(a.contains(&1)); assert!(a.contains(&2)); assert!(a.contains(&3)); assert!(a.contains(&4)); assert!(a.contains(&5)); assert!(a.contains(&6)); } #[test] fn test_retain() { let xs = [1, 2, 3, 4, 5, 6]; let mut set: HashSet = xs.iter().copied().collect(); set.retain(|&k| k % 2 == 0); assert_eq!(set.len(), 3); assert!(set.contains(&2)); assert!(set.contains(&4)); assert!(set.contains(&6)); } #[test] fn test_extract_if() { { let mut set: HashSet = (0..8).collect(); let drained = set.extract_if(|&k| k % 2 == 0); let mut out = drained.collect::>(); out.sort_unstable(); assert_eq!(vec![0, 2, 4, 6], out); assert_eq!(set.len(), 4); } { let mut set: HashSet = (0..8).collect(); set.extract_if(|&k| k % 2 == 0).for_each(drop); assert_eq!(set.len(), 4, "Removes non-matching items on drop"); } } #[test] fn test_const_with_hasher() { use core::hash::BuildHasher; use std::collections::hash_map::DefaultHasher; #[derive(Clone)] struct MyHasher; impl BuildHasher for MyHasher { type Hasher = DefaultHasher; fn build_hasher(&self) -> DefaultHasher { DefaultHasher::new() } } const EMPTY_SET: HashSet = HashSet::with_hasher(MyHasher); let mut set = EMPTY_SET; set.insert(19); assert!(set.contains(&19)); } #[test] fn rehash_in_place() { let mut set = HashSet::new(); for i in 0..224 { set.insert(i); } assert_eq!( set.capacity(), 224, "The set must be at or close to capacity to trigger a re hashing" ); for i in 100..1400 { set.remove(&(i - 100)); set.insert(i); } } #[test] fn collect() { // At the time of writing, this hits the ZST case in from_base_index // (and without the `map`, it does not). let mut _set: HashSet<_> = (0..3).map(|_| ()).collect(); } } hashbrown-0.14.5/src/table.rs000064400000000000000000001764421046102023000141500ustar 00000000000000use core::{fmt, iter::FusedIterator, marker::PhantomData}; use crate::{ raw::{ Allocator, Bucket, Global, InsertSlot, RawDrain, RawExtractIf, RawIntoIter, RawIter, RawTable, }, TryReserveError, }; /// Low-level hash table with explicit hashing. /// /// The primary use case for this type over [`HashMap`] or [`HashSet`] is to /// support types that do not implement the [`Hash`] and [`Eq`] traits, but /// instead require additional data not contained in the key itself to compute a /// hash and compare two elements for equality. /// /// Examples of when this can be useful include: /// - An `IndexMap` implementation where indices into a `Vec` are stored as /// elements in a `HashTable`. Hashing and comparing the elements /// requires indexing the associated `Vec` to get the actual value referred to /// by the index. /// - Avoiding re-computing a hash when it is already known. /// - Mutating the key of an element in a way that doesn't affect its hash. /// /// To achieve this, `HashTable` methods that search for an element in the table /// require a hash value and equality function to be explicitly passed in as /// arguments. The method will then iterate over the elements with the given /// hash and call the equality function on each of them, until a match is found. /// /// In most cases, a `HashTable` will not be exposed directly in an API. It will /// instead be wrapped in a helper type which handles the work of calculating /// hash values and comparing elements. /// /// Due to its low-level nature, this type provides fewer guarantees than /// [`HashMap`] and [`HashSet`]. Specifically, the API allows you to shoot /// yourself in the foot by having multiple elements with identical keys in the /// table. The table itself will still function correctly and lookups will /// arbitrarily return one of the matching elements. However you should avoid /// doing this because it changes the runtime of hash table operations from /// `O(1)` to `O(k)` where `k` is the number of duplicate entries. /// /// [`HashMap`]: super::HashMap /// [`HashSet`]: super::HashSet pub struct HashTable where A: Allocator, { pub(crate) raw: RawTable, } impl HashTable { /// Creates an empty `HashTable`. /// /// The hash table is initially created with a capacity of 0, so it will not allocate until it /// is first inserted into. /// /// # Examples /// /// ``` /// use hashbrown::HashTable; /// let mut table: HashTable<&str> = HashTable::new(); /// assert_eq!(table.len(), 0); /// assert_eq!(table.capacity(), 0); /// ``` pub const fn new() -> Self { Self { raw: RawTable::new(), } } /// Creates an empty `HashTable` with the specified capacity. /// /// The hash table will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash table will not allocate. /// /// # Examples /// /// ``` /// use hashbrown::HashTable; /// let mut table: HashTable<&str> = HashTable::with_capacity(10); /// assert_eq!(table.len(), 0); /// assert!(table.capacity() >= 10); /// ``` pub fn with_capacity(capacity: usize) -> Self { Self { raw: RawTable::with_capacity(capacity), } } } impl HashTable where A: Allocator, { /// Creates an empty `HashTable` using the given allocator. /// /// The hash table is initially created with a capacity of 0, so it will not allocate until it /// is first inserted into. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use bumpalo::Bump; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let bump = Bump::new(); /// let mut table = HashTable::new_in(&bump); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// // The created HashTable holds none elements /// assert_eq!(table.len(), 0); /// /// // The created HashTable also doesn't allocate memory /// assert_eq!(table.capacity(), 0); /// /// // Now we insert element inside created HashTable /// table.insert_unique(hasher(&"One"), "One", hasher); /// // We can see that the HashTable holds 1 element /// assert_eq!(table.len(), 1); /// // And it also allocates some capacity /// assert!(table.capacity() > 1); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub const fn new_in(alloc: A) -> Self { Self { raw: RawTable::new_in(alloc), } } /// Creates an empty `HashTable` with the specified capacity using the given allocator. /// /// The hash table will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash table will not allocate. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use bumpalo::Bump; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let bump = Bump::new(); /// let mut table = HashTable::with_capacity_in(5, &bump); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// // The created HashTable holds none elements /// assert_eq!(table.len(), 0); /// // But it can hold at least 5 elements without reallocating /// let empty_map_capacity = table.capacity(); /// assert!(empty_map_capacity >= 5); /// /// // Now we insert some 5 elements inside created HashTable /// table.insert_unique(hasher(&"One"), "One", hasher); /// table.insert_unique(hasher(&"Two"), "Two", hasher); /// table.insert_unique(hasher(&"Three"), "Three", hasher); /// table.insert_unique(hasher(&"Four"), "Four", hasher); /// table.insert_unique(hasher(&"Five"), "Five", hasher); /// /// // We can see that the HashTable holds 5 elements /// assert_eq!(table.len(), 5); /// // But its capacity isn't changed /// assert_eq!(table.capacity(), empty_map_capacity) /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn with_capacity_in(capacity: usize, alloc: A) -> Self { Self { raw: RawTable::with_capacity_in(capacity, alloc), } } /// Returns a reference to the underlying allocator. pub fn allocator(&self) -> &A { self.raw.allocator() } /// Returns a reference to an entry in the table with the given hash and /// which satisfies the equality function passed. /// /// This method will call `eq` for all entries with the given hash, but may /// also call it for entries with a different hash. `eq` should only return /// true for the desired entry, at which point the search is stopped. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&1), 1, hasher); /// table.insert_unique(hasher(&2), 2, hasher); /// table.insert_unique(hasher(&3), 3, hasher); /// assert_eq!(table.find(hasher(&2), |&val| val == 2), Some(&2)); /// assert_eq!(table.find(hasher(&4), |&val| val == 4), None); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn find(&self, hash: u64, eq: impl FnMut(&T) -> bool) -> Option<&T> { self.raw.get(hash, eq) } /// Returns a mutable reference to an entry in the table with the given hash /// and which satisfies the equality function passed. /// /// This method will call `eq` for all entries with the given hash, but may /// also call it for entries with a different hash. `eq` should only return /// true for the desired entry, at which point the search is stopped. /// /// When mutating an entry, you should ensure that it still retains the same /// hash value as when it was inserted, otherwise lookups of that entry may /// fail to find it. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&1), (1, "a"), |val| hasher(&val.0)); /// if let Some(val) = table.find_mut(hasher(&1), |val| val.0 == 1) { /// val.1 = "b"; /// } /// assert_eq!(table.find(hasher(&1), |val| val.0 == 1), Some(&(1, "b"))); /// assert_eq!(table.find(hasher(&2), |val| val.0 == 2), None); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn find_mut(&mut self, hash: u64, eq: impl FnMut(&T) -> bool) -> Option<&mut T> { self.raw.get_mut(hash, eq) } /// Returns an `OccupiedEntry` for an entry in the table with the given hash /// and which satisfies the equality function passed. /// /// This can be used to remove the entry from the table. Call /// [`HashTable::entry`] instead if you wish to insert an entry if the /// lookup fails. /// /// This method will call `eq` for all entries with the given hash, but may /// also call it for entries with a different hash. `eq` should only return /// true for the desired entry, at which point the search is stopped. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&1), (1, "a"), |val| hasher(&val.0)); /// if let Ok(entry) = table.find_entry(hasher(&1), |val| val.0 == 1) { /// entry.remove(); /// } /// assert_eq!(table.find(hasher(&1), |val| val.0 == 1), None); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn find_entry( &mut self, hash: u64, eq: impl FnMut(&T) -> bool, ) -> Result, AbsentEntry<'_, T, A>> { match self.raw.find(hash, eq) { Some(bucket) => Ok(OccupiedEntry { hash, bucket, table: self, }), None => Err(AbsentEntry { table: self }), } } /// Returns an `Entry` for an entry in the table with the given hash /// and which satisfies the equality function passed. /// /// This can be used to remove the entry from the table, or insert a new /// entry with the given hash if one doesn't already exist. /// /// This method will call `eq` for all entries with the given hash, but may /// also call it for entries with a different hash. `eq` should only return /// true for the desired entry, at which point the search is stopped. /// /// This method may grow the table in preparation for an insertion. Call /// [`HashTable::find_entry`] if this is undesirable. /// /// `hasher` is called if entries need to be moved or copied to a new table. /// This must return the same hash value that each entry was inserted with. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::Entry; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&1), (1, "a"), |val| hasher(&val.0)); /// if let Entry::Occupied(entry) = table.entry(hasher(&1), |val| val.0 == 1, |val| hasher(&val.0)) /// { /// entry.remove(); /// } /// if let Entry::Vacant(entry) = table.entry(hasher(&2), |val| val.0 == 2, |val| hasher(&val.0)) { /// entry.insert((2, "b")); /// } /// assert_eq!(table.find(hasher(&1), |val| val.0 == 1), None); /// assert_eq!(table.find(hasher(&2), |val| val.0 == 2), Some(&(2, "b"))); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn entry( &mut self, hash: u64, eq: impl FnMut(&T) -> bool, hasher: impl Fn(&T) -> u64, ) -> Entry<'_, T, A> { match self.raw.find_or_find_insert_slot(hash, eq, hasher) { Ok(bucket) => Entry::Occupied(OccupiedEntry { hash, bucket, table: self, }), Err(insert_slot) => Entry::Vacant(VacantEntry { hash, insert_slot, table: self, }), } } /// Inserts an element into the `HashTable` with the given hash value, but /// without checking whether an equivalent element already exists within the /// table. /// /// `hasher` is called if entries need to be moved or copied to a new table. /// This must return the same hash value that each entry was inserted with. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut v = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// v.insert_unique(hasher(&1), 1, hasher); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn insert_unique( &mut self, hash: u64, value: T, hasher: impl Fn(&T) -> u64, ) -> OccupiedEntry<'_, T, A> { let bucket = self.raw.insert(hash, value, hasher); OccupiedEntry { hash, bucket, table: self, } } /// Clears the table, removing all values. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut v = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// v.insert_unique(hasher(&1), 1, hasher); /// v.clear(); /// assert!(v.is_empty()); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn clear(&mut self) { self.raw.clear(); } /// Shrinks the capacity of the table as much as possible. It will drop /// down as much as possible while maintaining the internal rules /// and possibly leaving some space in accordance with the resize policy. /// /// `hasher` is called if entries need to be moved or copied to a new table. /// This must return the same hash value that each entry was inserted with. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::with_capacity(100); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&1), 1, hasher); /// table.insert_unique(hasher(&2), 2, hasher); /// assert!(table.capacity() >= 100); /// table.shrink_to_fit(hasher); /// assert!(table.capacity() >= 2); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn shrink_to_fit(&mut self, hasher: impl Fn(&T) -> u64) { self.raw.shrink_to(self.len(), hasher) } /// Shrinks the capacity of the table with a lower limit. It will drop /// down no lower than the supplied limit while maintaining the internal rules /// and possibly leaving some space in accordance with the resize policy. /// /// `hasher` is called if entries need to be moved or copied to a new table. /// This must return the same hash value that each entry was inserted with. /// /// Panics if the current capacity is smaller than the supplied /// minimum capacity. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::with_capacity(100); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&1), 1, hasher); /// table.insert_unique(hasher(&2), 2, hasher); /// assert!(table.capacity() >= 100); /// table.shrink_to(10, hasher); /// assert!(table.capacity() >= 10); /// table.shrink_to(0, hasher); /// assert!(table.capacity() >= 2); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn shrink_to(&mut self, min_capacity: usize, hasher: impl Fn(&T) -> u64) { self.raw.shrink_to(min_capacity, hasher); } /// Reserves capacity for at least `additional` more elements to be inserted /// in the `HashTable`. The collection may reserve more space to avoid /// frequent reallocations. /// /// `hasher` is called if entries need to be moved or copied to a new table. /// This must return the same hash value that each entry was inserted with. /// /// # Panics /// /// Panics if the new capacity exceeds [`isize::MAX`] bytes and [`abort`] the program /// in case of allocation error. Use [`try_reserve`](HashTable::try_reserve) instead /// if you want to handle memory allocation failure. /// /// [`isize::MAX`]: https://doc.rust-lang.org/std/primitive.isize.html /// [`abort`]: https://doc.rust-lang.org/alloc/alloc/fn.handle_alloc_error.html /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.reserve(10, hasher); /// assert!(table.capacity() >= 10); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn reserve(&mut self, additional: usize, hasher: impl Fn(&T) -> u64) { self.raw.reserve(additional, hasher) } /// Tries to reserve capacity for at least `additional` more elements to be inserted /// in the given `HashTable`. The collection may reserve more space to avoid /// frequent reallocations. /// /// `hasher` is called if entries need to be moved or copied to a new table. /// This must return the same hash value that each entry was inserted with. /// /// # Errors /// /// If the capacity overflows, or the allocator reports a failure, then an error /// is returned. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table /// .try_reserve(10, hasher) /// .expect("why is the test harness OOMing on 10 bytes?"); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn try_reserve( &mut self, additional: usize, hasher: impl Fn(&T) -> u64, ) -> Result<(), TryReserveError> { self.raw.try_reserve(additional, hasher) } /// Returns the number of elements the table can hold without reallocating. /// /// # Examples /// /// ``` /// use hashbrown::HashTable; /// let table: HashTable = HashTable::with_capacity(100); /// assert!(table.capacity() >= 100); /// ``` pub fn capacity(&self) -> usize { self.raw.capacity() } /// Returns the number of elements in the table. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// let mut v = HashTable::new(); /// assert_eq!(v.len(), 0); /// v.insert_unique(hasher(&1), 1, hasher); /// assert_eq!(v.len(), 1); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn len(&self) -> usize { self.raw.len() } /// Returns `true` if the set contains no elements. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// let mut v = HashTable::new(); /// assert!(v.is_empty()); /// v.insert_unique(hasher(&1), 1, hasher); /// assert!(!v.is_empty()); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn is_empty(&self) -> bool { self.raw.is_empty() } /// An iterator visiting all elements in arbitrary order. /// The iterator element type is `&'a T`. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&"a"), "b", hasher); /// table.insert_unique(hasher(&"b"), "b", hasher); /// /// // Will print in an arbitrary order. /// for x in table.iter() { /// println!("{}", x); /// } /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn iter(&self) -> Iter<'_, T> { Iter { inner: unsafe { self.raw.iter() }, marker: PhantomData, } } /// An iterator visiting all elements in arbitrary order, /// with mutable references to the elements. /// The iterator element type is `&'a mut T`. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&1), 1, hasher); /// table.insert_unique(hasher(&2), 2, hasher); /// table.insert_unique(hasher(&3), 3, hasher); /// /// // Update all values /// for val in table.iter_mut() { /// *val *= 2; /// } /// /// assert_eq!(table.len(), 3); /// let mut vec: Vec = Vec::new(); /// /// for val in &table { /// println!("val: {}", val); /// vec.push(*val); /// } /// /// // The `Iter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, [2, 4, 6]); /// /// assert_eq!(table.len(), 3); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn iter_mut(&mut self) -> IterMut<'_, T> { IterMut { inner: unsafe { self.raw.iter() }, marker: PhantomData, } } /// Retains only the elements specified by the predicate. /// /// In other words, remove all elements `e` such that `f(&e)` returns `false`. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// for x in 1..=6 { /// table.insert_unique(hasher(&x), x, hasher); /// } /// table.retain(|&mut x| x % 2 == 0); /// assert_eq!(table.len(), 3); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn retain(&mut self, mut f: impl FnMut(&mut T) -> bool) { // Here we only use `iter` as a temporary, preventing use-after-free unsafe { for item in self.raw.iter() { if !f(item.as_mut()) { self.raw.erase(item); } } } } /// Clears the set, returning all elements in an iterator. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// for x in 1..=3 { /// table.insert_unique(hasher(&x), x, hasher); /// } /// assert!(!table.is_empty()); /// /// // print 1, 2, 3 in an arbitrary order /// for i in table.drain() { /// println!("{}", i); /// } /// /// assert!(table.is_empty()); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn drain(&mut self) -> Drain<'_, T, A> { Drain { inner: self.raw.drain(), } } /// Drains elements which are true under the given predicate, /// and returns an iterator over the removed items. /// /// In other words, move all elements `e` such that `f(&e)` returns `true` out /// into another iterator. /// /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating /// or the iteration short-circuits, then the remaining elements will be retained. /// Use [`retain()`] with a negated predicate if you do not need the returned iterator. /// /// [`retain()`]: HashTable::retain /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// for x in 0..8 { /// table.insert_unique(hasher(&x), x, hasher); /// } /// let drained: Vec = table.extract_if(|&mut v| v % 2 == 0).collect(); /// /// let mut evens = drained.into_iter().collect::>(); /// let mut odds = table.into_iter().collect::>(); /// evens.sort(); /// odds.sort(); /// /// assert_eq!(evens, vec![0, 2, 4, 6]); /// assert_eq!(odds, vec![1, 3, 5, 7]); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn extract_if(&mut self, f: F) -> ExtractIf<'_, T, F, A> where F: FnMut(&mut T) -> bool, { ExtractIf { f, inner: RawExtractIf { iter: unsafe { self.raw.iter() }, table: &mut self.raw, }, } } /// Attempts to get mutable references to `N` values in the map at once. /// /// The `eq` argument should be a closure such that `eq(i, k)` returns true if `k` is equal to /// the `i`th key to be looked up. /// /// Returns an array of length `N` with the results of each query. For soundness, at most one /// mutable reference will be returned to any value. `None` will be returned if any of the /// keys are duplicates or missing. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::Entry; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut libraries: HashTable<(&str, u32)> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// for (k, v) in [ /// ("Bodleian Library", 1602), /// ("Athenæum", 1807), /// ("Herzogin-Anna-Amalia-Bibliothek", 1691), /// ("Library of Congress", 1800), /// ] { /// libraries.insert_unique(hasher(&k), (k, v), |(k, _)| hasher(&k)); /// } /// /// let keys = ["Athenæum", "Library of Congress"]; /// let got = libraries.get_many_mut(keys.map(|k| hasher(&k)), |i, val| keys[i] == val.0); /// assert_eq!( /// got, /// Some([&mut ("Athenæum", 1807), &mut ("Library of Congress", 1800),]), /// ); /// /// // Missing keys result in None /// let keys = ["Athenæum", "New York Public Library"]; /// let got = libraries.get_many_mut(keys.map(|k| hasher(&k)), |i, val| keys[i] == val.0); /// assert_eq!(got, None); /// /// // Duplicate keys result in None /// let keys = ["Athenæum", "Athenæum"]; /// let got = libraries.get_many_mut(keys.map(|k| hasher(&k)), |i, val| keys[i] == val.0); /// assert_eq!(got, None); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn get_many_mut( &mut self, hashes: [u64; N], eq: impl FnMut(usize, &T) -> bool, ) -> Option<[&'_ mut T; N]> { self.raw.get_many_mut(hashes, eq) } /// Attempts to get mutable references to `N` values in the map at once, without validating that /// the values are unique. /// /// The `eq` argument should be a closure such that `eq(i, k)` returns true if `k` is equal to /// the `i`th key to be looked up. /// /// Returns an array of length `N` with the results of each query. `None` will be returned if /// any of the keys are missing. /// /// For a safe alternative see [`get_many_mut`](`HashTable::get_many_mut`). /// /// # Safety /// /// Calling this method with overlapping keys is *[undefined behavior]* even if the resulting /// references are not used. /// /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::Entry; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut libraries: HashTable<(&str, u32)> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// for (k, v) in [ /// ("Bodleian Library", 1602), /// ("Athenæum", 1807), /// ("Herzogin-Anna-Amalia-Bibliothek", 1691), /// ("Library of Congress", 1800), /// ] { /// libraries.insert_unique(hasher(&k), (k, v), |(k, _)| hasher(&k)); /// } /// /// let keys = ["Athenæum", "Library of Congress"]; /// let got = libraries.get_many_mut(keys.map(|k| hasher(&k)), |i, val| keys[i] == val.0); /// assert_eq!( /// got, /// Some([&mut ("Athenæum", 1807), &mut ("Library of Congress", 1800),]), /// ); /// /// // Missing keys result in None /// let keys = ["Athenæum", "New York Public Library"]; /// let got = libraries.get_many_mut(keys.map(|k| hasher(&k)), |i, val| keys[i] == val.0); /// assert_eq!(got, None); /// /// // Duplicate keys result in None /// let keys = ["Athenæum", "Athenæum"]; /// let got = libraries.get_many_mut(keys.map(|k| hasher(&k)), |i, val| keys[i] == val.0); /// assert_eq!(got, None); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub unsafe fn get_many_unchecked_mut( &mut self, hashes: [u64; N], eq: impl FnMut(usize, &T) -> bool, ) -> Option<[&'_ mut T; N]> { self.raw.get_many_unchecked_mut(hashes, eq) } } impl IntoIterator for HashTable where A: Allocator, { type Item = T; type IntoIter = IntoIter; fn into_iter(self) -> IntoIter { IntoIter { inner: self.raw.into_iter(), } } } impl<'a, T, A> IntoIterator for &'a HashTable where A: Allocator, { type Item = &'a T; type IntoIter = Iter<'a, T>; fn into_iter(self) -> Iter<'a, T> { self.iter() } } impl<'a, T, A> IntoIterator for &'a mut HashTable where A: Allocator, { type Item = &'a mut T; type IntoIter = IterMut<'a, T>; fn into_iter(self) -> IterMut<'a, T> { self.iter_mut() } } impl Default for HashTable where A: Allocator + Default, { fn default() -> Self { Self { raw: Default::default(), } } } impl Clone for HashTable where T: Clone, A: Allocator + Clone, { fn clone(&self) -> Self { Self { raw: self.raw.clone(), } } } impl fmt::Debug for HashTable where T: fmt::Debug, A: Allocator, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_set().entries(self.iter()).finish() } } /// A view into a single entry in a table, which may either be vacant or occupied. /// /// This `enum` is constructed from the [`entry`] method on [`HashTable`]. /// /// [`HashTable`]: struct.HashTable.html /// [`entry`]: struct.HashTable.html#method.entry /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::{Entry, HashTable, OccupiedEntry}; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// for x in ["a", "b", "c"] { /// table.insert_unique(hasher(&x), x, hasher); /// } /// assert_eq!(table.len(), 3); /// /// // Existing value (insert) /// let entry: Entry<_> = table.entry(hasher(&"a"), |&x| x == "a", hasher); /// let _raw_o: OccupiedEntry<_, _> = entry.insert("a"); /// assert_eq!(table.len(), 3); /// // Nonexistent value (insert) /// table.entry(hasher(&"d"), |&x| x == "d", hasher).insert("d"); /// /// // Existing value (or_insert) /// table /// .entry(hasher(&"b"), |&x| x == "b", hasher) /// .or_insert("b"); /// // Nonexistent value (or_insert) /// table /// .entry(hasher(&"e"), |&x| x == "e", hasher) /// .or_insert("e"); /// /// println!("Our HashTable: {:?}", table); /// /// let mut vec: Vec<_> = table.iter().copied().collect(); /// // The `Iter` iterator produces items in arbitrary order, so the /// // items must be sorted to test them against a sorted array. /// vec.sort_unstable(); /// assert_eq!(vec, ["a", "b", "c", "d", "e"]); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub enum Entry<'a, T, A = Global> where A: Allocator, { /// An occupied entry. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::{Entry, HashTable, OccupiedEntry}; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// for x in ["a", "b"] { /// table.insert_unique(hasher(&x), x, hasher); /// } /// /// match table.entry(hasher(&"a"), |&x| x == "a", hasher) { /// Entry::Vacant(_) => unreachable!(), /// Entry::Occupied(_) => {} /// } /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` Occupied(OccupiedEntry<'a, T, A>), /// A vacant entry. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::{Entry, HashTable, OccupiedEntry}; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::<&str>::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// match table.entry(hasher(&"a"), |&x| x == "a", hasher) { /// Entry::Vacant(_) => {} /// Entry::Occupied(_) => unreachable!(), /// } /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` Vacant(VacantEntry<'a, T, A>), } impl fmt::Debug for Entry<'_, T, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match *self { Entry::Vacant(ref v) => f.debug_tuple("Entry").field(v).finish(), Entry::Occupied(ref o) => f.debug_tuple("Entry").field(o).finish(), } } } impl<'a, T, A> Entry<'a, T, A> where A: Allocator, { /// Sets the value of the entry, replacing any existing value if there is /// one, and returns an [`OccupiedEntry`]. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<&str> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// let entry = table /// .entry(hasher(&"horseyland"), |&x| x == "horseyland", hasher) /// .insert("horseyland"); /// /// assert_eq!(entry.get(), &"horseyland"); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn insert(self, value: T) -> OccupiedEntry<'a, T, A> { match self { Entry::Occupied(mut entry) => { *entry.get_mut() = value; entry } Entry::Vacant(entry) => entry.insert(value), } } /// Ensures a value is in the entry by inserting if it was vacant. /// /// Returns an [`OccupiedEntry`] pointing to the now-occupied entry. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<&str> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// // nonexistent key /// table /// .entry(hasher(&"poneyland"), |&x| x == "poneyland", hasher) /// .or_insert("poneyland"); /// assert!(table /// .find(hasher(&"poneyland"), |&x| x == "poneyland") /// .is_some()); /// /// // existing key /// table /// .entry(hasher(&"poneyland"), |&x| x == "poneyland", hasher) /// .or_insert("poneyland"); /// assert!(table /// .find(hasher(&"poneyland"), |&x| x == "poneyland") /// .is_some()); /// assert_eq!(table.len(), 1); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn or_insert(self, default: T) -> OccupiedEntry<'a, T, A> { match self { Entry::Occupied(entry) => entry, Entry::Vacant(entry) => entry.insert(default), } } /// Ensures a value is in the entry by inserting the result of the default function if empty.. /// /// Returns an [`OccupiedEntry`] pointing to the now-occupied entry. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// table /// .entry(hasher("poneyland"), |x| x == "poneyland", |val| hasher(val)) /// .or_insert_with(|| "poneyland".to_string()); /// /// assert!(table /// .find(hasher(&"poneyland"), |x| x == "poneyland") /// .is_some()); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn or_insert_with(self, default: impl FnOnce() -> T) -> OccupiedEntry<'a, T, A> { match self { Entry::Occupied(entry) => entry, Entry::Vacant(entry) => entry.insert(default()), } } /// Provides in-place mutable access to an occupied entry before any /// potential inserts into the table. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<(&str, u32)> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// table /// .entry( /// hasher(&"poneyland"), /// |&(x, _)| x == "poneyland", /// |(k, _)| hasher(&k), /// ) /// .and_modify(|(_, v)| *v += 1) /// .or_insert(("poneyland", 42)); /// assert_eq!( /// table.find(hasher(&"poneyland"), |&(k, _)| k == "poneyland"), /// Some(&("poneyland", 42)) /// ); /// /// table /// .entry( /// hasher(&"poneyland"), /// |&(x, _)| x == "poneyland", /// |(k, _)| hasher(&k), /// ) /// .and_modify(|(_, v)| *v += 1) /// .or_insert(("poneyland", 42)); /// assert_eq!( /// table.find(hasher(&"poneyland"), |&(k, _)| k == "poneyland"), /// Some(&("poneyland", 43)) /// ); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn and_modify(self, f: impl FnOnce(&mut T)) -> Self { match self { Entry::Occupied(mut entry) => { f(entry.get_mut()); Entry::Occupied(entry) } Entry::Vacant(entry) => Entry::Vacant(entry), } } } /// A view into an occupied entry in a `HashTable`. /// It is part of the [`Entry`] enum. /// /// [`Entry`]: enum.Entry.html /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::{Entry, HashTable, OccupiedEntry}; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// for x in ["a", "b", "c"] { /// table.insert_unique(hasher(&x), x, hasher); /// } /// assert_eq!(table.len(), 3); /// /// let _entry_o: OccupiedEntry<_, _> = table.find_entry(hasher(&"a"), |&x| x == "a").unwrap(); /// assert_eq!(table.len(), 3); /// /// // Existing key /// match table.entry(hasher(&"a"), |&x| x == "a", hasher) { /// Entry::Vacant(_) => unreachable!(), /// Entry::Occupied(view) => { /// assert_eq!(view.get(), &"a"); /// } /// } /// /// assert_eq!(table.len(), 3); /// /// // Existing key (take) /// match table.entry(hasher(&"c"), |&x| x == "c", hasher) { /// Entry::Vacant(_) => unreachable!(), /// Entry::Occupied(view) => { /// assert_eq!(view.remove().0, "c"); /// } /// } /// assert_eq!(table.find(hasher(&"c"), |&x| x == "c"), None); /// assert_eq!(table.len(), 2); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub struct OccupiedEntry<'a, T, A = Global> where A: Allocator, { hash: u64, bucket: Bucket, table: &'a mut HashTable, } unsafe impl Send for OccupiedEntry<'_, T, A> where T: Send, A: Send + Allocator, { } unsafe impl Sync for OccupiedEntry<'_, T, A> where T: Sync, A: Sync + Allocator, { } impl fmt::Debug for OccupiedEntry<'_, T, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("OccupiedEntry") .field("value", self.get()) .finish() } } impl<'a, T, A> OccupiedEntry<'a, T, A> where A: Allocator, { /// Takes the value out of the entry, and returns it along with a /// `VacantEntry` that can be used to insert another value with the same /// hash as the one that was just removed. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::Entry; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<&str> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// // The table is empty /// assert!(table.is_empty() && table.capacity() == 0); /// /// table.insert_unique(hasher(&"poneyland"), "poneyland", hasher); /// let capacity_before_remove = table.capacity(); /// /// if let Entry::Occupied(o) = table.entry(hasher(&"poneyland"), |&x| x == "poneyland", hasher) { /// assert_eq!(o.remove().0, "poneyland"); /// } /// /// assert!(table /// .find(hasher(&"poneyland"), |&x| x == "poneyland") /// .is_none()); /// // Now table hold none elements but capacity is equal to the old one /// assert!(table.len() == 0 && table.capacity() == capacity_before_remove); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` #[cfg_attr(feature = "inline-more", inline)] pub fn remove(self) -> (T, VacantEntry<'a, T, A>) { let (val, slot) = unsafe { self.table.raw.remove(self.bucket) }; ( val, VacantEntry { hash: self.hash, insert_slot: slot, table: self.table, }, ) } /// Gets a reference to the value in the entry. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::Entry; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<&str> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&"poneyland"), "poneyland", hasher); /// /// match table.entry(hasher(&"poneyland"), |&x| x == "poneyland", hasher) { /// Entry::Vacant(_) => panic!(), /// Entry::Occupied(entry) => assert_eq!(entry.get(), &"poneyland"), /// } /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` #[inline] pub fn get(&self) -> &T { unsafe { self.bucket.as_ref() } } /// Gets a mutable reference to the value in the entry. /// /// If you need a reference to the `OccupiedEntry` which may outlive the /// destruction of the `Entry` value, see [`into_mut`]. /// /// [`into_mut`]: #method.into_mut /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::Entry; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<(&str, u32)> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&"poneyland"), ("poneyland", 12), |(k, _)| hasher(&k)); /// /// assert_eq!( /// table.find(hasher(&"poneyland"), |&(x, _)| x == "poneyland",), /// Some(&("poneyland", 12)) /// ); /// /// if let Entry::Occupied(mut o) = table.entry( /// hasher(&"poneyland"), /// |&(x, _)| x == "poneyland", /// |(k, _)| hasher(&k), /// ) { /// o.get_mut().1 += 10; /// assert_eq!(o.get().1, 22); /// /// // We can use the same Entry multiple times. /// o.get_mut().1 += 2; /// } /// /// assert_eq!( /// table.find(hasher(&"poneyland"), |&(x, _)| x == "poneyland",), /// Some(&("poneyland", 24)) /// ); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` #[inline] pub fn get_mut(&mut self) -> &mut T { unsafe { self.bucket.as_mut() } } /// Converts the OccupiedEntry into a mutable reference to the value in the entry /// with a lifetime bound to the table itself. /// /// If you need multiple references to the `OccupiedEntry`, see [`get_mut`]. /// /// [`get_mut`]: #method.get_mut /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::Entry; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<(&str, u32)> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// table.insert_unique(hasher(&"poneyland"), ("poneyland", 12), |(k, _)| hasher(&k)); /// /// assert_eq!( /// table.find(hasher(&"poneyland"), |&(x, _)| x == "poneyland",), /// Some(&("poneyland", 12)) /// ); /// /// let value: &mut (&str, u32); /// match table.entry( /// hasher(&"poneyland"), /// |&(x, _)| x == "poneyland", /// |(k, _)| hasher(&k), /// ) { /// Entry::Occupied(entry) => value = entry.into_mut(), /// Entry::Vacant(_) => panic!(), /// } /// value.1 += 10; /// /// assert_eq!( /// table.find(hasher(&"poneyland"), |&(x, _)| x == "poneyland",), /// Some(&("poneyland", 22)) /// ); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub fn into_mut(self) -> &'a mut T { unsafe { self.bucket.as_mut() } } /// Converts the OccupiedEntry into a mutable reference to the underlying /// table. pub fn into_table(self) -> &'a mut HashTable { self.table } } /// A view into a vacant entry in a `HashTable`. /// It is part of the [`Entry`] enum. /// /// [`Entry`]: enum.Entry.html /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::{Entry, HashTable, VacantEntry}; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<&str> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// let entry_v: VacantEntry<_, _> = match table.entry(hasher(&"a"), |&x| x == "a", hasher) { /// Entry::Vacant(view) => view, /// Entry::Occupied(_) => unreachable!(), /// }; /// entry_v.insert("a"); /// assert!(table.find(hasher(&"a"), |&x| x == "a").is_some() && table.len() == 1); /// /// // Nonexistent key (insert) /// match table.entry(hasher(&"b"), |&x| x == "b", hasher) { /// Entry::Vacant(view) => { /// view.insert("b"); /// } /// Entry::Occupied(_) => unreachable!(), /// } /// assert!(table.find(hasher(&"b"), |&x| x == "b").is_some() && table.len() == 2); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub struct VacantEntry<'a, T, A = Global> where A: Allocator, { hash: u64, insert_slot: InsertSlot, table: &'a mut HashTable, } impl fmt::Debug for VacantEntry<'_, T, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("VacantEntry") } } impl<'a, T, A> VacantEntry<'a, T, A> where A: Allocator, { /// Inserts a new element into the table with the hash that was used to /// obtain the `VacantEntry`. /// /// An `OccupiedEntry` is returned for the newly inserted element. /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::Entry; /// use hashbrown::HashTable; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<&str> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// if let Entry::Vacant(o) = table.entry(hasher(&"poneyland"), |&x| x == "poneyland", hasher) { /// o.insert("poneyland"); /// } /// assert_eq!( /// table.find(hasher(&"poneyland"), |&x| x == "poneyland"), /// Some(&"poneyland") /// ); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` #[inline] pub fn insert(self, value: T) -> OccupiedEntry<'a, T, A> { let bucket = unsafe { self.table .raw .insert_in_slot(self.hash, self.insert_slot, value) }; OccupiedEntry { hash: self.hash, bucket, table: self.table, } } /// Converts the VacantEntry into a mutable reference to the underlying /// table. pub fn into_table(self) -> &'a mut HashTable { self.table } } /// Type representing the absence of an entry, as returned by [`HashTable::find_entry`]. /// /// This type only exists due to [limitations] in Rust's NLL borrow checker. In /// the future, `find_entry` will return an `Option` and this /// type will be removed. /// /// [limitations]: https://smallcultfollowing.com/babysteps/blog/2018/06/15/mir-based-borrow-check-nll-status-update/#polonius /// /// # Examples /// /// ``` /// # #[cfg(feature = "nightly")] /// # fn test() { /// use ahash::AHasher; /// use hashbrown::hash_table::{AbsentEntry, Entry, HashTable}; /// use std::hash::{BuildHasher, BuildHasherDefault}; /// /// let mut table: HashTable<&str> = HashTable::new(); /// let hasher = BuildHasherDefault::::default(); /// let hasher = |val: &_| hasher.hash_one(val); /// /// let entry_v: AbsentEntry<_, _> = table.find_entry(hasher(&"a"), |&x| x == "a").unwrap_err(); /// entry_v /// .into_table() /// .insert_unique(hasher(&"a"), "a", hasher); /// assert!(table.find(hasher(&"a"), |&x| x == "a").is_some() && table.len() == 1); /// /// // Nonexistent key (insert) /// match table.entry(hasher(&"b"), |&x| x == "b", hasher) { /// Entry::Vacant(view) => { /// view.insert("b"); /// } /// Entry::Occupied(_) => unreachable!(), /// } /// assert!(table.find(hasher(&"b"), |&x| x == "b").is_some() && table.len() == 2); /// # } /// # fn main() { /// # #[cfg(feature = "nightly")] /// # test() /// # } /// ``` pub struct AbsentEntry<'a, T, A = Global> where A: Allocator, { table: &'a mut HashTable, } impl fmt::Debug for AbsentEntry<'_, T, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("AbsentEntry") } } impl<'a, T, A> AbsentEntry<'a, T, A> where A: Allocator, { /// Converts the AbsentEntry into a mutable reference to the underlying /// table. pub fn into_table(self) -> &'a mut HashTable { self.table } } /// An iterator over the entries of a `HashTable` in arbitrary order. /// The iterator element type is `&'a T`. /// /// This `struct` is created by the [`iter`] method on [`HashTable`]. See its /// documentation for more. /// /// [`iter`]: struct.HashTable.html#method.iter /// [`HashTable`]: struct.HashTable.html pub struct Iter<'a, T> { inner: RawIter, marker: PhantomData<&'a T>, } impl<'a, T> Iterator for Iter<'a, T> { type Item = &'a T; fn next(&mut self) -> Option { // Avoid `Option::map` because it bloats LLVM IR. match self.inner.next() { Some(bucket) => Some(unsafe { bucket.as_ref() }), None => None, } } fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner .fold(init, |acc, bucket| unsafe { f(acc, bucket.as_ref()) }) } } impl ExactSizeIterator for Iter<'_, T> { fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for Iter<'_, T> {} /// A mutable iterator over the entries of a `HashTable` in arbitrary order. /// The iterator element type is `&'a mut T`. /// /// This `struct` is created by the [`iter_mut`] method on [`HashTable`]. See its /// documentation for more. /// /// [`iter_mut`]: struct.HashTable.html#method.iter_mut /// [`HashTable`]: struct.HashTable.html pub struct IterMut<'a, T> { inner: RawIter, marker: PhantomData<&'a mut T>, } impl<'a, T> Iterator for IterMut<'a, T> { type Item = &'a mut T; fn next(&mut self) -> Option { // Avoid `Option::map` because it bloats LLVM IR. match self.inner.next() { Some(bucket) => Some(unsafe { bucket.as_mut() }), None => None, } } fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } fn fold(self, init: B, mut f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner .fold(init, |acc, bucket| unsafe { f(acc, bucket.as_mut()) }) } } impl ExactSizeIterator for IterMut<'_, T> { fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for IterMut<'_, T> {} /// An owning iterator over the entries of a `HashTable` in arbitrary order. /// The iterator element type is `T`. /// /// This `struct` is created by the [`into_iter`] method on [`HashTable`] /// (provided by the [`IntoIterator`] trait). See its documentation for more. /// The table cannot be used after calling that method. /// /// [`into_iter`]: struct.HashTable.html#method.into_iter /// [`HashTable`]: struct.HashTable.html /// [`IntoIterator`]: https://doc.rust-lang.org/core/iter/trait.IntoIterator.html pub struct IntoIter where A: Allocator, { inner: RawIntoIter, } impl Iterator for IntoIter where A: Allocator, { type Item = T; fn next(&mut self) -> Option { self.inner.next() } fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } fn fold(self, init: B, f: F) -> B where Self: Sized, F: FnMut(B, Self::Item) -> B, { self.inner.fold(init, f) } } impl ExactSizeIterator for IntoIter where A: Allocator, { fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for IntoIter where A: Allocator {} /// A draining iterator over the items of a `HashTable`. /// /// This `struct` is created by the [`drain`] method on [`HashTable`]. /// See its documentation for more. /// /// [`HashTable`]: struct.HashTable.html /// [`drain`]: struct.HashTable.html#method.drain pub struct Drain<'a, T, A: Allocator = Global> { inner: RawDrain<'a, T, A>, } impl Drain<'_, T, A> { /// Returns a iterator of references over the remaining items. fn iter(&self) -> Iter<'_, T> { Iter { inner: self.inner.iter(), marker: PhantomData, } } } impl Iterator for Drain<'_, T, A> { type Item = T; fn next(&mut self) -> Option { self.inner.next() } fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } } impl ExactSizeIterator for Drain<'_, T, A> { fn len(&self) -> usize { self.inner.len() } } impl FusedIterator for Drain<'_, T, A> {} impl fmt::Debug for Drain<'_, T, A> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_list().entries(self.iter()).finish() } } /// A draining iterator over entries of a `HashTable` which don't satisfy the predicate `f`. /// /// This `struct` is created by [`HashTable::extract_if`]. See its /// documentation for more. #[must_use = "Iterators are lazy unless consumed"] pub struct ExtractIf<'a, T, F, A: Allocator = Global> where F: FnMut(&mut T) -> bool, { f: F, inner: RawExtractIf<'a, T, A>, } impl Iterator for ExtractIf<'_, T, F, A> where F: FnMut(&mut T) -> bool, { type Item = T; #[inline] fn next(&mut self) -> Option { self.inner.next(|val| (self.f)(val)) } #[inline] fn size_hint(&self) -> (usize, Option) { (0, self.inner.iter.size_hint().1) } } impl FusedIterator for ExtractIf<'_, T, F, A> where F: FnMut(&mut T) -> bool {} hashbrown-0.14.5/tests/equivalent_trait.rs000064400000000000000000000021171046102023000167770ustar 00000000000000use hashbrown::Equivalent; use hashbrown::HashMap; use std::hash::Hash; #[derive(Debug, Hash)] pub struct Pair(pub A, pub B); impl PartialEq<(A, B)> for Pair where C: PartialEq, D: PartialEq, { fn eq(&self, rhs: &(A, B)) -> bool { self.0 == rhs.0 && self.1 == rhs.1 } } impl Equivalent for Pair where Pair: PartialEq, A: Hash + Eq, B: Hash + Eq, { fn equivalent(&self, other: &X) -> bool { *self == *other } } #[test] fn test_lookup() { let s = String::from; let mut map = HashMap::new(); map.insert((s("a"), s("b")), 1); map.insert((s("a"), s("x")), 2); assert!(map.contains_key(&Pair("a", "b"))); assert!(!map.contains_key(&Pair("b", "a"))); } #[test] fn test_string_str() { let s = String::from; let mut map = HashMap::new(); map.insert(s("a"), 1); map.insert(s("b"), 2); map.insert(s("x"), 3); map.insert(s("y"), 4); assert!(map.contains_key("a")); assert!(!map.contains_key("z")); assert_eq!(map.remove("b"), Some(2)); } hashbrown-0.14.5/tests/hasher.rs000064400000000000000000000025731046102023000146770ustar 00000000000000//! Sanity check that alternate hashers work correctly. #![cfg(not(miri))] // FIXME: takes too long use hashbrown::HashSet; use std::hash::{BuildHasher, BuildHasherDefault, Hasher}; fn check() { let range = 0..1_000; let mut set = HashSet::::default(); set.extend(range.clone()); assert!(!set.contains(&i32::min_value())); assert!(!set.contains(&(range.start - 1))); for i in range.clone() { assert!(set.contains(&i)); } assert!(!set.contains(&range.end)); assert!(!set.contains(&i32::max_value())); } /// Use hashbrown's default hasher. #[test] fn default() { check::(); } /// Use std's default hasher. #[test] fn random_state() { check::(); } /// Use a constant 0 hash. #[test] fn zero() { #[derive(Default)] struct ZeroHasher; impl Hasher for ZeroHasher { fn finish(&self) -> u64 { 0 } fn write(&mut self, _: &[u8]) {} } check::>(); } /// Use a constant maximum hash. #[test] fn max() { #[derive(Default)] struct MaxHasher; impl Hasher for MaxHasher { fn finish(&self) -> u64 { u64::max_value() } fn write(&mut self, _: &[u8]) {} } check::>(); } hashbrown-0.14.5/tests/raw.rs000064400000000000000000000005331046102023000142100ustar 00000000000000#![cfg(feature = "raw")] use hashbrown::raw::RawTable; use std::mem; #[test] fn test_allocation_info() { assert_eq!(RawTable::<()>::new().allocation_info().1.size(), 0); assert_eq!(RawTable::::new().allocation_info().1.size(), 0); assert!(RawTable::::with_capacity(1).allocation_info().1.size() > mem::size_of::()); } hashbrown-0.14.5/tests/rayon.rs000064400000000000000000000352121046102023000145510ustar 00000000000000#![cfg(feature = "rayon")] #[macro_use] extern crate lazy_static; use hashbrown::{HashMap, HashSet}; use rayon::iter::{ IntoParallelIterator, IntoParallelRefIterator, IntoParallelRefMutIterator, ParallelExtend, ParallelIterator, }; macro_rules! assert_eq3 { ($e1:expr, $e2:expr, $e3:expr) => {{ assert_eq!($e1, $e2); assert_eq!($e1, $e3); assert_eq!($e2, $e3); }}; } lazy_static! { static ref MAP_EMPTY: HashMap = HashMap::new(); static ref MAP: HashMap = { let mut m = HashMap::new(); m.insert('b', 20); m.insert('a', 10); m.insert('c', 30); m.insert('e', 50); m.insert('f', 60); m.insert('d', 40); m }; } #[test] fn map_seq_par_equivalence_iter_empty() { let vec_seq = MAP_EMPTY.iter().collect::>(); let vec_par = MAP_EMPTY.par_iter().collect::>(); assert_eq3!(vec_seq, vec_par, []); } #[test] fn map_seq_par_equivalence_iter() { let mut vec_seq = MAP.iter().collect::>(); let mut vec_par = MAP.par_iter().collect::>(); assert_eq!(vec_seq, vec_par); // Do not depend on the exact order of values let expected_sorted = [ (&'a', &10), (&'b', &20), (&'c', &30), (&'d', &40), (&'e', &50), (&'f', &60), ]; vec_seq.sort_unstable(); vec_par.sort_unstable(); assert_eq3!(vec_seq, vec_par, expected_sorted); } #[test] fn map_seq_par_equivalence_keys_empty() { let vec_seq = MAP_EMPTY.keys().collect::>(); let vec_par = MAP_EMPTY.par_keys().collect::>(); let expected: [&char; 0] = []; assert_eq3!(vec_seq, vec_par, expected); } #[test] fn map_seq_par_equivalence_keys() { let mut vec_seq = MAP.keys().collect::>(); let mut vec_par = MAP.par_keys().collect::>(); assert_eq!(vec_seq, vec_par); // Do not depend on the exact order of values let expected_sorted = [&'a', &'b', &'c', &'d', &'e', &'f']; vec_seq.sort_unstable(); vec_par.sort_unstable(); assert_eq3!(vec_seq, vec_par, expected_sorted); } #[test] fn map_seq_par_equivalence_values_empty() { let vec_seq = MAP_EMPTY.values().collect::>(); let vec_par = MAP_EMPTY.par_values().collect::>(); let expected: [&u32; 0] = []; assert_eq3!(vec_seq, vec_par, expected); } #[test] fn map_seq_par_equivalence_values() { let mut vec_seq = MAP.values().collect::>(); let mut vec_par = MAP.par_values().collect::>(); assert_eq!(vec_seq, vec_par); // Do not depend on the exact order of values let expected_sorted = [&10, &20, &30, &40, &50, &60]; vec_seq.sort_unstable(); vec_par.sort_unstable(); assert_eq3!(vec_seq, vec_par, expected_sorted); } #[test] fn map_seq_par_equivalence_iter_mut_empty() { let mut map1 = MAP_EMPTY.clone(); let mut map2 = MAP_EMPTY.clone(); let vec_seq = map1.iter_mut().collect::>(); let vec_par = map2.par_iter_mut().collect::>(); assert_eq3!(vec_seq, vec_par, []); } #[test] fn map_seq_par_equivalence_iter_mut() { let mut map1 = MAP.clone(); let mut map2 = MAP.clone(); let mut vec_seq = map1.iter_mut().collect::>(); let mut vec_par = map2.par_iter_mut().collect::>(); assert_eq!(vec_seq, vec_par); // Do not depend on the exact order of values let expected_sorted = [ (&'a', &mut 10), (&'b', &mut 20), (&'c', &mut 30), (&'d', &mut 40), (&'e', &mut 50), (&'f', &mut 60), ]; vec_seq.sort_unstable(); vec_par.sort_unstable(); assert_eq3!(vec_seq, vec_par, expected_sorted); } #[test] fn map_seq_par_equivalence_values_mut_empty() { let mut map1 = MAP_EMPTY.clone(); let mut map2 = MAP_EMPTY.clone(); let vec_seq = map1.values_mut().collect::>(); let vec_par = map2.par_values_mut().collect::>(); let expected: [&u32; 0] = []; assert_eq3!(vec_seq, vec_par, expected); } #[test] fn map_seq_par_equivalence_values_mut() { let mut map1 = MAP.clone(); let mut map2 = MAP.clone(); let mut vec_seq = map1.values_mut().collect::>(); let mut vec_par = map2.par_values_mut().collect::>(); assert_eq!(vec_seq, vec_par); // Do not depend on the exact order of values let expected_sorted = [&mut 10, &mut 20, &mut 30, &mut 40, &mut 50, &mut 60]; vec_seq.sort_unstable(); vec_par.sort_unstable(); assert_eq3!(vec_seq, vec_par, expected_sorted); } #[test] fn map_seq_par_equivalence_into_iter_empty() { let vec_seq = MAP_EMPTY.clone().into_iter().collect::>(); let vec_par = MAP_EMPTY.clone().into_par_iter().collect::>(); assert_eq3!(vec_seq, vec_par, []); } #[test] fn map_seq_par_equivalence_into_iter() { let mut vec_seq = MAP.clone().into_iter().collect::>(); let mut vec_par = MAP.clone().into_par_iter().collect::>(); assert_eq!(vec_seq, vec_par); // Do not depend on the exact order of values let expected_sorted = [ ('a', 10), ('b', 20), ('c', 30), ('d', 40), ('e', 50), ('f', 60), ]; vec_seq.sort_unstable(); vec_par.sort_unstable(); assert_eq3!(vec_seq, vec_par, expected_sorted); } lazy_static! { static ref MAP_VEC_EMPTY: Vec<(char, u32)> = vec![]; static ref MAP_VEC: Vec<(char, u32)> = vec![ ('b', 20), ('a', 10), ('c', 30), ('e', 50), ('f', 60), ('d', 40), ]; } #[test] fn map_seq_par_equivalence_collect_empty() { let map_expected = MAP_EMPTY.clone(); let map_seq = MAP_VEC_EMPTY.clone().into_iter().collect::>(); let map_par = MAP_VEC_EMPTY .clone() .into_par_iter() .collect::>(); assert_eq!(map_seq, map_par); assert_eq!(map_seq, map_expected); assert_eq!(map_par, map_expected); } #[test] fn map_seq_par_equivalence_collect() { let map_expected = MAP.clone(); let map_seq = MAP_VEC.clone().into_iter().collect::>(); let map_par = MAP_VEC.clone().into_par_iter().collect::>(); assert_eq!(map_seq, map_par); assert_eq!(map_seq, map_expected); assert_eq!(map_par, map_expected); } lazy_static! { static ref MAP_EXISTING_EMPTY: HashMap = HashMap::new(); static ref MAP_EXISTING: HashMap = { let mut m = HashMap::new(); m.insert('b', 20); m.insert('a', 10); m }; static ref MAP_EXTENSION_EMPTY: Vec<(char, u32)> = vec![]; static ref MAP_EXTENSION: Vec<(char, u32)> = vec![('c', 30), ('e', 50), ('f', 60), ('d', 40),]; } #[test] fn map_seq_par_equivalence_existing_empty_extend_empty() { let expected = HashMap::new(); let mut map_seq = MAP_EXISTING_EMPTY.clone(); let mut map_par = MAP_EXISTING_EMPTY.clone(); map_seq.extend(MAP_EXTENSION_EMPTY.iter().copied()); map_par.par_extend(MAP_EXTENSION_EMPTY.par_iter().copied()); assert_eq3!(map_seq, map_par, expected); } #[test] fn map_seq_par_equivalence_existing_empty_extend() { let expected = MAP_EXTENSION.iter().copied().collect::>(); let mut map_seq = MAP_EXISTING_EMPTY.clone(); let mut map_par = MAP_EXISTING_EMPTY.clone(); map_seq.extend(MAP_EXTENSION.iter().copied()); map_par.par_extend(MAP_EXTENSION.par_iter().copied()); assert_eq3!(map_seq, map_par, expected); } #[test] fn map_seq_par_equivalence_existing_extend_empty() { let expected = MAP_EXISTING.clone(); let mut map_seq = MAP_EXISTING.clone(); let mut map_par = MAP_EXISTING.clone(); map_seq.extend(MAP_EXTENSION_EMPTY.iter().copied()); map_par.par_extend(MAP_EXTENSION_EMPTY.par_iter().copied()); assert_eq3!(map_seq, map_par, expected); } #[test] fn map_seq_par_equivalence_existing_extend() { let expected = MAP.clone(); let mut map_seq = MAP_EXISTING.clone(); let mut map_par = MAP_EXISTING.clone(); map_seq.extend(MAP_EXTENSION.iter().copied()); map_par.par_extend(MAP_EXTENSION.par_iter().copied()); assert_eq3!(map_seq, map_par, expected); } lazy_static! { static ref SET_EMPTY: HashSet = HashSet::new(); static ref SET: HashSet = { let mut s = HashSet::new(); s.insert('b'); s.insert('a'); s.insert('c'); s.insert('e'); s.insert('f'); s.insert('d'); s }; } #[test] fn set_seq_par_equivalence_iter_empty() { let vec_seq = SET_EMPTY.iter().collect::>(); let vec_par = SET_EMPTY.par_iter().collect::>(); let expected: [&char; 0] = []; assert_eq3!(vec_seq, vec_par, expected); } #[test] fn set_seq_par_equivalence_iter() { let mut vec_seq = SET.iter().collect::>(); let mut vec_par = SET.par_iter().collect::>(); assert_eq!(vec_seq, vec_par); // Do not depend on the exact order of values let expected_sorted = [&'a', &'b', &'c', &'d', &'e', &'f']; vec_seq.sort_unstable(); vec_par.sort_unstable(); assert_eq3!(vec_seq, vec_par, expected_sorted); } #[test] fn set_seq_par_equivalence_into_iter_empty() { let vec_seq = SET_EMPTY.clone().into_iter().collect::>(); let vec_par = SET_EMPTY.clone().into_par_iter().collect::>(); // Work around type inference failure introduced by rend dev-dependency. let empty: [char; 0] = []; assert_eq3!(vec_seq, vec_par, empty); } #[test] fn set_seq_par_equivalence_into_iter() { let mut vec_seq = SET.clone().into_iter().collect::>(); let mut vec_par = SET.clone().into_par_iter().collect::>(); assert_eq!(vec_seq, vec_par); // Do not depend on the exact order of values let expected_sorted = ['a', 'b', 'c', 'd', 'e', 'f']; vec_seq.sort_unstable(); vec_par.sort_unstable(); assert_eq3!(vec_seq, vec_par, expected_sorted); } lazy_static! { static ref SET_VEC_EMPTY: Vec = vec![]; static ref SET_VEC: Vec = vec!['b', 'a', 'c', 'e', 'f', 'd',]; } #[test] fn set_seq_par_equivalence_collect_empty() { let set_expected = SET_EMPTY.clone(); let set_seq = SET_VEC_EMPTY.clone().into_iter().collect::>(); let set_par = SET_VEC_EMPTY .clone() .into_par_iter() .collect::>(); assert_eq!(set_seq, set_par); assert_eq!(set_seq, set_expected); assert_eq!(set_par, set_expected); } #[test] fn set_seq_par_equivalence_collect() { let set_expected = SET.clone(); let set_seq = SET_VEC.clone().into_iter().collect::>(); let set_par = SET_VEC.clone().into_par_iter().collect::>(); assert_eq!(set_seq, set_par); assert_eq!(set_seq, set_expected); assert_eq!(set_par, set_expected); } lazy_static! { static ref SET_EXISTING_EMPTY: HashSet = HashSet::new(); static ref SET_EXISTING: HashSet = { let mut s = HashSet::new(); s.insert('b'); s.insert('a'); s }; static ref SET_EXTENSION_EMPTY: Vec = vec![]; static ref SET_EXTENSION: Vec = vec!['c', 'e', 'f', 'd',]; } #[test] fn set_seq_par_equivalence_existing_empty_extend_empty() { let expected = HashSet::new(); let mut set_seq = SET_EXISTING_EMPTY.clone(); let mut set_par = SET_EXISTING_EMPTY.clone(); set_seq.extend(SET_EXTENSION_EMPTY.iter().copied()); set_par.par_extend(SET_EXTENSION_EMPTY.par_iter().copied()); assert_eq3!(set_seq, set_par, expected); } #[test] fn set_seq_par_equivalence_existing_empty_extend() { let expected = SET_EXTENSION.iter().copied().collect::>(); let mut set_seq = SET_EXISTING_EMPTY.clone(); let mut set_par = SET_EXISTING_EMPTY.clone(); set_seq.extend(SET_EXTENSION.iter().copied()); set_par.par_extend(SET_EXTENSION.par_iter().copied()); assert_eq3!(set_seq, set_par, expected); } #[test] fn set_seq_par_equivalence_existing_extend_empty() { let expected = SET_EXISTING.clone(); let mut set_seq = SET_EXISTING.clone(); let mut set_par = SET_EXISTING.clone(); set_seq.extend(SET_EXTENSION_EMPTY.iter().copied()); set_par.par_extend(SET_EXTENSION_EMPTY.par_iter().copied()); assert_eq3!(set_seq, set_par, expected); } #[test] fn set_seq_par_equivalence_existing_extend() { let expected = SET.clone(); let mut set_seq = SET_EXISTING.clone(); let mut set_par = SET_EXISTING.clone(); set_seq.extend(SET_EXTENSION.iter().copied()); set_par.par_extend(SET_EXTENSION.par_iter().copied()); assert_eq3!(set_seq, set_par, expected); } lazy_static! { static ref SET_A: HashSet = ['a', 'b', 'c', 'd'].iter().copied().collect(); static ref SET_B: HashSet = ['a', 'b', 'e', 'f'].iter().copied().collect(); static ref SET_DIFF_AB: HashSet = ['c', 'd'].iter().copied().collect(); static ref SET_DIFF_BA: HashSet = ['e', 'f'].iter().copied().collect(); static ref SET_SYMM_DIFF_AB: HashSet = ['c', 'd', 'e', 'f'].iter().copied().collect(); static ref SET_INTERSECTION_AB: HashSet = ['a', 'b'].iter().copied().collect(); static ref SET_UNION_AB: HashSet = ['a', 'b', 'c', 'd', 'e', 'f'].iter().copied().collect(); } #[test] fn set_seq_par_equivalence_difference() { let diff_ab_seq = SET_A.difference(&*SET_B).copied().collect::>(); let diff_ab_par = SET_A .par_difference(&*SET_B) .copied() .collect::>(); assert_eq3!(diff_ab_seq, diff_ab_par, *SET_DIFF_AB); let diff_ba_seq = SET_B.difference(&*SET_A).copied().collect::>(); let diff_ba_par = SET_B .par_difference(&*SET_A) .copied() .collect::>(); assert_eq3!(diff_ba_seq, diff_ba_par, *SET_DIFF_BA); } #[test] fn set_seq_par_equivalence_symmetric_difference() { let symm_diff_ab_seq = SET_A .symmetric_difference(&*SET_B) .copied() .collect::>(); let symm_diff_ab_par = SET_A .par_symmetric_difference(&*SET_B) .copied() .collect::>(); assert_eq3!(symm_diff_ab_seq, symm_diff_ab_par, *SET_SYMM_DIFF_AB); } #[test] fn set_seq_par_equivalence_intersection() { let intersection_ab_seq = SET_A.intersection(&*SET_B).copied().collect::>(); let intersection_ab_par = SET_A .par_intersection(&*SET_B) .copied() .collect::>(); assert_eq3!( intersection_ab_seq, intersection_ab_par, *SET_INTERSECTION_AB ); } #[test] fn set_seq_par_equivalence_union() { let union_ab_seq = SET_A.union(&*SET_B).copied().collect::>(); let union_ab_par = SET_A.par_union(&*SET_B).copied().collect::>(); assert_eq3!(union_ab_seq, union_ab_par, *SET_UNION_AB); } hashbrown-0.14.5/tests/serde.rs000064400000000000000000000027171046102023000145270ustar 00000000000000#![cfg(feature = "serde")] use core::hash::BuildHasherDefault; use fnv::FnvHasher; use hashbrown::{HashMap, HashSet}; use serde_test::{assert_tokens, Token}; // We use FnvHash for this test because we rely on the ordering type FnvHashMap = HashMap>; type FnvHashSet = HashSet>; #[test] fn map_serde_tokens_empty() { let map = FnvHashMap::::default(); assert_tokens(&map, &[Token::Map { len: Some(0) }, Token::MapEnd]); } #[test] fn map_serde_tokens() { let mut map = FnvHashMap::default(); map.insert('b', 20); map.insert('a', 10); map.insert('c', 30); assert_tokens( &map, &[ Token::Map { len: Some(3) }, Token::Char('a'), Token::I32(10), Token::Char('c'), Token::I32(30), Token::Char('b'), Token::I32(20), Token::MapEnd, ], ); } #[test] fn set_serde_tokens_empty() { let set = FnvHashSet::::default(); assert_tokens(&set, &[Token::Seq { len: Some(0) }, Token::SeqEnd]); } #[test] fn set_serde_tokens() { let mut set = FnvHashSet::default(); set.insert(20); set.insert(10); set.insert(30); assert_tokens( &set, &[ Token::Seq { len: Some(3) }, Token::I32(30), Token::I32(20), Token::I32(10), Token::SeqEnd, ], ); } hashbrown-0.14.5/tests/set.rs000064400000000000000000000016761046102023000142230ustar 00000000000000#![cfg(not(miri))] // FIXME: takes too long use hashbrown::HashSet; use rand::{distributions::Alphanumeric, rngs::SmallRng, Rng, SeedableRng}; use std::iter; #[test] fn test_hashset_insert_remove() { let mut m: HashSet> = HashSet::new(); let seed = u64::from_le_bytes(*b"testseed"); let rng = &mut SmallRng::seed_from_u64(seed); let tx: Vec> = iter::repeat_with(|| { rng.sample_iter(&Alphanumeric) .take(32) .map(char::from) .collect() }) .take(4096) .collect(); // more readable with explicit `true` / `false` #[allow(clippy::bool_assert_comparison)] for _ in 0..32 { for x in &tx { assert_eq!(m.contains(x), false); assert_eq!(m.insert(x.clone()), true); } for (i, x) in tx.iter().enumerate() { println!("removing {i} {x:?}"); assert_eq!(m.remove(x), true); } } }