Struct StorageVec

pub struct StorageVec<S: StorageType> { /* private fields */ }

Accessor for a storage-backed vector.

Implementations

impl<S: StorageType> StorageVec<S>

pub fn is_empty(&self) -> bool

Returns true if the collection contains no elements.

pub fn len(&self) -> usize

Gets the number of elements stored.

pub unsafe fn set_len(&mut self, len: usize)

Overwrites the vector’s length.

Safety

It must be sensible to create accessors for S from zero-slots, or any junk data left over from prior dirty operations. Note that StorageVec has unlimited capacity, so all lengths are valid.

pub fn getter(&self, index: impl TryInto<usize>) -> Option<StorageGuard<'_, S>>

Gets an accessor to the element at a given index, if it exists.

Note: the accessor is protected by a StorageGuard, which restricts its lifetime to that of &self.

pub fn setter( &mut self, index: impl TryInto<usize>, ) -> Option<StorageGuardMut<'_, S>>

Gets a mutable accessor to the element at a given index, if it exists.

Note: the accessor is protected by a StorageGuardMut, which restricts its lifetime to that of &mut self.

pub fn get(&self, index: impl TryInto<usize>) -> Option<S::Wraps<'_>>

Gets the element at the given index, if it exists.

pub fn get_mut(&mut self, index: impl TryInto<usize>) -> Option<S::WrapsMut<'_>>

Gets a mutable accessor to the element at a given index, if it exists.

pub fn grow(&mut self) -> StorageGuardMut<'_, S>

Like std::vec::Vec::push, but returns a mutable accessor to the new slot. This enables pushing elements without constructing them first.

Example

extern crate alloc;
use stylus_sdk::storage::{StorageVec, StorageType, StorageU256};
use stylus_sdk::alloy_primitives::U256;
use stylus_test::*;

let vm = TestVM::default();
let mut vec: StorageVec<StorageVec<StorageU256>> = StorageVec::from(&vm);
let mut inner_vec = vec.grow();
inner_vec.push(U256::from(8));

let value = inner_vec.get(0).unwrap();
assert_eq!(value, U256::from(8));
assert_eq!(inner_vec.len(), 1);

pub fn shrink(&mut self) -> Option<StorageGuardMut<'_, S>>

Removes and returns an accessor to the last element of the vector, if any.

pub fn truncate(&mut self, len: usize)

Shortens the vector, keeping the first len elements.

Note: this method does not erase any underlying storage.

impl<'a, S: SimpleStorageType<'a>> StorageVec<S>

pub fn push(&mut self, value: S::Wraps<'a>)

Adds an element to the end of the vector.

pub fn pop(&mut self) -> Option<S::Wraps<'a>>

Removes and returns the last element of the vector, if it exists.

Note: the underlying storage slot is erased when all elements in a word are freed.

impl<S: Erase> StorageVec<S>

pub fn erase_last(&mut self)

Removes and erases the last element of the vector.

Trait Implementations

impl<S: Erase> Erase for StorageVec<S>

fn erase(&mut self)

Erase the value from persistent storage.

impl<'a, S: SimpleStorageType<'a>> Extend<<S as StorageType>::Wraps<'a>> for StorageVec<S>

fn extend<T: IntoIterator<Item = S::Wraps<'a>>>(&mut self, iter: 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<S, T> From<&T> for StorageVec<S>

where S: StorageType, T: Host + Clone + 'static,

fn from(host: &T) -> Self

Converts to this type from the input type.

impl<S: StorageType> HostAccess for StorageVec<S>

fn vm(&self) -> &dyn Host

Provides access to the parametrized host of a contract, giving access to all the desired hostios from the user.

impl<S: StorageType> StorageType for StorageVec<S>

type Wraps<'a> = StorageGuard<'a, StorageVec<S>> where Self: 'a

For primitive types, this is the type being stored. For collections, this is the StorageType being collected.

type WrapsMut<'a> = StorageGuardMut<'a, StorageVec<S>> where Self: 'a

Mutable accessor to the type being stored.

unsafe fn new(slot: U256, offset: u8, host: VM) -> Self

Where in persistent storage the type should live. Although useful for framework designers creating new storage types, most user programs shouldn’t call this. Note: implementations will have to be const once generic_const_exprs stabilizes.

fn load<'s>(self) -> Self::Wraps<'s>

Load the wrapped type, consuming the accessor. Note: most types have a get and/or getter, which don’t consume Self.

fn load_mut<'s>(self) -> Self::WrapsMut<'s>

Load the wrapped mutable type, consuming the accessor. Note: most types have a set and/or setter, which don’t consume Self.

const SLOT_BYTES: usize = 32usize

The number of bytes in a slot needed to represent the type. Must not exceed 32. For types larger than 32 bytes that are stored inline with a struct’s fields, set this to 32 and return the full size in StorageType::new.

const REQUIRED_SLOTS: usize = 0usize

The number of words this type must fill. For primitives this is always 0. For complex types requiring more than one inline word, set this to the total size.