Skip to main content

​
Vec<T>

Vec is a sequential and indexable growable collection type. Values are stored in the environment and are available to contract through the functions defined on Vec. Values stored in the Vec are transmitted to the environment as Vals, and when retrieved from the Vec are transmitted back and converted from Val back into their type.

​
Type Safety

The values in a Vec are not guaranteed to be of type T and conversion will fail if they are not. Most functions on Vec have a try_ variation that returns a Result that will be Err if the conversion fails. Functions that are not prefixed with try_ will panic if conversion fails. Functions with an _unchecked suffix will panic if called with indexes that are out-of-bounds.

​
Constructor Methods

​
new

pub fn new(env: &Env) -> Vec<T>
Create an empty Vec. Example: 
use soroban_sdk::{Env, Vec};

let env = Env::default();
let vec = Vec::<i32>::new(&env);
assert_eq!(vec.len(), 0);

​
from_array

pub fn from_array<const N: usize>(env: &Env, items: [T; N]) -> Vec<T>
Create a Vec from the array of items.

​
from_slice

pub fn from_slice(env: &Env, items: &[T]) -> Vec<T>
where T: Clone
Create a Vec from the slice of items.

​
from_iter

pub fn from_iter<I: IntoIterator<Item = T>>(env: &Env, iter: I) -> Vec<T>
Create a Vec from an iterator of items. This provides FromIterator-like functionality but requires an Env parameter. Note: This function iteratively adds each item one at a time, making a call to the Soroban environment for each item making it inefficient for joining two Vecs. Use Vec::append to join two Vecs. Example: 
use soroban_sdk::{Env, Vec};

let env = Env::default();
let items = vec![1, 2, 3, 4];
let vec = Vec::from_iter(&env, items.into_iter());
assert_eq!(vec.len(), 4);

​
Element Access Methods

​
get

pub fn get(&self, i: u32) -> Option<T>
Returns the item at the position or None if out-of-bounds. Panics: If the value at the position cannot be converted to type T.

​
try_get

pub fn try_get(&self, i: u32) -> Result<Option<T>, T::Error>
Returns the item at the position or None if out-of-bounds. Errors: If the value at the position cannot be converted to type T.

​
get_unchecked

pub fn get_unchecked(&self, i: u32) -> T
Returns the item at the position. Panics:
  • If the position is out-of-bounds.
  • If the value at the position cannot be converted to type T.

​
try_get_unchecked

pub fn try_get_unchecked(&self, i: u32) -> Result<T, T::Error>
Returns the item at the position. Errors: If the value at the position cannot be converted to type T. Panics: If the position is out-of-bounds.

​
set

pub fn set(&mut self, i: u32, v: T)
Sets the item at the position with new value. Panics: If the position is out-of-bounds.

​
Front/Back Access Methods

​
first

pub fn first(&self) -> Option<T>
Returns the first item or None if empty. Panics: If the value at the first position cannot be converted to type T.

​
try_first

pub fn try_first(&self) -> Result<Option<T>, T::Error>
Returns the first item or None if empty. Errors: If the value at the first position cannot be converted to type T.

​
first_unchecked

pub fn first_unchecked(&self) -> T
Returns the first item. Panics:
  • If the vec is empty.
  • If the value at the first position cannot be converted to type T.

​
try_first_unchecked

pub fn try_first_unchecked(&self) -> Result<T, T::Error>
Returns the first item. Errors: If the value at the first position cannot be converted to type T. Panics: If the vec is empty.

​
last

pub fn last(&self) -> Option<T>
Returns the last item or None if empty. Panics: If the value at the last position cannot be converted to type T.

​
try_last

pub fn try_last(&self) -> Result<Option<T>, T::Error>
Returns the last item or None if empty. Errors: If the value at the last position cannot be converted to type T.

​
last_unchecked

pub fn last_unchecked(&self) -> T
Returns the last item. Panics:
  • If the vec is empty.
  • If the value at the last position cannot be converted to type T.

​
try_last_unchecked

pub fn try_last_unchecked(&self) -> Result<T, T::Error>
Returns the last item. Errors: If the value at the last position cannot be converted to type T. Panics: If the vec is empty.

​
Modification Methods

​
push_front

pub fn push_front(&mut self, x: T)
Adds the item to the front. Increases the length by one, shifts all items up by one, and puts the item in the first position.

​
pop_front

pub fn pop_front(&mut self) -> Option<T>
Removes and returns the first item or None if empty. Panics: If the value at the first position cannot be converted to type T.

​
try_pop_front

pub fn try_pop_front(&mut self) -> Result<Option<T>, T::Error>
Removes and returns the first item or None if empty. Errors: If the value at the first position cannot be converted to type T.

​
pop_front_unchecked

pub fn pop_front_unchecked(&mut self) -> T
Removes and returns the first item. Panics:
  • If the vec is empty.
  • If the value at the first position cannot be converted to type T.

​
try_pop_front_unchecked

pub fn try_pop_front_unchecked(&mut self) -> Result<T, T::Error>
Removes and returns the first item. Errors: If the value at the first position cannot be converted to type T. Panics: If the vec is empty.

​
push_back

pub fn push_back(&mut self, x: T)
Adds the item to the back. Increases the length by one and puts the item in the last position.

​
pop_back

pub fn pop_back(&mut self) -> Option<T>
Removes and returns the last item or None if empty. Panics: If the value at the last position cannot be converted to type T.

