Struct SVec 

pub struct SVec<T: StableType + AsFixedSizeBytes> { /* private fields */ }

Stable analog of Vec

May reallocate on inserts. In this case will copy the underlying data to a new location.

This is a “finite” data structure, it can only holp up to u32::MAX / T::SIZE elements. Putting more elements inside will panic.

T has to implement both StableType and AsFixedSizeBytes. SVec itself implements these traits and can be nested inside other stable data structures.

When SVec is stable-dropped, its elements are also stable-dropped but in reverse order.

Implementations

impl<T: StableType + AsFixedSizeBytes> SVec<T>

pub fn new() -> Self

Creates a SVec of capacity equal to 4 elements.

Does not allocate any heap or stable memory.

Example

// won't allocate until you insert something in it
let mut numbers = SVec::<u64>::new();

pub fn new_with_capacity(capacity: usize) -> Result<Self, OutOfMemory>

Creates a SVec of requested capacity.

Does allocate stable memory, returning OutOfMemory if there is not enough of it. If this function returns Ok, you are guaranteed to have enough stable memory to store at least capacity elements in it.

Example

let mut at_least_10_numbers = SVec::<u64>::new_with_capacity(10)
    .expect("Out of memory");

pub fn capacity(&self) -> usize

Returns the capacity of this SVec

pub fn len(&self) -> usize

Returns the length of this SVec

pub fn is_empty(&self) -> bool

Returns true if the length of this SVec is 0

pub const fn max_capacity() -> usize

Returns the maximum possible capacity of this SVec

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

Inserts a new element at the end of this SVec

Will try to reallocate if capacity == length. If the canister is out of stable memory, will return Err with the element that was about to get inserted.

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

Removes the last element of the SVec

If the SVec is empty, returns None.

pub fn get(&self, idx: usize) -> Option<SRef<'_, T>>

Returns a SRef pointing to the element at requested index

See also SVec::get_mut.

If out of bounds, returns None

Example

let mut vec = SVec::<u64>::new();
vec.push(20).expect("Out of memory");

let elem = vec.get(0).unwrap();

assert_eq!(*elem, 20);

pub fn get_mut(&mut self, idx: usize) -> Option<SRefMut<'_, T>>

Returns SRefMut pointing to the element at requested index

See also SVec::get.

If out of bounds, returns None

Example

let mut vec = SVec::<u64>::new();
vec.push(20).expect("Out of memory");

let mut elem = vec.get_mut(0).unwrap();
*elem = 100;

pub fn replace(&mut self, idx: usize, element: T) -> T

Replaces an element at requested index with a provided value

Panics

Panics if out of bounds.

Example

let mut vec = SVec::<u64>::new();
vec.push(10).expect("Out of memory");

let prev = vec.replace(0, 20);

assert_eq!(prev, 10);
assert_eq!(*vec.get(0).unwrap(), 20);

pub fn insert(&mut self, idx: usize, element: T) -> Result<(), T>

Inserts a new element at the requested index, forward-shifting all elements after it

Will try to reallocate, if capacity == length. If the canister is out of stable memory, will return Err with the element that was about to get inserted.

Panics

Panics if out of bounds.

pub fn remove(&mut self, idx: usize) -> T

Removes element at the requested index, back-shifting all elements after it

Panics

Panics if out of bounds.

pub fn swap(&mut self, idx1: usize, idx2: usize)

Swaps elements at requested indices with each other

Panics

Panics if idx1 == idx2 or if any of indices are out of bounds.

pub fn clear(&mut self)

Clears the SVec from elements

Does not reallocate or shrink the underlying memory block.

pub fn binary_search_by<FN>(&self, f: FN) -> Result<usize, usize>

where FN: FnMut(&T) -> Ordering,

Performs binary search on a sorted SVec, using the provided lambda

Works the same way as in Vec.

Example

let mut vec = SVec::new_with_capacity(100).expect("Out of memory");

for i in 0..100 {
    vec.push(i);
}

let idx = vec.binary_search_by(|it| it.cmp(&10)).unwrap();

assert_eq!(idx, 10);

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

Returns an immutable iterator over this collection

Example

let mut vec = SVec::new_with_capacity(100).expect("Out of memory");

for i in 0..100 {
    vec.push(i);
}

for elem in vec.iter() {
    println!("{}", *elem); // will print '0, 1, 2, 3, 4, ...'
}

pub fn debug_print(&self)

Prints byte representation of this collection

Useful for tests

Trait Implementations

impl<T: StableType + AsFixedSizeBytes> AsFixedSizeBytes for SVec<T>

const SIZE: usize = 24usize

Size of self when encoded

type Buf = [u8; 24]

Buffer that is used to encode this value into

fn as_fixed_size_bytes(&self, buf: &mut [u8])

Encodes itself into a slice of bytes.

fn from_fixed_size_bytes(arr: &[u8]) -> Self

Decodes itself from a slice of bytes.

fn as_new_fixed_size_bytes(&self) -> Self::Buf

Encodes itself into a new Self::Buf of size == Self::SIZE

impl<T: StableType + AsFixedSizeBytes + Debug> Debug for SVec<T>

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

Formats the value using the given formatter.

impl<T: StableType + AsFixedSizeBytes> Default for SVec<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T: StableType + AsFixedSizeBytes> Drop for SVec<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: StableType + AsFixedSizeBytes> StableType for SVec<T>

unsafe fn stable_drop_flag_off(&mut self)

Sets stable drop flag to off position, if it is applicable

unsafe fn stable_drop_flag_on(&mut self)

Should set stable drop flag to on position, if it is applicable

fn should_stable_drop(&self) -> bool

Should return the value of the stable drop flag

unsafe fn stable_drop(&mut self)

Performs stable drop, releasing all underlying stable memory of this data structure