Struct ink_storage::collections::Stash

pub struct Stash<T> where
    T: PackedLayout,  { /* private fields */ }

A stash data structure operating on contract storage.

This allows to store information similar to a vector but in unordered fashion which enables constant time random deletion of elements. This allows for efficient attachment of data to some numeric indices.

Implementations

impl<T> Stash<T> where
    T: PackedLayout, 

pub fn new() -> Self

Creates a new empty stash.

pub fn len(&self) -> u32

Returns the number of elements stored in the stash.

pub fn is_empty(&self) -> bool

Returns true if the stash contains no elements.

pub fn capacity(&self) -> u32

Returns the number of entries the stash can hold without allocating another storage cell.

Note

This is the total number of occupied and vacant entries of the stash.

pub fn entries_key(&self) -> Option<&Key>

Returns the underlying key to the cells.

Note

This is a low-level utility getter and should normally not be required by users.

pub fn iter(&self) -> Iter<'_, T>

Returns an iterator yielding shared references to all elements of the stash.

Note

Avoid unbounded iteration over big storage stashes. Prefer using methods like Iterator::take in order to limit the number of yielded elements.

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Returns an iterator yielding exclusive references to all elements of the stash.

Note

Avoid unbounded iteration over big storage stashes. Prefer using methods like Iterator::take in order to limit the number of yielded elements.

pub fn entries(&self) -> Entries<'_, T>

Returns an iterator yielding shared references to all entries of the stash.

impl<T> Stash<T> where
    T: PackedLayout, 

pub fn get(&self, at: u32) -> Option<&T>

Returns a shared reference to the element at the given index.

pub fn get_mut(&mut self, at: u32) -> Option<&mut T>

Returns an exclusive reference to the element at the given index.

impl<T> Stash<T> where
    T: PackedLayout, 

pub fn put(&mut self, new_value: T) -> u32

Put the element into the stash at the next vacant position.

Returns the stash index that the element was put into.

pub fn take(&mut self, at: u32) -> Option<T>

Takes the element stored at the given index if any.

pub unsafe fn remove_occupied(&mut self, at: u32) -> Option<()>

Removes the element stored at the given index if any.

This method acts similar to the take API and even still returns an Option. However, it guarantees to make no contract storage reads to the indexed element and will only write to its internal low-level lazy cache that the element at the given index is going to be removed at the end of the contract execution.

Calling this method with an index out of bounds for the returns None and does not remove the element, otherwise it returns Some(()).

Safety

The caller must ensure that at refers to an occupied index. Behavior is unspecified if at refers to a vacant index and could seriously damage the contract storage integrity.

pub fn defrag<C>(&mut self, max_iterations: Option<u32>, callback: C) -> u32 where
    C: FnMut(u32, u32, &T), 

Defragments the underlying storage to minimize footprint.

Returns the number of storage cells freed this way.

This might invalidate indices stored outside the stash.

Callback

In order to keep those indices up-to-date the caller can provide a callback function that is called for every moved entry with a shared reference to the entries value and the old as well as the new index.

Note

• If max_iterations is Some concrete value it is used in order to bound the number of iterations and won’t try to defrag until the stash is optimally compacted.
• Users are advised to call this method using Some concrete value to keep gas costs within certain bounds.
• The call to the given callback takes place before the reinsertion of the shifted occupied entry.

Trait Implementations

impl<T: Debug> Debug for Stash<T> where
    T: PackedLayout, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Default for StorageStash<T> where
    T: PackedLayout, 

fn default() -> Self

Returns the “default value” for a type.

impl<T> Drop for StorageStash<T> where
    T: PackedLayout, 

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Extend<T> for StorageStash<T> where
    T: PackedLayout, 

fn extend<I>(&mut self, iter: I) where
    I: IntoIterator<Item = T>, 

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T> FromIterator<T> for StorageStash<T> where
    T: PackedLayout, 

fn from_iter<I>(iter: I) -> Self where
    I: IntoIterator<Item = T>, 

Creates a value from an iterator.

impl<T> Index<u32> for StorageStash<T> where
    T: PackedLayout, 

type Output = T

The returned type after indexing.

fn index(&self, index: u32) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> IndexMut<u32> for StorageStash<T> where
    T: PackedLayout, 

fn index_mut(&mut self, index: u32) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<'a, T: 'a> IntoIterator for &'a StorageStash<T> where
    T: PackedLayout, 

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T: 'a> IntoIterator for &'a mut StorageStash<T> where
    T: PackedLayout, 

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> PartialEq<Stash<T>> for StorageStash<T> where
    T: PartialEq + PackedLayout, 

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> SpreadAllocate for StorageStash<T> where
    T: PackedLayout, 

fn allocate_spread(ptr: &mut KeyPtr) -> Self

Default initializes the implementing type using spread layout.

impl<T> SpreadLayout for StorageStash<T> where
    T: PackedLayout, 

const FOOTPRINT: u64

The footprint of the type.

fn pull_spread(ptr: &mut KeyPtr) -> Self

Pulls an instance of Self from the contract storage.

fn push_spread(&self, ptr: &mut KeyPtr)

Pushes an instance of Self to the contract storage.

fn clear_spread(&self, ptr: &mut KeyPtr)

Clears an instance of Self from the contract storage.

const REQUIRES_DEEP_CLEAN_UP: bool

Indicates whether a type requires deep clean-up of its state meaning that a clean-up routine has to decode an entity into an instance in order to eventually recurse upon its tear-down. This is not required for the majority of primitive data types such as i32, however types such as storage::Box that might want to forward the clean-up procedure to their inner T require a deep clean-up.

impl<T> StorageLayout for StorageStash<T> where
    T: PackedLayout + TypeInfo + 'static, 

fn layout(key_ptr: &mut KeyPtr) -> Layout

Returns the static storage layout of Self.

impl<T> Eq for StorageStash<T> where
    T: Decode + Eq + PackedLayout,