Struct std::vec::Vec

pub struct Vec<T> {
    buf: RawVec<T>,
    len: u64,
}
Expand description

A contiguous growable array type, written as Vec<T>, short for ‘vector’. It has ownership over its buffer.

Fields

buf: RawVeclen: u64

Trait Implementations

pub fn new() -> Self

Constructs a new, empty Vec<T>.

Additional Information

The vector will not allocate until elements are pushed onto it.

Returns

  • [Vec] - A new, empty Vec<T>.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    // allocates when an element is pushed
    vec.push(5);
}

pub fn with_capacity(capacity: u64) -> Self

Constructs a new, empty Vec<T> with the specified capacity.

Additional Information

The vector will be able to hold exactly capacity elements without
reallocating. If capacity is zero, the vector will not allocate.

It is important to note that although the returned vector has the
capacity specified, the vector will have a zero length.

Arguments

  • capacity: [u64] - The capacity of the Vec<T>.

Returns

  • [Vec] - A new, empty Vec<T> with the specified capacity.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::with_capacity(2);
    // does not allocate
    vec.push(5);
    // does not re-allocate
    vec.push(10);
    // allocates
    vec.push(15);
}

pub fn push(refmut self, value: T)

Appends an element at the end of the collection.

Arguments

  • value: [T] - The value to be pushed onto the end of the collection.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    let last_element = vec.pop().unwrap();
    assert(last_element == 5);
}
```sway

pub fn capacity(self) -> u64

Gets the capacity of the allocation.

Returns

  • [u64] - The capacity of the allocation.

Examples

use std::vec::Vec;

fn foo() {
    let vec = Vec::with_capacity(5);
    let cap = vec.capacity();
    assert(cap == 5);
}

pub fn clear(refmut self)

Clears the vector, removing all values.

Note that this method has no effect on the allocated capacity
of the vector.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    vec.clear()
    assert(vec.is_empty());
}

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

Fetches the element stored at index

Arguments

  • index: [u64] - The index of the element to be fetched.

Returns

  • [Option] - The element stored at index, or None if index is out of bounds.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    vec.push(10);
    vec.push(15);
    let item = vec.get(1).unwrap();
    assert(item == 10);
    let res = vec.get(10);
    assert(res.is_none()); // index out of bounds
}

pub fn len(self) -> u64

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

Returns

  • [u64] - The length of the vector.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    assert(vec.len() == 1);
    vec.push(10);
    assert(vec.len() == 2);
}

pub fn is_empty(self) -> bool

Returns whether the vector is empty.

Returns

  • [bool] - true if the vector is empty, false otherwise.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    assert(vec.is_empty());
    vec.push(5);
    assert(!vec.is_empty());
}

pub fn remove(refmut self, index: u64) -> T

Removes and returns the element at position index within the vector,
shifting all elements after it to the left.

Arguments

  • index: [u64] - The index of the element to be removed.

Returns

  • [T] - The element that was removed.

Reverts

  • If index >= self.len

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    vec.push(10);
    vec.push(15);
    let item = vec.remove(1);
    assert(item == 10);
    assert(vec.get(0).unwrap() == 5);
    assert(vec.get(1).unwrap() == 15);
    assert(vec.get(2).is_none());
}

pub fn insert(
refmut self,
index: u64,
element: T,
)

Inserts an element at position index within the vector, shifting all
elements after it to the right.

Arguments

  • index: [u64] - The index at which to insert the element.

  • element: [T] - The element to be inserted.

Reverts

  • If index > self.len

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    vec.push(10);

    vec.insert(1, 15);

    assert(vec.get(0).unwrap() == 5);
    assert(vec.get(1).unwrap() == 15);
    assert(vec.get(2).unwrap() == 10);
}

pub fn pop(refmut self) -> Option<T>

Removes the last element from a vector and returns it.

Returns

  • [Option] - The last element of the vector, or None if the vector is empty.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();

    let res = vec.pop();
    assert(res.is_none());

    vec.push(5);
    let res = vec.pop();
    assert(res.unwrap() == 5);
    assert(vec.is_empty());
}

pub fn swap(
refmut self,
element1_index: u64,
element2_index: u64,
)

Swaps two elements.

Arguments

  • element1_index: [u64] - The index of the first element.
  • element2_index: [u64] - The index of the second element.

Reverts

  • If element1_index or element2_index is greater than or equal to the length of vector.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    vec.push(10);

    vec.swap(0, 1);

    assert(vec.get(0).unwrap() == 10);
    assert(vec.get(1).unwrap() == 5);
}

pub fn set(
refmut self,
index: u64,
value: T,
)

Updates an element at position index with a new element value.

Arguments

  • index: [u64] - The index of the element to be set.
  • value: [T] - The value of the element to be set.

Reverts

  • If index is greater than or equal to the length of vector.

Examples

use std::vec::Vec;

fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    vec.push(10);

    vec.set(0, 15);

    assert(vec.get(0).unwrap() == 15);
    assert(vec.get(1).unwrap() == 10);
}

pub fn iter(self) -> VecIter<T>

Returns an [Iterator] to iterate over this Vec.

Returns

  • [VecIter] - The struct which can be iterated over.

Examples

fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    vec.push(10);
    vec.push(15);

    // Get the iterator
    let iter = vec.iter();

    assert_eq(5, iter.next().unwrap());
    assert_eq(10, iter.next().unwrap());
    assert_eq(15, iter.next().unwrap());

    for elem in vec.iter() {
        log(elem);
    }
}

# Undefined Behavior

Modifying vector during iteration is a logical error and
results in undefined behavior. E.g.:

```sway
fn foo() {
    let mut vec = Vec::new();
    vec.push(5);
    vec.push(10);
    vec.push(15);

    for elem in vec.iter() {
        vec.push(20); // Modification causes undefined behavior.
    }
}

