From 335aecd8b86a094053aa894f12dcdaed582cca76 Mon Sep 17 00:00:00 2001 From: Filippo Costa Date: Wed, 23 Aug 2023 10:51:24 +0200 Subject: [PATCH] Docs --- module-system/sov-state/src/lib.rs | 2 +- module-system/sov-state/src/map.rs | 72 +++++++++++++++++++++++++----- 2 files changed, 62 insertions(+), 12 deletions(-) diff --git a/module-system/sov-state/src/lib.rs b/module-system/sov-state/src/lib.rs index 360f6167d1..31743b0178 100644 --- a/module-system/sov-state/src/lib.rs +++ b/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::*; diff --git a/module-system/sov-state/src/map.rs b/module-system/sov-state/src/map.rs index b876cc85db..f20338ca33 100644 --- a/module-system/sov-state/src/map.rs +++ b/module-system/sov-state/src/map.rs @@ -24,7 +24,7 @@ pub struct StateMap { /// 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 StateMap { } impl StateMap { - /// 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, { /// 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(&self, key: &Q, value: &V, working_set: &mut WorkingSet) where K: Borrow, @@ -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(map: StateMap, u64>, key: &[u8], ws: &mut WorkingSet) -> Option + /// 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(map: StateMap, u64>, key: [u8; 32], ws: &mut WorkingSet) -> Option + /// where + /// S: Storage, + /// { + /// map.get(&key[..], ws) + /// } + /// ``` pub fn get(&self, key: &Q, working_set: &mut WorkingSet) -> Option where K: Borrow, @@ -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( &self, key: &Q, working_set: &mut WorkingSet, - ) -> Result + ) -> Result where K: Borrow, 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(&self, key: &Q, working_set: &mut WorkingSet) -> Option where K: Borrow, @@ -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( &self, key: &Q, working_set: &mut WorkingSet, - ) -> Result + ) -> Result where K: Borrow, 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(&self, key: &Q, working_set: &mut WorkingSet) where K: Borrow,