Struct IterableMap 

pub struct IterableMap<K, V>
where
    K: BorshSerialize + BorshDeserialize,
    V: Iterable + Clone,
{ /* private fields */ }

IterableMap is a contract-level data structure to provide abstraction by utilizing Get and Set operations associated with Contract Storage. It supports lazy read/write on key-value tuples which can also be iterated as a vector.

IterableMap

IterableMap can be a Contract Field defined in the contract struct. E.g.

#[contract]
struct MyContract {
    iterable_map: IterableMap<K, V>,
}

Storage Model

Account Storage State Key Format:

Component	Key	Value (Data type)
Map Info	P, 0	MapInfoCell
Key-Index	P, 1, L, K	KeyIndexCell
Index-Key	P, 2, L, I	ValueCell (data: K)
Index-Value	P, 3, L, I	ValueCell

• P: parent key
• L: map level
• I: little endian bytes of index (u32)
• K: user defined key

Lazy Write

Trait Storage implements the IterableMap so that data can be saved to world state

1. after execution of action method with receiver &mut self; or
2. explicitly calling the setter Self::set().

Implementations

impl<K, V> IterableMap<K, V>

where K: BorshSerialize + BorshDeserialize, V: Iterable + Clone,

pub fn new() -> Self

Instantiate new instance of IterableMap. It does not interact with world state if it is not inserted into contract field.

Example

let nested_map: IterableMap<String, u64> = IterableMap::new();
self.iterable_map.insert(&"nested_map".to_string(), nested_map);

pub fn get(&self, key: &K) -> Option<V>

Get data either from cached value or world state.

Example

match self.get(key) {
   Some(value) => {
       log("GET".as_bytes(), format!("value = {}", value).as_bytes());
   },
   None => {
       log("GET".as_bytes(), "key not found".as_bytes());
   }
}

pub fn get_mut(&mut self, key: &K) -> Option<&mut V>

Get data as mutable reference to Iterable either from cached value or world state.

Example

match self.iterable_map.get_mut(key) {
    Some(value) => { 
        // value is mutable reference.
        *value += 1; 
        // the change will be updated to world state after contract method execution
    },
    None => {}
}

pub fn insert(&mut self, key: &K, value: V) -> Option<&mut V>

Insert value to IterableMap. It returns a mutable reference to the inserted value in cache.

Example

self.iterable_map.insert(key, value);

pub fn remove(&mut self, key: &K)

Remove key from IterableMap.

pub fn clear(&mut self)

clear the map. It performs actual Write to world state.

Example

// It performs clearance of pending key-value pairs and also world state.
self.iterable_map.clear();
// After this point, no value can be obtained after clear.
self.iterable_map.get(key);

pub fn keys(&self) -> IterableMapKeys<'_, K, V>

Iterator to iterating keys in the map as MapKey. Iterating is a Lazy Read operation.

Example

self.iterable_map.keys().for_each(|k|{
    ...
});

pub fn values(&self) -> IterableMapValues<'_, K, V>

Iterator to iterating values in the map as Iterable. Iterating is a Lazy Read operation.

Example

self.iterable_map.values().for_each(|v|{
    ...
});

pub fn values_mut(&mut self) -> IterableMapValuesMut<'_, K, V>

Mutable Iterator to iterating values in the map as &mut Iterable. Iterating is a Lazy Read operation. It is expensive operation because the values are expected to save back to storage at the end of contract execution.

Example

self.iterable_map.values_mut().for_each(|v|{
    ...
});

Trait Implementations

impl<K, V> BorshDeserialize for IterableMap<K, V>

where K: BorshSerialize + BorshDeserialize, V: Iterable + Clone,

fn deserialize_reader<R: Read>(reader: &mut R) -> Result<Self>

fn deserialize(buf: &mut &[u8]) -> Result<Self, Error>

Deserializes this instance from a given slice of bytes. Updates the buffer to point at the remaining bytes.

fn try_from_slice(v: &[u8]) -> Result<Self, Error>

Deserialize this instance from a slice of bytes.

fn try_from_reader<R>(reader: &mut R) -> Result<Self, Error>

where R: Read,

impl<K, V> BorshSerialize for IterableMap<K, V>

where K: BorshSerialize + BorshDeserialize, V: Iterable + Clone,

fn serialize<W: Write>(&self, writer: &mut W) -> Result<()>

fn try_to_vec(&self) -> Result<Vec<u8>, Error>

Serialize this instance into a vector of bytes.

impl<K, V> Clone for IterableMap<K, V>

where K: BorshSerialize + BorshDeserialize + Clone, V: Iterable + Clone + Clone,

fn clone(&self) -> IterableMap<K, V>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K, V> Iterable for IterableMap<K, V>

where K: BorshSerialize + BorshDeserialize, V: Iterable + Clone,

fn save(&mut self, key: Vec<u8>)

fn is_map(key: Vec<u8>) -> bool

fn load(key: Vec<u8>) -> Option<Self>

fn delete(key: Vec<u8>)

impl<K, V> Storable for IterableMap<K, V>

where K: BorshSerialize + BorshDeserialize, V: Iterable + Clone,

fn __load_storage(field: &StoragePath) -> Self

This method is called at the beginning of contract execution, if this IterableMap is a field of the Contract Struct.

fn __save_storage(&mut self, field: &StoragePath)

This method is called at the end of contract execution, if this IterableMap is a field of the Contract Struct.