pub fn ptr(self) -> raw_ptr

Gets the pointer of the allocation.

Returns

[raw_ptr] - The location in memory that the allocated vec lives.

Examples

fn foo() {
    let vec = Vec::new();
    assert(!vec.ptr().is_null());
}

pub fn resize(
refmut self,
new_len: u64,
value: T,
)

Resizes the Vec in-place so that len is equal to new_len.

Additional Information

If new_len is greater than len, the Vec is extended by the difference, with each additional slot filled with value. If new_len is less than len, the Vec is simply truncated.

Arguments

  • new_len: [u64] - The new length of the Vec.
  • value: [T] - The value to fill the new length.

Examples

fn foo() {
    let vec: Vec<u64> = Vec::new();
    vec.resize(1, 7);
    assert(vec.len() == 1);
    assert(vec.get(0).unwrap() == 7);

    vec.resize(2, 9);
    assert(vec.len() == 2);
    assert(vec.get(0).unwrap() == 7);
    assert(vec.get(1).unwrap() == 9);

    vec.resize(1, 0);
    assert(vec.len() == 1);
    assert(vec.get(0).unwrap() == 7);
    assert(vec.get(1) == None);
}

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

Returns the last element in the Vec.

Returns

[Option] - The last element in the Vec or None.

Examples

fn foo() {
    let mut vec = Vec::new();
    assert(vec.last() == None);
    vec.push(1u64);
    assert(vec.last() == Some(1u64));
    vec.push(2u64);
    assert(vec.last() == Some(2u64));
}

pub fn as_raw_slice(self) -> raw_slice

pub fn from(slice: raw_slice) -> Self

pub fn abi_encode(self, buffer: Buffer) -> Buffer

pub fn abi_decode(refmut buffer: BufferReader) -> Vec<T>

pub fn clone(self) -> Self

pub fn from(bytes: Bytes) -> Vec<u8>

Creates a Vec<u8> from a Bytes.

Examples

use std:bytes::Bytes;

let mut bytes = Bytes::new();
let a = 5u8;
let b = 7u8;
let c = 9u8
bytes.push(a);
bytes.push(b);
bytes.push(c);

assert(bytes.len() == 3);

let vec: Vec<u8> = bytes.into();

assert(vec.len() == 3);
assert(vec.get(0).unwrap() == a);
assert(vec.get(1).unwrap() == b);
assert(vec.get(2).unwrap() == c);