pchain_sdk/collections/
iterable_map.rs

1/*
2    Copyright © 2023, ParallelChain Lab 
3    Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
4*/
5
6//! Defines the collection struct [IterableMap].
7
8use std::{marker::PhantomData, collections::BTreeMap};
9use borsh::{BorshDeserialize, BorshSerialize};
10use crate::{storage::{self}, Storable, StoragePath};
11
12/// [IterableMap] is a contract-level data structure to provide abstraction by utilizing Get and Set operations associated with Contract Storage.
13/// It supports lazy read/write on key-value tuples which can also be iterated as a vector.
14/// 
15/// ## IterableMap
16/// 
17/// `IterableMap` can be a Contract Field defined in the contract struct. E.g.
18/// 
19/// ```rust
20/// #[contract]
21/// struct MyContract {
22///     iterable_map: IterableMap<K, V>,
23/// }
24/// ```
25/// 
26/// ### Storage Model
27/// 
28/// Account Storage State Key Format:
29/// 
30/// |Component|Key|Value (Data type) |
31/// |:---|:---|:---|
32/// |Map Info|P, 0|`MapInfoCell`|
33/// |Key-Index|P, 1, L, K|`KeyIndexCell`|
34/// |Index-Key|P, 2, L, I|`ValueCell` (data: K)|
35/// |Index-Value|P, 3, L, I|`ValueCell`|
36/// 
37/// - P: parent key
38/// - L: map level
39/// - I: little endian bytes of index (u32)
40/// - K: user defined key
41/// 
42/// ### Lazy Write
43/// 
44/// Trait `Storage` implements the `IterableMap` so that data can be saved to world state
45/// 
46/// 1. after execution of action method with receiver `&mut self`; or
47/// 2. explicitly calling the setter `Self::set()`.
48#[derive(Clone)]
49pub struct IterableMap<K, V> 
50    where K: BorshSerialize + BorshDeserialize,
51          V: Iterable + Clone {
52    parent_key: Vec<u8>,
53    write_set: BTreeMap<Vec<u8>, UpdateOperation<V>>,
54    _marker: PhantomData<Box<(K, V)>>
55}
56
57impl<K, V> IterableMap<K, V>
58    where K: BorshSerialize + BorshDeserialize, 
59          V: Iterable + Clone {
60    
61    /// Instantiate new instance of `IterableMap`. It does not interact with world state if it is not inserted into 
62    /// contract field.
63    /// ### Example
64    /// ```no_run
65    /// let nested_map: IterableMap<String, u64> = IterableMap::new();
66    /// self.iterable_map.insert(&"nested_map".to_string(), nested_map);
67    /// ```
68    pub fn new() -> Self {
69        Self { parent_key: vec![], write_set: BTreeMap::default(), _marker: PhantomData::default() }
70    }
71
72    /// Get data either from cached value or world state.
73    /// ### Example
74    /// ```no_run
75    /// match self.get(key) {
76    ///    Some(value) => {
77    ///        log("GET".as_bytes(), format!("value = {}", value).as_bytes());
78    ///    },
79    ///    None => {
80    ///        log("GET".as_bytes(), "key not found".as_bytes());
81    ///    }
82    /// }
83    /// ```
84    pub fn get(&self, key: &K) -> Option<V> {
85        let key_bs = key.try_to_vec().unwrap();
86        self.get_inner(&key_bs).map(|(v, _)| v)
87    }
88
89    fn get_inner(&self, key_bs: &Vec<u8>) -> Option<(V, bool)> {
90        // search the cache with last update related to this key
91        match self.write_set.get(key_bs) {
92            Some(UpdateOperation::Delete) => { None }, // deleted key in cache
93            Some(UpdateOperation::Insert(value, is_new_record)) => { Some((value.clone(), *is_new_record)) }, // found key in cache
94            None=> { self.get_from_ws_by_key(key_bs).map(|v| (v, false)) } // get from world-state
95        }
96    }
97
98    /// Get data as mutable reference to `Iterable` either from cached value or world state.
99    /// ### Example
100    /// ```no_run
101    /// match self.iterable_map.get_mut(key) {
102    ///     Some(value) => { 
103    ///         // value is mutable reference.
104    ///         *value += 1; 
105    ///         // the change will be updated to world state after contract method execution
106    ///     },
107    ///     None => {}
108    /// }
109    /// ```
110    pub fn get_mut(&mut self, key: &K) -> Option<&mut V> {
111        let key_bs = key.try_to_vec().unwrap();
112        self.get_mut_inner(&key_bs)
113    }
114
115    fn get_mut_inner(&mut self, key_bs: &Vec<u8>) -> Option<&mut V> {
116        match self.get_inner(key_bs) {
117            Some((iterable, is_new_record)) => {
118                self.insert_inner(key_bs, iterable, is_new_record);
119                match self.write_set.get_mut(key_bs) {
120                    Some(UpdateOperation::Insert(mut_value, _)) => Some(mut_value),
121                    _=> None
122                }
123            },
124            None => None,
125        }
126    }
127
128    /// Insert value to `IterableMap`. It returns a mutable reference to the inserted value in cache.
129    /// ### Example
130    /// ```no_run
131    /// self.iterable_map.insert(key, value);
132    /// ```
133    pub fn insert(&mut self, key: &K, value: V) -> Option<&mut V> {
134        let key_bs = key.try_to_vec().unwrap();
135        let new_record = !self.is_key_used(&key_bs);
136        self.insert_inner(&key_bs, value, new_record)
137    }
138
139    fn insert_inner(&mut self, key_bs: &Vec<u8>, value: V, new_record: bool) -> Option<&mut V> {
140        self.write_set.insert(key_bs.clone(), UpdateOperation::Insert(value, new_record));
141        match self.write_set.get_mut(key_bs) {
142            Some(UpdateOperation::Insert(mut_value,  _)) => Some(mut_value),
143            _=> None
144        }
145    }
146
147    /// Remove key from `IterableMap`.
148    pub fn remove(&mut self, key: &K) {
149        let key_bs = key.try_to_vec().unwrap();
150        self.write_set.insert(key_bs, UpdateOperation::Delete);
151    }
152
153    /// clear the map. It performs actual Write to world state.
154    /// ### Example
155    /// ```no_run
156    /// // It performs clearance of pending key-value pairs and also world state.
157    /// self.iterable_map.clear();
158    /// // After this point, no value can be obtained after clear.
159    /// self.iterable_map.get(key);
160    /// ```
161    pub fn clear(&mut self) {
162        self.write_set.clear();
163        self.new_ws_map_info();
164    }
165
166    /// Iterator to iterating keys in the map as `MapKey`. Iterating is a Lazy Read operation.
167    /// ### Example
168    /// ```no_run
169    /// self.iterable_map.keys().for_each(|k|{
170    ///     ...
171    /// });
172    /// ```
173    pub fn keys(&self) -> IterableMapKeys<K, V> {
174        let map_info_cell = self.get_map_info();
175        let extends: Vec<Vec<u8>> = self.write_set.iter().filter_map(|w|{
176            match w.1 { UpdateOperation::Insert(_, true) => Some(w.0.clone()), _ => None }
177        }).collect();
178        IterableMapKeys { iterable_map: self, idx: 0, level: map_info_cell.level, len: map_info_cell.sequence as usize, ext_idx: 0, extends }
179    }
180
181    /// Iterator to iterating values in the map as `Iterable`. Iterating is a Lazy Read operation.
182    /// ### Example
183    /// ```no_run
184    /// self.iterable_map.values().for_each(|v|{
185    ///     ...
186    /// });
187    /// ```
188    pub fn values(&self) -> IterableMapValues<K, V> {
189        let map_info_cell = self.get_map_info();
190        let extends: Vec<Vec<u8>> = self.write_set.iter().filter_map(|w|{
191            match w.1 { UpdateOperation::Insert(_, true) => Some(w.0.clone()), _ => None }
192        }).collect();
193        IterableMapValues{ iterable_map: self, idx: 0, level: map_info_cell.level, len: map_info_cell.sequence as usize, extends, ext_idx: 0 }
194    }
195
196    /// Mutable Iterator to iterating values in the map as `&mut Iterable`. Iterating is a Lazy Read operation.
197    /// It is expensive operation because the values are expected to save back to storage at the end of contract execution.
198    /// ### Example
199    /// ```no_run
200    /// self.iterable_map.values_mut().for_each(|v|{
201    ///     ...
202    /// });
203    /// ```
204    pub fn values_mut(&mut self) -> IterableMapValuesMut<K, V> {
205        let map_info_cell = self.get_map_info();
206        let extends: Vec<Vec<u8>> = self.write_set.iter().filter_map(|w|{
207            match w.1 { UpdateOperation::Insert(_, true) => Some(w.0.clone()), _ => None }
208        }).collect();
209        IterableMapValuesMut{iterable_map: self, idx: 0, level: map_info_cell.level, len: map_info_cell.sequence as usize, ext_idx: 0, extends }
210    }
211
212    // Map information
213    fn get_map_info(&self) -> MapInfoCell {
214        if self.parent_key.is_empty() { // newly inserted map that is not yet save to world state
215            return MapInfoCell { level: 0, sequence: 0 };
216        }
217        let ws_seq = self.wskey_map_info();
218        MapInfoCell::load(ws_seq).unwrap()
219    }
220
221    // Next level of Map Information
222    fn new_ws_map_info(&self) {
223        let mut map_info_cell = self.get_map_info();
224        map_info_cell.level += 1;
225        map_info_cell.sequence = 0;
226        let ws_seq = self.wskey_map_info();
227        map_info_cell.save(ws_seq);
228    }
229
230    /// Get the index from Key-Index, given user-defined Key.
231    /// Returns None if key is not found in Key-Index
232    fn get_index(&self, key: &[u8] , level: u32) -> Option<u32> {
233        let ws_key_index = self.wskey_key_index(key, level);
234        KeyIndexCell::load(ws_key_index).map(|ki| ki.index)
235    }
236
237    /// Get Value, given user-defined key.
238    /// 
239    /// Steps:
240    /// 1. get the index from Key-Index
241    /// 2. get the value from Index-Value
242    fn get_from_ws_by_key(&self, key: &[u8]) -> Option<V> {
243        let map_info_cell = self.get_map_info();
244        let ws_index = self.get_index(key, map_info_cell.level);
245        let ws_key_index_value = match ws_index {
246            Some(ws_index) if ws_index < map_info_cell.sequence => self.wskey_index_value(map_info_cell.level, &ws_index),
247            _ => return None,
248        };
249        V::load(ws_key_index_value)
250    }
251
252    /// Check if the user-defined key has been used. It could be alive or already deleted.
253    /// If it is used, new data to insert should reuse the cell (overriding).
254    fn is_key_used(&self, key: &[u8]) -> bool {
255        // search the cache with last update related to this key
256        let map_info_cell = self.get_map_info();
257        if map_info_cell.sequence == 0 { return false } // no elements
258        let ws_index = match self.get_index(key, map_info_cell.level) {
259            Some(ws_index) => ws_index,
260            None => return false
261        };
262        ws_index < map_info_cell.sequence
263    }
264
265    /// Add value to world state , given user-defined key and current value of Sequence.
266    /// Sequence will be increased afterwards.
267    fn add_to_ws(&self, key: &[u8], level: u32, sequence: u32, value: V) {
268        // 1. set sequence += 1
269        let ws_seq = self.wskey_map_info();
270        MapInfoCell {
271            level,
272            sequence: sequence + 1
273        }.save(ws_seq);
274
275        // 2. set key to index (sequence)
276        let ws_key_index = self.wskey_key_index(key, level);
277        KeyIndexCell {
278            index: sequence
279        }.save(ws_key_index);
280
281        // 3. set index (sequence) to key
282        let ws_index_key = self.wskey_index_key(level, &sequence);
283        key.to_owned().save(ws_index_key);
284        
285        // 4. set to index-value (sequence)
286        let ws_index_value = self.wskey_index_value(level, &sequence);
287        let mut value = value;
288        value.save(ws_index_value);
289    }
290
291    /// Lookup Key-Index and Index-Value. Update key and value to world state.
292    fn set_to_ws(&self, key: &[u8], level: u32, value: V) {
293        if let Some(index) = self.get_index(key, level) {
294            // 1. set index to key
295            let ws_index_key = self.wskey_index_key(level, &index);
296            key.to_owned().save(ws_index_key);
297
298            // 2. set to index-value
299            let ws_index_value = self.wskey_index_value(level, &index);
300            let mut value = value;
301            value.save(ws_index_value);
302        }
303    }
304
305    fn remove_from_ws(&self, key: &[u8], level: u32) {
306        if let Some(index) = self.get_index(key, level) {
307            // 1. set Index-Key to None
308            let ws_index_key = self.wskey_index_key(level, &index);
309            Vec::<u8>::delete(ws_index_key);
310
311            // 2. set Index-Value to None
312            let ws_index_value = self.wskey_index_value(level, &index);
313            V::delete(ws_index_value.clone());
314
315            // 2a. if it is a nested map, set Sequence of the nested map to 0
316            if V::is_map(ws_index_value) {
317                self.new_ws_map_info();
318            }
319        }
320    }
321
322    /// Account Storage State Key format for Map Information.
323    /// Map Information consists of:
324    /// 1. level
325    /// 2. sequence
326    /// 
327    /// - Key: [P, 0]
328    /// - Value Data Type: MapInfoCell
329    /// 
330    /// where
331    ///  - P: Parent Key
332    fn wskey_map_info(&self) -> Vec<u8> {
333        [
334            self.parent_key.to_vec(),
335            [0u8].to_vec()
336        ].concat()
337    }
338
339    /// Account Storage State Key format for Key-Index
340    /// 
341    /// - Key: [P, 1, L, K]
342    /// - Value Data Type: KeyIndexCell
343    /// 
344    /// where
345    ///  - P: Parent Key
346    ///  - L: Map Level
347    ///  - K: User defined Key
348    fn wskey_key_index(&self, key: &[u8], level: u32) -> Vec<u8> {
349        [
350            self.parent_key.to_vec(),
351            [1u8].to_vec(),
352            level.to_le_bytes().to_vec(),
353            key.to_vec()
354        ].concat()
355    }
356
357    /// Account Storage State Key format for Index-Key
358    /// 
359    /// - Key: [P, 2, L, I]
360    /// - Value Data Type: ValueCell (data: K)
361    /// 
362    /// where
363    ///  - P: Parent Key
364    ///  - K: User defined Key
365    ///  - L: Map Level
366    ///  - I: u32 value of index
367    fn wskey_index_key(&self, level: u32, index: &u32) -> Vec<u8> {
368        [
369            self.parent_key.to_vec(),
370            [2u8].to_vec(),
371            level.to_le_bytes().to_vec(),
372            index.to_le_bytes().to_vec()
373        ].concat()
374    }
375
376    /// Account Storage State Key format for Index-Value
377    /// 
378    /// - Key: [P, 3, L, I]
379    /// - Value Data Type: ValueCell
380    /// 
381    /// where
382    ///  - P: Parent Key
383    ///  - L: Map Level
384    ///  - I: u32 value of index
385    fn wskey_index_value(&self, level: u32, index: &u32) -> Vec<u8> {
386        [
387            self.parent_key.to_vec(),
388            [3u8].to_vec(),
389            level.to_le_bytes().to_vec(),
390            index.to_le_bytes().to_vec()
391        ].concat()
392    }
393}
394
395impl<K, V> Iterable for IterableMap<K, V>
396    where K: BorshSerialize + BorshDeserialize,
397          V: Iterable + Clone {
398    
399    fn save(&mut self, key: Vec<u8>) {
400        
401        if self.parent_key.is_empty() {
402            self.parent_key = key.clone();
403            // If parent key is empty, this IterableMap is inserted as nested map. 
404            // This behaviour is treated as creation of a new map and therefore MapInfo should be 
405            // updated to clear previous data.
406            self.new_ws_map_info();
407        }
408
409        let c = ValueCell { is_map: true, data: Some(self.try_to_vec().unwrap()) };
410        storage::set(&key, c.try_to_vec().unwrap().as_slice());
411
412        self.write_set.iter().for_each(|(key, ops)| {
413            let map_info_cell = self.get_map_info();
414            match ops {
415                UpdateOperation::Insert(value, true) => {
416                    self.add_to_ws(key, map_info_cell.level, map_info_cell.sequence, value.clone());
417                },
418                UpdateOperation::Insert(value, false) => {
419                    self.set_to_ws(key, map_info_cell.level, value.clone());
420                },
421                UpdateOperation::Delete => {
422                    self.remove_from_ws(key, map_info_cell.level);
423                },
424            }
425        });
426    }
427}
428
429impl<K, V> Storable for IterableMap<K, V> 
430    where K: BorshSerialize + BorshDeserialize,
431          V: Iterable + Clone {
432    
433    /// This method is called at the beginning of contract execution, if this `IterableMap` is a field of the Contract Struct.
434    fn __load_storage(field: &StoragePath) -> Self {
435        Self {
436            parent_key: field.get_path().to_vec(),
437            write_set: BTreeMap::default(),
438            _marker: PhantomData,
439        }
440    }
441
442    /// This method is called at the end of contract execution, if this `IterableMap` is a field of the Contract Struct.
443    fn __save_storage(&mut self, field: &StoragePath) {
444        self.save(field.get_path().to_vec());
445    }
446}
447
448impl<K, V> BorshSerialize for IterableMap<K, V>
449    where K: BorshSerialize + BorshDeserialize,
450          V: Iterable + Clone {
451    fn serialize<W: std::io::Write>(&self, writer: &mut W) -> std::io::Result<()> {
452        // Serialization of `IterableMap` itself takes only parent_key to be stored.
453        self.parent_key.serialize(writer)
454    }
455}
456
457impl<K, V> BorshDeserialize for IterableMap<K, V>
458    where K: BorshSerialize + BorshDeserialize,
459          V: Iterable + Clone {
460    fn deserialize_reader<R: std::io::Read>(reader: &mut R) -> std::io::Result<Self> {
461        let parent_key = Vec::<u8>::deserialize_reader(reader)?;
462        Ok(Self{
463            parent_key,
464            write_set: BTreeMap::default(),
465            _marker: PhantomData,
466        })
467    }
468}
469
470/// Return data type for `IterableMap::keys()`
471pub struct IterableMapKeys<'a, K, V>
472    where K: BorshSerialize + BorshDeserialize,
473          V: Iterable + Clone {
474    iterable_map: &'a IterableMap<K, V>,
475    idx: usize,
476    level: u32,
477    len: usize,
478    ext_idx: usize,
479    extends: Vec<Vec<u8>>,
480}
481
482impl<'a, K, V> Iterator for IterableMapKeys<'a, K, V>
483    where K: BorshSerialize + BorshDeserialize,
484          V: Iterable + Clone {
485    type Item = K;
486
487    fn next(&mut self) -> Option<K> {
488        loop {
489            if self.idx >= self.len  {
490                if let Some(bytes) = self.extends.get(self.ext_idx) {
491                    self.ext_idx += 1;
492                    return Some(K::deserialize(&mut bytes.as_slice()).unwrap())
493                }
494                return None
495            } else {
496                let ws_index_key = self.iterable_map.wskey_index_key(self.level, &(self.idx as u32));
497                if let Some(bytes) = Vec::<u8>::load(ws_index_key) {
498                    self.idx += 1;
499                    return Some(K::deserialize(&mut bytes.as_slice()).unwrap())
500                }
501            }
502            self.idx += 1;
503        }
504    }
505}
506
507/// Return data type for `IterableMap::values()`
508pub struct IterableMapValues<'a, K, V>
509    where K: BorshSerialize + BorshDeserialize,
510          V: Iterable + Clone {
511    iterable_map: &'a IterableMap<K, V>,
512    idx: usize,
513    level: u32,
514    len: usize,
515    ext_idx: usize,
516    extends: Vec<Vec<u8>>,
517}
518
519impl<'a, K, V> Iterator for IterableMapValues<'a, K, V> 
520    where K: BorshSerialize + BorshDeserialize,
521          V: Iterable + Clone {
522    type Item = V;
523
524    fn next(&mut self) -> Option<Self::Item> {
525        loop {
526            if self.idx >= self.len {
527                // keys that are newly inserted
528                if let Some(bytes) = self.extends.get(self.ext_idx) {
529                    return match self.iterable_map.write_set.get(bytes) {
530                        Some(UpdateOperation::Insert(value, _)) => {
531                            self.ext_idx += 1;
532                            Some(value.clone())
533                        },
534                        _=> None
535                    }
536                }
537                return None;
538            } else {
539                // keys that can be found in world state
540                let ws_index_key = self.iterable_map.wskey_index_key(self.level, &(self.idx as u32));
541                if let Some(bytes) = Vec::<u8>::load(ws_index_key) {
542                    if let Some((value, _)) = self.iterable_map.get_inner(&bytes) {
543                        self.idx += 1;
544                        return Some(value);
545                    }
546                }
547            }
548            self.idx += 1;
549        }
550    }
551}
552
553/// Mutable iterator created by `IterableMap::values_mut()`
554pub struct IterableMapValuesMut<'a, K, V> 
555    where K: BorshSerialize + BorshDeserialize,
556          V: Iterable + Clone {
557    iterable_map: &'a mut IterableMap<K, V>,
558    idx: usize,
559    level: u32,
560    len: usize,
561    ext_idx: usize,
562    extends: Vec<Vec<u8>>
563}
564
565impl<'a, K, V> Iterator for IterableMapValuesMut<'a, K, V> 
566    where K: BorshSerialize + BorshDeserialize,
567          V: Iterable + Clone {
568    type Item = &'a mut V;
569
570    fn next(&mut self) -> Option<Self::Item> {
571        loop {
572            if self.idx >= self.len {
573                // keys that are newly inserted
574                if let Some(bytes) = self.extends.get(self.ext_idx) {
575                    return match self.iterable_map.write_set.get_mut(bytes) {
576                        Some(UpdateOperation::Insert(mut_value, _)) => {
577                            self.ext_idx += 1;
578                            Some(unsafe{
579                                let r = mut_value as * const V;
580                                &mut *(r as *mut V)
581                            })
582                        },
583                        _ => None
584                    };
585                };
586                return None;
587            } else {
588                // keys that can be found in world state
589                let ws_index_key = self.iterable_map.wskey_index_key(self.level, &(self.idx as u32));
590                if let Some(bytes) = Vec::<u8>::load(ws_index_key) {
591                    if let Some(mut_value) = self.iterable_map.get_mut_inner(&bytes) {
592                        self.idx += 1;
593                        return Some(unsafe{
594                            let r = mut_value as * const V;
595                            &mut *(r as *mut V)
596                        });
597                    }
598                }
599            }
600            self.idx += 1;
601        }
602    }
603}
604
605/// The trait that applies to most of the data types used as value of `IterableMap`.
606/// Actual data stored to world state is in format of `ValueCell`.
607pub trait Iterable : BorshSerialize + BorshDeserialize {
608    fn is_map(key: Vec<u8>) -> bool {
609        storage::get(&key).map_or(false, |bytes|{
610            ValueCell::deserialize(&mut bytes.as_slice()).map_or(false, |c| c.is_map)
611        })
612    }
613    
614    fn load(key: Vec<u8>) -> Option<Self> {
615        let bytes = storage::get(&key)?;
616        let c = ValueCell::deserialize(&mut bytes.as_slice()).ok()?;
617        let data = c.data?;
618        Self::deserialize(&mut data.as_slice()).map_or(None, |s| Some(s))
619    }
620
621    fn save(&mut self, key: Vec<u8>) {
622        let c = ValueCell { is_map: false, data: Some(self.try_to_vec().unwrap()) };
623        storage::set(&key, c.try_to_vec().unwrap().as_slice());
624    }
625
626    fn delete(key: Vec<u8>) {
627        let c = ValueCell { is_map: false,  data: None };
628        storage::set(&key, c.try_to_vec().unwrap().as_slice());
629    }
630}
631
632/// `UpdateOpertaion` defines the runtime level update operations for Map.
633#[derive(Clone)]
634pub(crate) enum UpdateOperation<T> {
635    /// Data for update, new record indicator
636    Insert(T, bool),
637    Delete
638}
639
640/// Basic data representation of the format of value being stored in world state.
641#[derive(BorshSerialize, BorshDeserialize)]
642struct ValueCell {
643    /// indicator of whether the value being stored is a map (nested map)
644    is_map: bool,
645    /// The content is serialized from the value, which depends on implementation of 
646    /// different data types in collections. None if data is deleted. 
647    data: Option<Vec<u8>>
648}
649
650/// MapInfoCell defines the map information that is useful in constructing the storage model of `IterableMap`
651#[derive(BorshSerialize, BorshDeserialize)]
652struct MapInfoCell {
653    /// level defines the level of the map by being part of the key of child of this map.
654    /// It is part of prefix of the key to child element.
655    level: u32,
656    /// sequence is an increasing pointer to index of new inserted item.
657    /// It is part of prefix of the key to child element.
658    sequence: u32
659}
660
661impl Iterable for MapInfoCell {
662    fn load(key: Vec<u8>) -> Option<Self> {
663        if let Some(bytes) = storage::get(&key) {
664            if let Ok(c) = MapInfoCell::deserialize(&mut bytes.as_slice()) {
665                return Some(c)
666            }
667        }
668        Some(Self { level: 0, sequence: 0 })
669    }
670    fn save(&mut self, key: Vec<u8>) { storage::set(&key, self.try_to_vec().unwrap().as_slice()) }
671    fn delete(_key: Vec<u8>) { unreachable!() }
672}
673
674/// KeyIndexCell defines the data stored for Key-Index mapping in storage model of [IterableMap]
675#[derive(BorshSerialize, BorshDeserialize)]
676struct KeyIndexCell {
677    // index of Key-Index mapping. It is part of prefix of the key to child element.
678    index: u32
679}
680
681impl Iterable for KeyIndexCell {
682    fn load(key: Vec<u8>) -> Option<Self> {
683        let bytes = storage::get(&key)?;
684        KeyIndexCell::deserialize(&mut bytes.as_slice()).ok()
685    }
686    fn save(&mut self, key: Vec<u8>) { storage::set(&key, self.try_to_vec().unwrap().as_slice()) }
687    fn delete(_key: Vec<u8>) { unreachable!() }
688}
689
690// Defines Iterable to data types that supported from Borsh Serialization
691
692macro_rules! define_primitives {
693    ($($t:ty),*) => {
694        $(
695            impl Iterable for $t {}
696        )*
697    }
698}
699define_primitives!(
700    u8, u16, u32, u64, u128,
701    i8, i16, i32, i64, i128,
702    String, bool, usize,
703    [u8;32]
704);
705impl<T> Iterable for Option<T> where T: BorshSerialize + BorshDeserialize {}
706impl<T> Iterable for Vec<T> where T: BorshSerialize + BorshDeserialize {}
707macro_rules! impl_tuple {
708    ($($idx:tt $name:ident)+) => {
709      impl<$($name),+> Iterable for ($($name),+)
710      where $($name: BorshSerialize + BorshDeserialize,)+
711      {}
712    };
713}
714impl_tuple!(0 T0 1 T1);
715impl_tuple!(0 T0 1 T1 2 T2);
716impl_tuple!(0 T0 1 T1 2 T2 3 T3);
717impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4);
718impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5);
719impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6);
720impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7);
721impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8);
722impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9);
723impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10);
724impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10 11 T11);
725impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10 11 T11 12 T12);
726impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10 11 T11 12 T12 13 T13);
727impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10 11 T11 12 T12 13 T13 14 T14);
728impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10 11 T11 12 T12 13 T13 14 T14 15 T15);
729impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10 11 T11 12 T12 13 T13 14 T14 15 T15 16 T16);
730impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10 11 T11 12 T12 13 T13 14 T14 15 T15 16 T16 17 T17);
731impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10 11 T11 12 T12 13 T13 14 T14 15 T15 16 T16 17 T17 18 T18);
732impl_tuple!(0 T0 1 T1 2 T2 3 T3 4 T4 5 T5 6 T6 7 T7 8 T8 9 T9 10 T10 11 T11 12 T12 13 T13 14 T14 15 T15 16 T16 17 T17 18 T18 19 T19);
pchain_sdk/collections/iterable_map.rs

pchain_sdk/collections/
iterable_map.rs
