pub struct Vector<T>where
T: BorshSerialize,{ /* private fields */ }
Expand description
An iterable implementation of vector that stores its content on the trie. This implementation will load and store values in the underlying storage lazily.
Uses the following map: index -> element. Because the data is sharded to avoid reading/writing large chunks of data, the values cannot be accessed as a contiguous piece of memory.
This implementation will cache all changes and loads and only updates values that are changed
in storage after it’s dropped through it’s Drop
implementation. These changes can be updated
in storage before the variable is dropped by using Vector::flush
. During the lifetime of
this type, storage will only be read a maximum of one time per index and only written once per
index unless specifically flushed.
This type should be a drop in replacement for Vec
in most cases and will provide contracts
a vector structure which scales much better as the contract data grows.
§Examples
use near_sdk::store::Vector;
let mut vec = Vector::new(b"a");
assert!(vec.is_empty());
vec.push(1);
vec.push(2);
assert_eq!(vec.len(), 2);
assert_eq!(vec[0], 1);
assert_eq!(vec.pop(), Some(2));
assert_eq!(vec.len(), 1);
vec[0] = 7;
assert_eq!(vec[0], 7);
vec.extend([1, 2, 3].iter().copied());
assert!(Iterator::eq(vec.into_iter(), [7, 1, 2, 3].iter()));
Implementations§
source§impl<T> Vector<T>where
T: BorshSerialize,
impl<T> Vector<T>where
T: BorshSerialize,
sourcepub fn len(&self) -> u32
pub fn len(&self) -> u32
Returns the number of elements in the vector, also referred to as its size.
This function returns a u32
rather than the Vec
equivalent of usize
to have
consistency between targets.
§Examples
use near_sdk::store::Vector;
let mut vec = Vector::new(b"a");
vec.push(1);
vec.push(2);
assert_eq!(vec.len(), 2);
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true
if the vector contains no elements.
§Examples
use near_sdk::store::Vector;
let mut vec = Vector::new(b"a");
assert!(vec.is_empty());
vec.push(1);
assert!(!vec.is_empty());
sourcepub fn new<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
pub fn new<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
Create new vector with zero elements. Prefixes storage access with the prefix provided.
This prefix can be anything that implements IntoStorageKey
. The prefix is used when
storing and looking up values in storage to ensure no collisions with other collections.
§Examples
use near_sdk::store::Vector;
let mut vec: Vector<u8> = Vector::new(b"a");
sourcepub fn set(&mut self, index: u32, value: T)
pub fn set(&mut self, index: u32, value: T)
Sets a value at a given index to the value provided. This does not shift values after the index to the right.
The reason to use this over modifying with Vector::get_mut
or
IndexMut::index_mut
is to avoid loading the existing
value from storage. This method will just write the new value.
§Panics
Panics if index
is out of bounds.
§Examples
use near_sdk::store::Vector;
let mut vec = Vector::new(b"v");
vec.push("test".to_string());
vec.set(0,"new_value".to_string());
assert_eq!(vec.get(0),Some(&"new_value".to_string()));
source§impl<T> Vector<T>where
T: BorshSerialize + BorshDeserialize,
impl<T> Vector<T>where
T: BorshSerialize + BorshDeserialize,
sourcepub fn get(&self, index: u32) -> Option<&T>
pub fn get(&self, index: u32) -> Option<&T>
Returns the element by index or None
if it is not present.
§Examples
use near_sdk::store::Vector;
let mut vec = Vector::new(b"v");
vec.push("test".to_string());
assert_eq!(Some(&"test".to_string()), vec.get(0));
assert_eq!(None, vec.get(3));
sourcepub fn get_mut(&mut self, index: u32) -> Option<&mut T>
pub fn get_mut(&mut self, index: u32) -> Option<&mut T>
Returns a mutable reference to the element at the index
provided.
§Examples
use near_sdk::store::Vector;
let mut vec = Vector::new(b"v");
let x = vec![0, 1, 2];
vec.extend(x);
if let Some(elem) = vec.get_mut(1) {
*elem = 42;
}
let actual: Vec<_> = vec.iter().cloned().collect();
assert_eq!(actual, &[0, 42, 2]);
sourcepub fn swap_remove(&mut self, index: u32) -> T
pub fn swap_remove(&mut self, index: u32) -> T
Removes an element from the vector and returns it.
The removed element is replaced by the last element of the vector.
Does not preserve ordering, but is O(1)
.
§Panics
Panics if index
is out of bounds.
§Examples
use near_sdk::store::Vector;
let mut vec: Vector<u8> = Vector::new(b"v");
vec.extend([1, 2, 3, 4]);
assert_eq!(vec.swap_remove(1), 2);
assert_eq!(vec.iter().copied().collect::<Vec<_>>(), &[1, 4, 3]);
assert_eq!(vec.swap_remove(0), 1);
assert_eq!(vec.iter().copied().collect::<Vec<_>>(), &[3, 4]);
sourcepub fn iter(&self) -> Iter<'_, T> ⓘ
pub fn iter(&self) -> Iter<'_, T> ⓘ
Returns an iterator over the vector. This iterator will lazily load any values iterated over from storage.
§Examples
use near_sdk::store::Vector;
let mut vec = Vector::new(b"v");
vec.extend([1, 2, 4]);
let mut iterator = vec.iter();
assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
sourcepub fn iter_mut(&mut self) -> IterMut<'_, T> ⓘ
pub fn iter_mut(&mut self) -> IterMut<'_, T> ⓘ
Returns an iterator over the Vector
that allows modifying each value. This iterator
will lazily load any values iterated over from storage.
§Examples
use near_sdk::store::Vector;
let mut vec = Vector::new(b"v");
vec.extend([1u32, 2, 4]);
for elem in vec.iter_mut() {
*elem += 2;
}
assert_eq!(vec.iter().copied().collect::<Vec<_>>(), &[3u32, 4, 6]);
sourcepub fn drain<R>(&mut self, range: R) -> Drain<'_, T> ⓘwhere
R: RangeBounds<u32>,
pub fn drain<R>(&mut self, range: R) -> Drain<'_, T> ⓘwhere
R: RangeBounds<u32>,
Creates a draining iterator that removes the specified range in the vector and yields the removed items.
When the iterator is dropped, all elements in the range are removed
from the vector, even if the iterator was not fully consumed. If the
iterator is not dropped (with mem::forget
for example),
the collection will be left in an inconsistent state.
This will not panic on invalid ranges (end > length
or end < start
) and instead the
iterator will just be empty.
§Examples
use near_sdk::store::Vector;
let mut vec: Vector<u32> = Vector::new(b"v");
vec.extend(vec![1, 2, 3]);
let u: Vec<_> = vec.drain(1..).collect();
assert_eq!(vec.iter().copied().collect::<Vec<_>>(), &[1]);
assert_eq!(u, &[2, 3]);
// A full range clears the vector, like `clear()` does
vec.drain(..);
assert!(vec.is_empty());
Trait Implementations§
source§impl<T> BorshDeserialize for Vector<T>where
T: BorshSerialize,
impl<T> BorshDeserialize for Vector<T>where
T: BorshSerialize,
fn deserialize_reader<R: Read>(reader: &mut R) -> Result<Self, Error>
source§fn deserialize(buf: &mut &[u8]) -> Result<Self, Error>
fn deserialize(buf: &mut &[u8]) -> Result<Self, Error>
source§fn try_from_slice(v: &[u8]) -> Result<Self, Error>
fn try_from_slice(v: &[u8]) -> Result<Self, Error>
fn try_from_reader<R>(reader: &mut R) -> Result<Self, Error>where
R: Read,
source§impl<T> BorshSerialize for Vector<T>where
T: BorshSerialize,
impl<T> BorshSerialize for Vector<T>where
T: BorshSerialize,
source§impl<T> Drop for Vector<T>where
T: BorshSerialize,
impl<T> Drop for Vector<T>where
T: BorshSerialize,
source§impl<T> Extend<T> for Vector<T>where
T: BorshSerialize + BorshDeserialize,
impl<T> Extend<T> for Vector<T>where
T: BorshSerialize + BorshDeserialize,
source§fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = T>,
fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = T>,
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)