diff --git a/CHANGELOG.md b/CHANGELOG.md index d4e35bc..dea9cc1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,32 @@ All notable changes to this project will be documented in this file. +## [v0.10.0] - 2022-04-21 + +### Added + +- **`drain`** `DHashMap` method that clears the map, returning all keys-value tuples +as an arbitrary order iterator; +- **`get_mut_keys`** `DHashMap` method that returns a mutable reference to the value corresponding +to the given primary key `(key #1)` and secondary key `(key #2)` if they both exist and refer to +the same value; +- **`remove_keys`** `DHashMap` method that removes element from the map corresponding to the +given primary key `(key #1)` and secondary key `(key #2)` returning the value at the keys if +the keys was previously in the map and refer to the same value; +- Add some clarifications to `capacity`, `len`, `is_empty` methods documentations. + +### Changed + +Nothing + +### Removed + +Nothing + +### Fixed + +Nothing + ## [v0.9.0] - 2022-04-20 ### Added diff --git a/Cargo.toml b/Cargo.toml index b3d9bf5..94c6069 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "double-map" -version = "0.9.0" +version = "0.10.0" authors = ["Alisher Galiev "] description = "A HashMap with double key to single data/value" edition = "2021" diff --git a/README.md b/README.md index 739e56b..d936878 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ interface. Look at [Change log](CHANGELOG.md) for more information. - [x] `iter_mut`: Done since `v0.5.0` - [x] `len`: Done since `v0.1.0` - [x] `is_empty`: Done since `v0.1.0` -- [ ] `drain`: Under development +- [x] `drain`: Done since `v0.10.0` - [ ] `drain_filter`: Under development - [ ] `retain`: Under development - [x] `clear`: Done since `v0.1.0` diff --git a/src/map.rs b/src/map.rs index 4b03266..ae960e2 100644 --- a/src/map.rs +++ b/src/map.rs @@ -1319,7 +1319,7 @@ where /// /// // We remove element with key #1 from the map and get corresponding value /// assert_eq!(map.remove_key1(&1), Some("Eins".to_owned())); - /// // If we try to remove the same element with key #1 twise we get None, + /// // If we try to remove the same element with key #1 twice we get None, /// // because that element was already removed /// assert_eq!(map.remove_key1(&1), None); /// @@ -1381,7 +1381,7 @@ where /// /// // We remove element with key #1 from the map and get corresponding value /// assert_eq!(map.remove_key2(&"One"), Some("Eins".to_owned())); - /// // If we try to remove the same element with key #1 twise we get None, + /// // If we try to remove the same element with key #1 twice we get None, /// // because that element was already removed /// assert_eq!(map.remove_key2(&"One"), None); /// @@ -1408,6 +1408,56 @@ where } } + /// Removes element from the map corresponding to the given primary key `(key #1)` + /// and secondary key `(key #2)` returning the value at the keys if the keys was + /// previously in the map and refer to the same value. 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. + /// + /// # Examples + /// + /// ``` + /// use double_map::{DHashMap, dhashmap}; + /// + /// // We create map with three elements + /// let mut map = dhashmap! { + /// 1, "One" => String::from("Eins"), + /// 2, "Two" => String::from("Zwei"), + /// 3, "Three" => String::from("Drei"), + /// }; + /// + /// // We can see that DHashMap holds three elements + /// assert!(map.len() == 3 && map.capacity() >= 3); + /// + /// // Also we reserve memory for holding additionally at least 20 elements, + /// // so that DHashMap can hold 23 elements or more + /// map.reserve(20); + /// let capacity_before_remove = map.capacity(); + /// + /// // We remove element from the map and get corresponding value + /// assert_eq!(map.remove_keys(&1, &"One"), Some("Eins".to_owned())); + /// // If we try to remove the same element with these keys twice we get None, + /// // because that element was already removed + /// assert_eq!(map.remove_keys(&1, &"One"), None); + /// + /// // We get None if both keys don't exist in the map + /// assert_eq!(map.remove_keys(&4, &"Four"), None); + /// // Also we get None if both keys exist but refer to the different value + /// assert_eq!(map.remove_keys(&2, &"Three"), None); + /// assert_eq!(map.get_key1(&2).unwrap(), "Zwei"); + /// assert_eq!(map.get_key2(&"Three").unwrap(), "Drei"); + /// + /// // Now we remove all elements one by one, and can see that map holds nothing + /// map.remove_keys(&2, &"Two"); + /// map.remove_keys(&3, &"Three"); + /// assert_eq!(map.len(), 0); + /// + /// // But map capacity is equal to the old one and can hold at least 23 elements + /// assert!(map.capacity() == capacity_before_remove && map.capacity() >= 23); + /// ``` #[inline] pub fn remove_keys(&mut self, k1: &Q1, k2: &Q2) -> Option where