Introduce Entry API (#31)

Co-authored-by: John-John Tedro <[email protected]>

.github/workflows/ci.yml

@@ -35,9 +35,9 @@ jobs:
     - uses: actions-rs/toolchain@v1
       with: { toolchain: beta, override: true, profile: minimal }
     # Test all relevant feature combos:
-    # features: std, map, serde
+    # features: std, map, entry, serde
     - run: cargo test --all-features
-    # features: -std, -map, -serde
+    # features: -std, -map, -entry, -serde
     - run: cargo test --no-default-features
-    # features: -std, -map, serde
+    # features: -std, -map, -entry, serde
     - run: cargo test --no-default-features --features serde

.gitignore

@@ -2,3 +2,4 @@ Cargo.lock
 /target
 /fixed-map-derive/target
 **/*.rs.bk
+.vscode

Cargo.toml

@@ -17,9 +17,10 @@ categories = ["data-structures"]
 all-features = true
 
 [features]
-default = ["map", "std"]
+default = ["map", "std", "entry"]
 std = ["serde?/std"]
 map = ["hashbrown", "std"]
+entry = ["fixed-map-derive/entry"]
 
 [dependencies]
 fixed-map-derive = { version = "0.8.0-alpha.2", path = "fixed-map-derive" }
@@ -39,4 +40,6 @@ name = "simple"
 harness = false
 
 [workspace]
-members = ["fixed-map-derive"]
+members = [
+  "fixed-map-derive"
+]

README.md

@@ -63,11 +63,12 @@ assert!(!set.contains(Key::East));
 
 The following features are available:
 
-* `std` - Disabling this feature enables causes this crate to be no-std.
+* `std` - Disabling this feature causes this crate to be no-std.
   This means that dynamic types cannot be used in keys, like ones enabled by
   the `map` feature (default).
 * `map` - Causes [`Storage`] to be implemented by dynamic types such as
   `&'static str` or `u32`. These are backed by a `hashbrown` (default).
+* `entry` - Enables an [`entry`] API similar to that found on [`HashMap`].
 * `serde` - Causes [`Map`] and [`Set`] to implement [`Serialize`] and
   [`Deserialize`] if it's implemented by the key and value.
 
@@ -176,6 +177,11 @@ if let Some(item) = map.get(Dir::North) {
 }
 ```
 
+## Unsafe use
+The Entry API uses `unwrap_unchecked` to obtain
+mutable references to the inner value of `Some`s,
+and to skip `drop` when overwriting `None`s.
+
 <br>
 
 ## Benchmarks
@@ -263,6 +269,8 @@ ls target/release/examples/
 [`Key` derive]: https://docs.rs/fixed-map/latest/fixed_map/derive.Key.html
 [`Key`]: https://docs.rs/fixed-map/latest/fixed_map/derive.Key.html
 [`Map`]: https://docs.rs/fixed-map/latest/fixed_map/map/struct.Map.html
+[`entry`]: https://docs.rs/fixed-map/latest/fixed_map/map/struct.Map.html#method.entry
+[`HashMap`]: https://doc.rust-lang.org/stable/std/collections/hash_map/struct.HashMap.html#method.entry
 [`Serialize`]: https://docs.rs/serde/1/serde/trait.Serialize.html
 [`Set`]: https://docs.rs/fixed-map/latest/fixed_map/set/struct.Set.html
 [`Storage`]: https://docs.rs/fixed-map/latest/fixed_map/storage/trait.Storage.html

fixed-map-derive/Cargo.toml

@@ -16,6 +16,9 @@ license = "MIT/Apache-2.0"
 keywords = ["container", "data-structure", "map", "no_std"]
 categories = ["data-structures"]
 
+[features]
+entry = ["fixed-map/entry"]
+
 [dependencies]
 syn = "1.0.8"
 quote = "1.0.2"