document storey::Map

docs-test-gen/Cargo.toml

@@ -29,3 +29,4 @@ serde = "*"
 cw-storey = "*"
 schemars = "0.8.21" # Used in entrypoint example
 thiserror = "1.0.65"
+storey = "*"

src/pages/storey/containers/map.mdx

@@ -5,3 +5,144 @@ tags: ["storey", "containers"]
 import { Callout } from "nextra/components";
 
 # Map
+
+A `Map` is a container that maps keys to instances of another container.
+
+Most commonly, you will use a `Map` to store a list of items. For example, the signature could be a
+`Map<String, Item<String>>` to store a list of signatures for each user. (See the first example.)
+
+## Examples
+
+### Keeping balances
+
+Let's say you want to keep track of the balances of each user. You can do this with a
+`Map<String, Item<Uint128>>`.
+
+```rust template="storage" showLineNumbers {6,8,10,12,14}
+use cw_storey::containers::{Item, Map};
+use cw_storey::CwStorage;
+
+const BALANCES: u8 = 0;
+
+let balances: Map<String, Item<Uint128>> = Map::new(BALANCES);
+let mut cw_storage = CwStorage(&mut storage);
+let mut access = balances.access(&mut cw_storage);
+
+assert_eq!(access.entry("alice").get().unwrap(), None);
+
+access.entry_mut("alice").set(&Uint128::new(1000)).unwrap();
+
+assert_eq!(access.entry("alice").get().unwrap(), Some(Uint128::new(1000)));
+```
+
+- _line 6:_ Here we construct the `Map` facade. The constructor takes a key, which is the prefix of
+  the keys in the underlying storage backend.
+- _line 8:_ The `access` method returns a `MapAccess` entity, which allows manipulating the map.
+- _line 10:_ Here we try to access the balance of `alice`. Since she doesn't have one yet, it
+  returns `None`. The `entry` method returns an `ItemAccess` entity, which allows manipulating the
+  item stored under the key `alice`.
+- _line 12:_ Here we set Alice's balance to `1000`.
+- _line 14:_ We check that the balance is now `1000`.
+
+#### Iterating over the balances
+
+Iterating over the balances is pretty straightforward. The `keys` method returns an iterator over
+the keys, the `values` method returns an iterator over the values, and the `pairs` method returns an
+iterator over both.
+
+```rust template="storage" showLineNumbers {4, 17, 19}
+use cw_storey::containers::{Item, Map};
+use cw_storey::CwStorage;
+
+use storey::containers::IterableAccessor as _;
+
+const BALANCES: u8 = 1;
+
+let balances: Map<String, Item<Uint128>> = Map::new(BALANCES);
+let mut cw_storage = CwStorage(&mut storage);
+let mut access = balances.access(&mut cw_storage);
+
+access.entry_mut("bob").set(&Uint128::new(500)).unwrap();
+access.entry_mut("carol").set(&Uint128::new(1500)).unwrap();
+access.entry_mut("dave").set(&Uint128::new(2000)).unwrap();
+
+assert_eq!(
+    access.pairs().collect::<Result<Vec<_>, _>>().unwrap(),
+    vec![
+        (("bob".to_string(), ()), Uint128::new(500)),
+        (("carol".to_string(), ()), Uint128::new(1500)),
+        (("dave".to_string(), ()), Uint128::new(2000)),
+    ]
+);
+
+assert_eq!(
+    access.keys().collect::<Result<Vec<_>, _>>().unwrap(),
+    vec![("bob".to_string(), ()), ("carol".to_string(), ()), ("dave".to_string(), ())]
+);
+
+assert_eq!(
+    access.values().collect::<Result<Vec<_>, _>>().unwrap(),
+    vec![Uint128::new(500), Uint128::new(1500), Uint128::new(2000)]
+);
+```
+
+- _line 4:_ Here we import the `IterableAccessor` trait. This trait provides unbounded iteration.
+- _line 17:_ The `pairs` method returns an iterator over the key-value pairs.
+- _line 19:_ Notice the key type is `(String, ())`. This is likely to become just `String` in the
+  future. For now, consider this a quirk of the design. This will make more sense once you get to
+  composite maps.
+
+### Keeping balances with composition
+
+Alright, let's say this time you'd also like to keep track of the balances of each user, but each
+can have multiple different tokens. This is where composition comes in.
+
+```rust template="storage" showLineNumbers {6, 10-14}
+use cw_storey::containers::{Item, Map};
+use cw_storey::CwStorage;
+
+const BALANCES: u8 = 0;
+
+let balances: Map<String, Map<String, Item<Uint128>>> = Map::new(BALANCES);
+let mut cw_storage = CwStorage(&mut storage);
+let mut access = balances.access(&mut cw_storage);
+
+access.entry_mut("alice").entry_mut("USDT").set(&Uint128::new(1000)).unwrap();
+access.entry_mut("alice").entry_mut("OSMO").set(&Uint128::new(2000)).unwrap();
+
+assert_eq!(access.entry("alice").entry("USDT").get().unwrap(), Some(Uint128::new(1000)));
+assert_eq!(access.entry("alice").entry("OSMO").get().unwrap(), Some(Uint128::new(2000)));
+```
+
+This example is similar to the previous one, but this time we have an extra level of nesting.
+
+First of all, our type is `Map<String, Map<String, Item<Uint128>>>`. The outer map maps user
+addresses to an inner map. The inner map maps token denominations to actual balances.
+
+When we access the stuff, the first `entry`/`entry_mut` call accesses a record in the outer map, and
+the second one accesses a record in the inner map.
+
+<Callout>
+  In [`cw-storage-plus`], you can achieve the same
+  effect using composite keys (tuples). The example above would then use something like
+  `cw_storage_plus::Map<(String, String), Uint128>`.
+</Callout>
+
+#### Iterating over the balances
+
+TODO
+
+<Callout type="warning">
+  When iterating over the entries in a `Map` using the `pairs`, `keys`, and `values` methods, the
+  **order of the keys is not guaranteed to be sensible** (though it is deterministic). If you need a
+  sensible order, try using the bounded iterators. If they do not exist (traits like
+  `BoundedIterableAccessor` are not implemented for the accessor), sensibly ordered iteration is not
+  possible.
+
+  Sensibly ordered iteration is not possible when both of the following conditions are met:
+
+  - The key is dynamically sized (e.g. `String`, `Vec<u8>`, etc.).
+  - The value type is a collection (`Map`, `Column`, etc.) rather than something like `Item`.
+</Callout>
+
+[`cw-storage-plus`]: /cw-storage-plus/containers/map