Struct ink_storage::Vec

pub struct Vec<T> where
    T: PackedLayout,  { /* fields omitted */ }

A contiguous growable array type, written Vec<T> but pronounced “vector”.

Note

Despite the similarity to Rust’s Vec type this storage Vec has many differences in its internal data layout. While it stores its data in contiguous storage slots this does not mean that the data is actually densely stored in memory.

Also its technical performance characteristics may be different from Rust’s Vec due to the differences stated above.

Allows to store up to 2^32 elements and is guaranteed to not reallocate upon pushing new elements to it.

Implementations

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

pub fn new() -> Self

Creates a new empty storage vector.

pub fn len(&self) -> u32

Returns the number of elements in the vector, also referred to as its length.

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

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

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

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

Note

Avoid unbounded iteration over big storage vectors. 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 vector.

Note

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

pub fn first(&self) -> Option<&T>

Returns a shared reference to the first element if any.

pub fn last(&self) -> Option<&T>

Returns a shared reference to the last element if any.

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

Returns a shared reference to the indexed element.

Returns None if index is out of bounds.

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

pub fn push(&mut self, value: T)

Appends an element to the back of the vector.

pub fn binary_search(&self, x: &T) -> Result<u32, u32> where
    T: Ord, 

Binary searches this sorted vector for a given element.

If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.

See also binary_search_by, binary_search_by_key.

Examples

Looks up a series of four elements. The first is found, with a uniquely determined position; the second and third are not found; the fourth could match any position in [1, 4].

use ink_storage::Vec as StorageVec;

let s: StorageVec<i32> = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
    .into_iter()
    .copied()
    .collect();

assert_eq!(s.binary_search(&13),  Ok(9));
assert_eq!(s.binary_search(&4),   Err(7));
assert_eq!(s.binary_search(&100), Err(13));
let r = s.binary_search(&1);
assert!(match r { Ok(1..=4) => true, _ => false, });

pub fn binary_search_by<'a, F>(&'a self, f: F) -> Result<u32, u32> where
    F: FnMut(&'a T) -> Ordering, 

Binary searches this sorted vector with a comparator function.

The comparator function should implement an order consistent with the sort order of the underlying vector, returning an order code that indicates whether its argument is Less, Equal or Greater the desired target.

If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.

See also binary_search, binary_search_by_key.

Examples

Looks up a series of four elements. The first is found, with a uniquely determined position; the second and third are not found; the fourth could match any position in [1, 4].

use ink_storage::Vec as StorageVec;

let s: StorageVec<i32> = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
    .into_iter()
    .copied()
    .collect();

let seek = 13;
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
let seek = 4;
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
let seek = 100;
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
let seek = 1;
let r = s.binary_search_by(|probe| probe.cmp(&seek));
assert!(match r { Ok(1..=4) => true, _ => false, });

pub fn binary_search_by_key<'a, B, F>(&'a self, b: &B, f: F) -> Result<u32, u32> where
    F: FnMut(&'a T) -> B,
    B: Ord, 

Binary searches this sorted vector with a key extraction function.

If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.

See also binary_search, binary_search_by.

Examples

Looks up a series of four elements in a vector of pairs sorted by their second elements. The first is found, with a uniquely determined position; the second and third are not found; the fourth could match any position in [1, 4].

use ink_storage::Vec as StorageVec;

let s: StorageVec<(i32, i32)> = [
    (0, 0),
    (2, 1),
    (4, 1),
    (5, 1),
    (3, 1),
    (1, 2),
    (2, 3),
    (4, 5),
    (5, 8),
    (3, 13),
    (1, 21),
    (2, 34),
    (4, 55),
]
.into_iter()
.copied()
.collect();

assert_eq!(s.binary_search_by_key(&13, |&(a, b)| b),  Ok(9));
assert_eq!(s.binary_search_by_key(&4, |&(a, b)| b),   Err(7));
assert_eq!(s.binary_search_by_key(&100, |&(a, b)| b), Err(13));
let r = s.binary_search_by_key(&1, |&(a, b)| b);
assert!(match r { Ok(1..=4) => true, _ => false, });

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

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

Pops the last element from the vector and returns it. Returns None if the vector is empty.

pub fn pop_drop(&mut self) -> Option<()>

Pops the last element from the vector and immediately drops it.

Returns Some(()) if an element has been removed and None otherwise.

Note

This operation is a bit more efficient than Vec::pop since it avoids reading from contract storage in some use cases.

pub fn first_mut(&mut self) -> Option<&mut T>

Returns an exclusive reference to the first element if any.

pub fn last_mut(&mut self) -> Option<&mut T>

Returns an exclusive reference to the last element if any.

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

Returns an exclusive reference to the indexed element.

Returns None if index is out of bounds.

pub fn swap(&mut self, a: u32, b: u32)

Swaps the elements at the given indices.

Panics

If one or both indices are out of bounds.

pub fn swap_remove(&mut self, n: u32) -> Option<T>

Removes the indexed element from the vector and returns it.

The last element of the vector is put into the indexed slot. Returns None and does not mutate the vector if the index is out of bounds.

Note

This operation does not preserve ordering but is constant time.

pub fn swap_remove_drop(&mut self, n: u32) -> Option<()>

Removes the indexed element from the vector.

The last element of the vector is put into the indexed slot. Returns Some(()) if an element has been removed and None otherwise.

Note

This operation should be preferred over Vec::swap_remove if there is no need to return the removed element since it avoids a contract storage read for some use cases.

pub fn set(&mut self, index: u32, new_value: T) -> Result<(), IndexOutOfBounds>

Sets the elements at the given index to the new value.

Won’t return the old element back to the caller. Prefer this operation over other method of overriding an element in the storage vector since this is more efficient.

pub fn clear(&mut self)

Removes all elements from this vector.

Note

Use this method to clear the vector instead of e.g. iterative pop(). This method performs significantly better and does not actually read any of the elements (whereas pop() does).

Trait Implementations

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

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

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

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Extend<T> for StorageVec<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 StorageVec<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 StorageVec<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 StorageVec<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 StorageVec<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 StorageVec<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<Vec<T>> for StorageVec<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> SpreadLayout for StorageVec<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 StorageVec<T> where
    T: PackedLayout + TypeInfo + 'static, 

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

Returns the static storage layout of Self.

impl<T> Eq for StorageVec<T> where
    T: Eq + PackedLayout,