storey::Map: document bounded and composite iteration

src/pages/storey/containers/map.mdx

@@ -22,9 +22,9 @@ Let's say you want to keep track of the balances of each user. You can do this w
 use cw_storey::containers::{Item, Map};
 use cw_storey::CwStorage;
 
-const BALANCES: u8 = 0;
+const BALANCES_IX: u8 = 0;
 
-let balances: Map<String, Item<Uint128>> = Map::new(BALANCES);
+let balances: Map<String, Item<Uint128>> = Map::new(BALANCES_IX);
 let mut cw_storage = CwStorage(&mut storage);
 let mut access = balances.access(&mut cw_storage);
 
@@ -37,17 +37,17 @@ 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 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
+  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
+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}
@@ -56,9 +56,9 @@ use cw_storey::CwStorage;
 
 use storey::containers::IterableAccessor as _;
 
-const BALANCES: u8 = 1;
+const BALANCES_IX: u8 = 1;
 
-let balances: Map<String, Item<Uint128>> = Map::new(BALANCES);
+let balances: Map<String, Item<Uint128>> = Map::new(BALANCES_IX);
 let mut cw_storage = CwStorage(&mut storage);
 let mut access = balances.access(&mut cw_storage);
 
@@ -86,12 +86,44 @@ assert_eq!(
 );
 ```
 
-- _line 4:_ Here we import the `IterableAccessor` trait. This trait provides unbounded iteration.
+- _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.
 
+#### Bounded iteration
+
+Bounded iteration is also supported in many cases.
+
+```rust template="storage" showLineNumbers {17}
+use cw_storey::containers::{Item, Map};
+use cw_storey::CwStorage;
+
+use storey::containers::BoundedIterableAccessor as _;
+
+const BALANCES_IX: u8 = 1;
+
+let balances: Map<String, Item<Uint128>> = Map::new(BALANCES_IX);
+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.bounded_pairs(Some("bob"), Some("dave")).collect::<Result<Vec<_>, _>>().unwrap(),
+    vec![(("bob".to_string(), ()), Uint128::new(500)), (("carol".to_string(), ()), Uint128::new(1500))]
+);
+```
+
+Here we used the [`bounded_pairs`] method to iterate over some key-value pairs. Other bounded
+methods are also available: [`bounded_keys`] and [`bounded_values`].
+
+The bounds are provided as arguments to the methods. Currently, the bounds are inclusive on the lower
+bound and exclusive on the upper bound. In a future release (soon!) this will be configurable.
+
 ### 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
@@ -101,9 +133,9 @@ can have multiple different tokens. This is where composition comes in.
 use cw_storey::containers::{Item, Map};
 use cw_storey::CwStorage;
 
-const BALANCES: u8 = 0;
+const BALANCES_IX: u8 = 0;
 
-let balances: Map<String, Map<String, Item<Uint128>>> = Map::new(BALANCES);
+let balances: Map<String, Map<String, Item<Uint128>>> = Map::new(BALANCES_IX);
 let mut cw_storage = CwStorage(&mut storage);
 let mut access = balances.access(&mut cw_storage);
 
@@ -117,9 +149,9 @@ assert_eq!(access.entry("alice").entry("OSMO").get().unwrap(), Some(Uint128::new
 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.
+addresses to inner maps. 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
+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>
@@ -130,20 +162,73 @@ the second one accesses a record in the inner map.
 
 #### Iterating over the balances
 
-TODO
+Let's take a look at what iteration looks like with a composite map.
+
+```rust template="storage" showLineNumbers {18, 27}
+use cw_storey::containers::{Item, Map};
+use cw_storey::CwStorage;
+use cosmwasm_std::Order;
+
+use storey::containers::IterableAccessor as _;
+
+const BALANCES_IX: u8 = 1;
+
+let balances: Map<String, Map<String, Item<u64>>> = Map::new(BALANCES_IX);
+let mut cw_storage = CwStorage(&mut storage);
+let mut access = balances.access(&mut cw_storage);
+
+access.entry_mut("alice").entry_mut("USDT").set(&1000).unwrap();
+access.entry_mut("alice").entry_mut("OSMO").set(&2000).unwrap();
+access.entry_mut("bob").entry_mut("USDT").set(&1500).unwrap();
+
+assert_eq!(
+    access.pairs().collect::<Result<Vec<_>, _>>().unwrap(),
+    vec![
+        (("bob".into(), ("USDT".into(), ())), 1500),
+        (("alice".into(), ("OSMO".into(), ())), 2000),
+        (("alice".into(), ("USDT".into(), ())), 1000),
+    ]
+);
+
+assert_eq!(
+    access.entry("alice").pairs().collect::<Result<Vec<_>, _>>().unwrap(),
+    vec![(("OSMO".into(), ()), 2000), (("USDT".into(), ()), 1000)]
+);
+```
+
+Here we iterated twice, but each time we got a different view of the data. Each iteration was at a different level.
+
+- _line 18:_ We call `pairs` on the outer map, which gives us all the entries.
+- _line 27:_ We call `pairs` on the inner map under the key `alice`, which gives us all of Alice's
+  balances.
+
+We can of course do the same with the `keys` and `values` methods.
 
 <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
+  sensible order, try using the bounded iterators. If they do not exist (`BoundedIterableAccessor` is 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:
+Bounded or 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`.
 
+This is why, in the example above, bounded iteration (and a sensible order) is only possible for
+the inner map.
 </Callout>
 
 [`cw-storage-plus`]: /cw-storage-plus/containers/map
+[`bounded_pairs`]: https://docs.rs/storey/latest/storey/containers/trait.BoundedIterableAccessor.html#method.bounded_pairs
+[`bounded_keys`]: https://docs.rs/storey/latest/storey/containers/trait.BoundedIterableAccessor.html#method.bounded_keys
+[`bounded_values`]: https://docs.rs/storey/latest/storey/containers/trait.BoundedIterableAccessor.html#method.bounded_values
+[`access`]: https://docs.rs/storey/latest/storey/containers/map/struct.Map.html#method.access
+[`entry`]: https://docs.rs/storey/latest/storey/containers/map/struct.MapAccess.html#method.entry
+[`entry_mut`]: https://docs.rs/storey/latest/storey/containers/map/struct.MapAccess.html#method.entry_mut
+[`keys`]: https://docs.rs/storey/latest/storey/containers/trait.IterableAccessor.html#method.keys
+[`values`]: https://docs.rs/storey/latest/storey/containers/trait.IterableAccessor.html#method.values
+[`pairs`]: https://docs.rs/storey/latest/storey/containers/trait.IterableAccessor.html#method.pairs
+[`ItemAccess`]: https://docs.rs/storey/latest/storey/containers/struct.ItemAccess.html
+[`MapAccess`]: https://docs.rs/storey/latest/storey/containers/map/struct.MapAccess.html
+[`IterableAccessor`]: https://docs.rs/storey/latest/storey/containers/trait.IterableAccessor.html