Struct VecHandler 

pub struct VecHandler<T: Storable> {
    len_slot: U256,
    address: Address,
    cache: HandlerCache<usize, T::Handler>,
}

Type-safe handler for accessing Vec<T> in storage.

Provides both full-vector operations (read/write/delete) and individual element access. The handler is a thin wrapper around a storage slot number and delegates full-vector operations to Slot<Vec<T>>.

Element Access

Use at(index) to get a Slot<T> for individual element operations with OOB guarantees. Use [index] for its efficient counterpart without the check.

• For packed elements (T::BYTES ≤ 16): returns a packed Slot<T> with byte offsets
• For unpacked elements: returns a full Slot<T> for the element’s dedicated slot

Example

let handler = <Vec<u8> as StorableType>::handle(len_slot, LayoutCtx::FULL);

// Full vector operations
let vec = handler.read()?;
handler.write(&mut storage, vec![1, 2, 3])?;

// Individual element operations
if let Some(slot) = handler[0]? {
    let elem = slot.read()?;
    slot.write(42)?;
}

Capacity

Vectors have a maximum capacity of u32::MAX / element_size to prevent arithmetic overflow in storage slot calculations.

Fields

len_slot: U256

address: Address

cache: HandlerCache<usize, T::Handler>

Implementations

impl<T> VecHandler<T>

where T: Storable,

pub fn new(len_slot: U256, address: Address) -> Self

Creates a new handler for the vector at the given base slot and address.

const fn max_index() -> usize

Max valid index to prevent arithmetic overflow in slot calculations.

pub fn len_slot(&self) -> U256

Returns the slot that stores the length of the dynamic array.

pub fn data_slot(&self) -> U256

Returns the base storage slot where this array’s data is stored.

Single-slot vectors pack all fields into this slot. Multi-slot vectors use consecutive slots starting from this base.

fn as_slot(&self) -> Slot<Vec<T>>

Returns a Slot accessor for full-vector operations.

pub fn len(&self) -> Result<usize>

Returns the length of the vector.

pub fn is_empty(&self) -> Result<bool>

Returns whether the vector is empty.

fn compute_handler( data_start: U256, address: Address, index: usize, ) -> T::Handler

pub fn at(&self, index: usize) -> Result<Option<&T::Handler>>

Returns a Handler for the element at the given index with bounds checking.

The handler is computed on first access and cached for subsequent accesses.

Returns

• If the SLOAD to read the length fails, returns an error.
• If the index is OOB, returns Ok(None).
• Otherwise, returns Ok(Some(&T::Handler)).

pub fn push(&self, value: T) -> Result<()>

where T: Storable, T::Handler: Handler<T>,

Pushes a new element to the end of the vector.

Automatically increments the length and handles packing for small types.

Returns Err if the vector has reached its maximum capacity.

pub fn pop(&self) -> Result<Option<T>>

where T: Storable, T::Handler: Handler<T>,

Pops the last element from the vector.

Returns None if the vector is empty. Automatically decrements the length and zeros out the popped element’s storage slot.

Trait Implementations

impl<T: Clone + Storable> Clone for VecHandler<T>

where T::Handler: Clone,

fn clone(&self) -> VecHandler<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug + Storable> Debug for VecHandler<T>

where T::Handler: Debug,

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

Formats the value using the given formatter.

impl<T> Handler<Vec<T>> for VecHandler<T>

where T: Storable,

fn read(&self) -> Result<Vec<T>>

Reads the entire vector from storage.

fn write(&mut self, value: Vec<T>) -> Result<()>

Writes the entire vector to storage.

fn delete(&mut self) -> Result<()>

Deletes the entire vector from storage (clears length and all elements).

fn t_read(&self) -> Result<Vec<T>>

Reads the entire vector from transient storage.

fn t_write(&mut self, value: Vec<T>) -> Result<()>

Writes the entire vector to transient storage.

fn t_delete(&mut self) -> Result<()>

Deletes the entire vector from transient storage.

impl<T> Index<usize> for VecHandler<T>

where T: Storable,

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

Returns a reference to the cached handler for the given index (unchecked).

WARNING: Does not check bounds. Caller must ensure that the index is valid. For checked access use .at(index) instead.

type Output = <T as StorableType>::Handler

The returned type after indexing.

impl<T> IndexMut<usize> for VecHandler<T>

where T: Storable,

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

Returns a mutable reference to the cached handler for the given index (unchecked).

WARNING: Does not check bounds. Caller must ensure that the index is valid. For checked access use .at(index) instead.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 112 bytes