​
try_pop_back

pub fn try_pop_back(&mut self) -> Result<Option<T>, T::Error>
Removes and returns the last item or None if empty. Errors: If the value at the last position cannot be converted to type T.

​
pop_back_unchecked

pub fn pop_back_unchecked(&mut self) -> T
Removes and returns the last item. Panics:
  • If the vec is empty.
  • If the value at the last position cannot be converted to type T.

​
try_pop_back_unchecked

pub fn try_pop_back_unchecked(&mut self) -> Result<T, T::Error>
Removes and returns the last item. Errors: If the value at the last position cannot be converted to type T. Panics: If the vec is empty.

​
insert

pub fn insert(&mut self, i: u32, x: T)
Inserts an item at the position. Panics: If the position is out-of-bounds.

​
remove

pub fn remove(&mut self, i: u32) -> Option<()>
Removes the item at the position. Returns None if out-of-bounds.

​
remove_unchecked

pub fn remove_unchecked(&mut self, i: u32)
Removes the item at the position. Panics: If the position is out-of-bounds.

​
Collection Operations

​
append

pub fn append(&mut self, other: &Vec<T>)
Append the items.

​
extend_from_array

pub fn extend_from_array<const N: usize>(&mut self, items: [T; N])
Extend with the items in the array.

​
extend_from_slice

pub fn extend_from_slice(&mut self, items: &[T])
where T: Clone
Extend with the items in the slice.

​
slice

pub fn slice(&self, r: impl RangeBounds<u32>) -> Self
Returns a subset of the bytes as defined by the start and end bounds of the range. Panics: If the range is out-of-bounds.

​
concat (for Vec<Vec<T>>)

pub fn concat(&self) -> Vec<T>
Concatenates all inner vectors into a single vector.

​
Search Methods

​
contains

pub fn contains(&self, item: impl Borrow<T>) -> bool
Returns true if the Vec contains the item.

​
first_index_of

pub fn first_index_of(&self, item: impl Borrow<T>) -> Option<u32>
Returns the index of the first occurrence of the item. If the item cannot be found None is returned.

​
last_index_of

pub fn last_index_of(&self, item: impl Borrow<T>) -> Option<u32>
Returns the index of the last occurrence of the item. If the item cannot be found None is returned. 
pub fn binary_search(&self, item: impl Borrow<T>) -> Result<u32, u32>
Returns the index of an occurrence of the item in an already sorted Vec, or the index of where the item can be inserted to keep the Vec sorted. If the item is found, Result::Ok is returned containing the index of the item. If the item is not found, Result::Err is returned containing the index of where the item could be inserted to retain the sorted ordering.

​
Utility Methods

​
is_empty

pub fn is_empty(&self) -> bool
Returns true if the vec is empty and contains no items.

​
len

pub fn len(&self) -> u32
Returns the number of items in the vec.

​
shuffle

pub fn shuffle(&mut self)
Returns copy of the vec shuffled using the NOT-SECURE PRNG. In tests, must be called from within a running contract. Warning: The pseudo-random generator used to perform the shuffle is not suitable for security-sensitive work.

​
to_shuffled

pub fn to_shuffled(&self) -> Self
Returns copy of the vec shuffled using the NOT-SECURE PRNG. In tests, must be called from within a running contract. Warning: The pseudo-random generator used to perform the shuffle is not suitable for security-sensitive work.

​
Iterator Methods

​
iter

pub fn iter(&self) -> UnwrappedIter<VecTryIter<T>, T, T::Error>
Returns an iterator over the vec.

​
try_iter

pub fn try_iter(&self) -> VecTryIter<T>
Returns a fallible iterator over the vec.

​
into_try_iter

pub fn into_try_iter(self) -> VecTryIter<T>
Converts the vec into a fallible iterator.

​
Conversion Methods

​
env

pub fn env(&self) -> &Env
Returns a reference to the environment.

​
as_val

pub fn as_val(&self) -> &Val
Returns a reference to the underlying Val.

​
to_val

pub fn to_val(&self) -> Val
Converts to a Val.

​
to_vals

pub fn to_vals(&self) -> Vec<Val>
Converts to a Vec of Val.

​
Macro

​
vec!

vec!($env:expr $(,)?)
vec!($env:expr, $($x:expr),+ $(,)?)
Create a Vec with the given items. The first argument in the list must be a reference to an Env, then the items follow. Example: 
use soroban_sdk::{Env, vec};

let env = Env::default();
let vec = vec![&env, 0, 1, 2, 3];
assert_eq!(vec.len(), 4);

​
Usage Examples

​
Basic Usage

use soroban_sdk::{vec, Env};

let env = Env::default();
let vec = vec![&env, 0, 1, 2, 3];
assert_eq!(vec.len(), 4);

​
Iterating Over a Vec

use soroban_sdk::{vec, Env};

let env = Env::default();
let vec = vec![&env, 0, 1, 2, 3, 4];

for item in vec.iter() {
    // Process each item
}

​
Slicing a Vec

use soroban_sdk::{vec, Env};

let env = Env::default();
let vec = vec![&env, 0, 1, 2, 3, 4];
let slice = vec.slice(1..4);
assert_eq!(slice, vec![&env, 1, 2, 3]);

​
See Also

  • Bytes and BytesN for storing u8s and binary data
  • Map for key-value storage
  • Storage for persistent storage