Struct fadroma::storage::iterable::IterableStorage

pub struct IterableStorage<T: FadromaSerialize + FadromaDeserialize, K: Key> { /* private fields */ }

Stores items in a way that allows for iterating over them in a sequential order just like a Vec. It’s also possible to retrieve or update inidividual items based on their index.

Implementations

impl<T: FadromaSerialize + FadromaDeserialize, K: Key> IterableStorage<T, K>

pub fn new(ns: K) -> Self

Creates an instance for the given namespace. The following namespaces are reserved by IterableStorage:

• ns + “index”
• ns + n - where n is a number

pub fn iter<'storage>( &self, storage: &'storage dyn Storage ) -> StdResult<Iter<'storage, T>>

Returns an iterator that iterates through the stored elements in a sequential order.

Examples

let key = CompositeKey::new(&[b"numbers"]);
let mut iterable = IterableStorage::<u8, _>::new(key);
 
iterable.push(storage, &1)?;
iterable.push(storage, &2)?;
 
let mut iter = iterable.iter(storage)?;
assert_eq!(iter.next().unwrap(), Ok(1));
assert_eq!(iter.next().unwrap(), Ok(2));
assert_eq!(iter.next(), None);

pub fn push(&mut self, storage: &mut dyn Storage, value: &T) -> StdResult<u64>

Returns the index at which the item is stored at.

Examples

let key = CompositeKey::new(&[b"numbers"]);
let mut iterable = IterableStorage::<u8, _>::new(key);
 
let index = iterable.push(storage, &1)?;
assert_eq!(index, 0);
 
let index = iterable.push(storage, &2)?;
assert_eq!(index, 1);

pub fn pop(&mut self, storage: &mut dyn Storage) -> StdResult<()>

Removes the item at the end of the collection. Does not return the removed element because that requires a storage read.

Examples

let key = CompositeKey::new(&[b"numbers"]);
let mut iterable = IterableStorage::<u8, _>::new(key);
 
iterable.push(storage, &1)?;
assert_eq!(iterable.len(storage)?, 1);
 
iterable.pop(storage)?;
assert_eq!(iterable.len(storage)?, 0);

pub fn get(&self, storage: &dyn Storage, index: u64) -> StdResult<Option<T>>

Retruns the element stored at the given index or None if the index is out of bounds.

Examples

let key = CompositeKey::new(&[b"numbers"]);
let mut iterable = IterableStorage::<u8, _>::new(key);
 
iterable.push(storage, &1)?;
 
assert_eq!(iterable.get(storage, 0)?, Some(1));
assert_eq!(iterable.get(storage, 1)?, None);

pub fn get_or_error(&self, storage: &dyn Storage, index: u64) -> StdResult<T>

pub fn canonize_and_push<Input: Canonize<Output = T>>( &mut self, deps: DepsMut<'_>, item: Input ) -> StdResult<u64>

pub fn canonize_and_set<Input: Canonize<Output = T>>( &mut self, deps: DepsMut<'_>, index: u64, item: Input ) -> StdResult<()>

pub fn set( &mut self, storage: &mut dyn Storage, index: u64, item: &T ) -> StdResult<()>

Overwrites the value at the given index. Returns and error if the index is out of bounds.

Examples

let key = CompositeKey::new(&[b"numbers"]);
let mut iterable = IterableStorage::<u8, _>::new(key);
iterable.push(storage, &1)?;
 
assert_eq!(iterable.get(storage, 0)?, Some(1));

iterable.set(storage, 0, &2)?;
assert_eq!(iterable.get(storage, 0)?, Some(2));

pub fn update<F>( &self, storage: &mut dyn Storage, index: u64, update: F ) -> StdResult<Option<T>>where F: FnOnce(T) -> StdResult<T>,

Returns the value returned by the provided update closure or None if nothing is stored at the given index.

Examples

let key = CompositeKey::new(&[b"numbers"]);
let mut iterable = IterableStorage::<u8, _>::new(key);
 
iterable.push(storage, &1)?;
 
let add_one = |mut x| {
    x += 1;
    Ok(x)
};
 
let updated_val = iterable.update(storage, 0, add_one)?;
assert_eq!(updated_val, Some(2));
assert_eq!(iterable.get(storage, 0)?, Some(2));
 
let updated_val = iterable.update(storage, 1, add_one)?;
assert_eq!(updated_val, None);

pub fn swap_remove( &mut self, storage: &mut dyn Storage, index: u64 ) -> StdResult<Option<T>>

Removes the element at the given index. The removed element is replaced by the last element in the storage. Does not preserve ordering. Returns the item that was swapped if such was necessary. Return an error if the index is out of bounds.

Examples

let key = CompositeKey::new(&[b"numbers"]);
let mut iterable = IterableStorage::<u8, _>::new(key);
 
iterable.push(storage, &1)?;
iterable.push(storage, &2)?;
 
let removed = iterable.swap_remove(storage, 0)?;
// We had to move the number 2 to index 0 so this is what is returned.
assert_eq!(removed, Some(2));
assert_eq!(iterable.len(storage)?, 1);
 
let removed = iterable.swap_remove(storage, 0)?;
// We removed the last element so no reordering was necessary.
assert_eq!(removed, None);
assert_eq!(iterable.len(storage)?, 0);
 
let err = iterable.swap_remove(storage, 0).unwrap_err();
assert_eq!(err, StdError::generic_err("IterableStorage: index out of bounds."));

pub fn len(&self, storage: &dyn Storage) -> StdResult<u64>

Returns the number of element currently stored.

Examples

let key = CompositeKey::new(&[b"numbers"]);
let mut iterable = IterableStorage::<u8, _>::new(key);
 
iterable.push(storage, &1)?;
assert_eq!(iterable.len(storage)?, 1);
 
iterable.pop(storage)?;
assert_eq!(iterable.len(storage)?, 0);

impl<T: FadromaSerialize + FadromaDeserialize + Humanize, K: Key> IterableStorage<T, K>

pub fn get_humanize( &self, deps: Deps<'_>, index: u64 ) -> StdResult<Option<<T as Humanize>::Output>>

pub fn get_humanize_or_error( &self, deps: Deps<'_>, index: u64 ) -> StdResult<<T as Humanize>::Output>

impl<T: FadromaSerialize + FadromaDeserialize + Humanize, K: Key> IterableStorage<T, K>where <T as Humanize>::Output: Default,

pub fn get_humanize_or_default( &self, deps: Deps<'_>, index: u64 ) -> StdResult<<T as Humanize>::Output>

impl<T: FadromaSerialize + FadromaDeserialize + Default, K: Key> IterableStorage<T, K>

pub fn get_or_default(&self, storage: &dyn Storage, index: u64) -> StdResult<T>