pub struct Vec<T> where
    T: PackedLayout
{ /* private fields */ }
Expand description

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

Creates a new empty storage vector.

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

Returns true if the vector contains no elements.

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.

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.

Returns a shared reference to the first element if any.

Returns a shared reference to the last element if any.

Returns a shared reference to the indexed element.

Returns None if index is out of bounds.

Appends an element to the back of the vector.

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()
    .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, });

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()
    .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, });

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()
.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, });

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

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.

Returns an exclusive reference to the first element if any.

Returns an exclusive reference to the last element if any.

Returns an exclusive reference to the indexed element.

Returns None if index is out of bounds.

Swaps the elements at the given indices.

Panics

If one or both indices are out of bounds.

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.

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.

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.

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

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Executes the destructor for this type. Read more

Extends a collection with the contents of an iterator. Read more

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements. Read more

Creates a value from an iterator. Read more

The returned type after indexing.

Performs the indexing (container[index]) operation. Read more

Performs the mutable indexing (container[index]) operation. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Default initializes the implementing type using spread layout. Read more

The footprint of the type. Read more

Pulls an instance of Self from the contract storage. Read more

Pushes an instance of Self to the contract storage. Read more

Clears an instance of Self from the contract storage. Read more

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. Read more

Returns the static storage layout of Self. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.