Docs

module-system/sov-state/src/lib.rs

@@ -27,7 +27,7 @@ mod state_tests;
 use std::fmt::Display;
 use std::str;
 
-pub use map::StateMap;
+pub use map::{StateMap, StateMapError};
 #[cfg(feature = "native")]
 pub use prover_storage::{delete_storage, ProverStorage};
 pub use scratchpad::*;

module-system/sov-state/src/map.rs

@@ -24,7 +24,7 @@ pub struct StateMap<K, V, VC = BorshCodec> {
 
 /// Error type for the [`StateMap::get`] method.
 #[derive(Debug, Error)]
-pub enum Error {
+pub enum StateMapError {
     #[error("Value not found for prefix: {0} and: storage key {1}")]
     MissingValue(Prefix, StorageKey),
 }
@@ -38,7 +38,8 @@ impl<K, V> StateMap<K, V> {
 }
 
 impl<K, V, VC> StateMap<K, V, VC> {
-    /// Creates a new [`StateMap`] with the given prefix and codec.
+    /// Creates a new [`StateMap`] with the given prefix and
+    /// [`StateValueCodec`].
     pub fn with_codec(prefix: Prefix, codec: VC) -> Self {
         Self {
             _phantom: (PhantomData, PhantomData),
@@ -59,6 +60,9 @@ where
     VC: StateValueCodec<V>,
 {
     /// Inserts a key-value pair into the map.
+    ///
+    /// Much like [`StateMap::get`], the key may be any borrowed form of the
+    /// map’s key type.
     pub fn set<Q, S: Storage>(&self, key: &Q, value: &V, working_set: &mut WorkingSet<S>)
     where
         K: Borrow<Q>,
@@ -67,7 +71,43 @@ where
         working_set.set_value(self.prefix(), key, value, &self.value_codec)
     }
 
-    /// Returns the value corresponding to the key or None if key is absent in the StateMap.
+    /// Returns the value corresponding to the key, or [`None`] if the map
+    /// doesn't contain the key.
+    ///
+    /// # Examples
+    ///
+    /// The key may be any borrowed form of the map’s key type. Note that
+    /// [`Hash`] and [`Eq`] on the borrowed form must match those for the key
+    /// type.
+    ///
+    /// ```
+    /// use sov_state::{StateMap, Storage, WorkingSet};
+    ///
+    /// fn foo<S>(map: StateMap<Vec<u8>, u64>, key: &[u8], ws: &mut WorkingSet<S>) -> Option<u64>
+    /// where
+    ///     S: Storage,
+    /// {
+    ///     // We perform the `get` with a slice, and not the `Vec`. it is so because `Vec` borrows
+    ///     // `[T]`.
+    ///     map.get(key, ws)
+    /// }
+    /// ```
+    ///
+    /// If the map's key type does not implement [`Borrow`] for your desired
+    /// target type, you'll have to convert the key to something else. An
+    /// example of this would be "slicing" an array to use in [`Vec`]-keyed
+    /// maps:
+    ///
+    /// ```
+    /// use sov_state::{StateMap, Storage, WorkingSet};
+    ///
+    /// fn foo<S>(map: StateMap<Vec<u8>, u64>, key: [u8; 32], ws: &mut WorkingSet<S>) -> Option<u64>
+    /// where
+    ///     S: Storage,
+    /// {
+    ///     map.get(&key[..], ws)
+    /// }
+    /// ```
     pub fn get<Q, S: Storage>(&self, key: &Q, working_set: &mut WorkingSet<S>) -> Option<V>
     where
         K: Borrow<Q>,
@@ -76,22 +116,26 @@ where
         working_set.get_value(self.prefix(), key, &self.value_codec)
     }
 
-    /// Returns the value corresponding to the key or Error if key is absent in the StateMap.
+    /// Returns the value corresponding to the key or [`StateMapError`] if the key is
+    /// not found.
+    ///
+    /// Use [`StateMap::get`] if you want an [`Option`] instead of a [`Result`].
     pub fn get_or_err<Q, S: Storage>(
         &self,
         key: &Q,
         working_set: &mut WorkingSet<S>,
-    ) -> Result<V, Error>
+    ) -> Result<V, StateMapError>
     where
         K: Borrow<Q>,
         Q: Hash + Eq + ?Sized,
     {
         self.get(key, working_set).ok_or_else(|| {
-            Error::MissingValue(self.prefix().clone(), StorageKey::new(self.prefix(), key))
+            StateMapError::MissingValue(self.prefix().clone(), StorageKey::new(self.prefix(), key))
         })
     }
 
-    /// Removes a key from the StateMap, returning the corresponding value (or None if the key is absent).
+    /// Removes a key from the map, returning the corresponding value (or
+    /// [`None`] if the key is absent).
     pub fn remove<Q, S: Storage>(&self, key: &Q, working_set: &mut WorkingSet<S>) -> Option<V>
     where
         K: Borrow<Q>,
@@ -100,22 +144,28 @@ where
         working_set.remove_value(self.prefix(), key, &self.value_codec)
     }
 
-    /// Removes a key from the StateMap, returning the corresponding value (or Error if the key is absent).
+    /// Removes a key from the map, returning the corresponding value (or
+    /// [`StateMapError`] if the key is absent).
+    ///
+    /// Use [`StateMap::remove`] if you want an [`Option`] instead of a [`Result`].
     pub fn remove_or_err<Q, S: Storage>(
         &self,
         key: &Q,
         working_set: &mut WorkingSet<S>,
-    ) -> Result<V, Error>
+    ) -> Result<V, StateMapError>
     where
         K: Borrow<Q>,
         Q: Hash + Eq + ?Sized,
     {
         self.remove(key, working_set).ok_or_else(|| {
-            Error::MissingValue(self.prefix().clone(), StorageKey::new(self.prefix(), key))
+            StateMapError::MissingValue(self.prefix().clone(), StorageKey::new(self.prefix(), key))
         })
     }
 
-    /// Deletes a key from the StateMap.
+    /// Deletes a key-value pair from the map.
+    ///
+    /// This is equivalent to [`StateMap::remove`], but doesn't deserialize and
+    /// return the value beforing deletion.
     pub fn delete<Q, S: Storage>(&self, key: &Q, working_set: &mut WorkingSet<S>)
     where
         K: Borrow<Q>,