Skip to main content

Module 0x1::vector

A variable-sized container that can hold any type. Indexing is 0-based, and vectors are growable. This module has many native functions.

Constants​

The index into the vector is out of bounds

const EIndexOutOfBounds: u64 = 131072;

Function empty​

Create an empty vector.

public fun empty<Element>(): vector<Element>
Implementation
native public fun empty<Element>(): vector<Element>;

Function length​

Return the length of the vector.

public fun length<Element>(v: &vector<Element>): u64
Implementation
native public fun length<Element>(v: &vector<Element>): u64;

Function borrow​

Acquire an immutable reference to the ith element of the vector v. Aborts if i is out of bounds.

public fun borrow<Element>(v: &vector<Element>, i: u64): &Element
Implementation
native public fun borrow<Element>(v: &vector<Element>, i: u64): ∈

Function push_back​

Add element e to the end of the vector v.

public fun push_back<Element>(v: &mut vector<Element>, e: Element)
Implementation
native public fun push_back<Element>(v: &mut vector<Element>, e: Element);

Function borrow_mut​

Return a mutable reference to the ith element in the vector v. Aborts if i is out of bounds.

public fun borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element
Implementation
native public fun borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element;

Function pop_back​

Pop an element from the end of vector v. Aborts if v is empty.

public fun pop_back<Element>(v: &mut vector<Element>): Element
Implementation
native public fun pop_back<Element>(v: &mut vector<Element>): Element;

Function destroy_empty​

Destroy the vector v. Aborts if v is not empty.

public fun destroy_empty<Element>(v: vector<Element>)
Implementation
native public fun destroy_empty<Element>(v: vector<Element>);

Function swap​

Swaps the elements at the ith and jth indices in the vector v. Aborts if i or j is out of bounds.

public fun swap<Element>(v: &mut vector<Element>, i: u64, j: u64)
Implementation
native public fun swap<Element>(v: &mut vector<Element>, i: u64, j: u64);

Function singleton​

Return an vector of size one containing element e.

public fun singleton<Element>(e: Element): vector<Element>
Implementation
public fun singleton<Element>(e: Element): vector<Element> {
    let mut v = empty();
    v.push_back(e);
    v
}

Function reverse​

Reverses the order of the elements in the vector v in place.

public fun reverse<Element>(v: &mut vector<Element>)
Implementation
public fun reverse<Element>(v: &mut vector<Element>) {
    let len = v.length();
    if (len == 0) return ();

    let mut front_index = 0;
    let mut back_index = len -1;
    while (front_index < back_index) {
        v.swap(front_index, back_index);
        front_index = front_index + 1;
        back_index = back_index - 1;
    }
}

Function append​

Pushes all of the elements of the other vector into the lhs vector.

public fun append<Element>(lhs: &mut vector<Element>, other: vector<Element>)
Implementation
public fun append<Element>(lhs: &mut vector<Element>, mut other: vector<Element>) {
    other.reverse();
    while (!other.is_empty()) lhs.push_back(other.pop_back());
    other.destroy_empty();
}

Function is_empty​

Return true if the vector v has no elements and false otherwise.

public fun is_empty<Element>(v: &vector<Element>): bool
Implementation
public fun is_empty<Element>(v: &vector<Element>): bool {
    v.length() == 0
}

Function contains​

Return true if e is in the vector v. Otherwise, returns false.

public fun contains<Element>(v: &vector<Element>, e: &Element): bool
Implementation
public fun contains<Element>(v: &vector<Element>, e: &Element): bool {
    let mut i = 0;
    let len = v.length();
    while (i < len) {
        if (&v[i] == e) return true;
        i = i + 1;
    };
    false
}

Function index_of​

Return (true, i) if e is in the vector v at index i. Otherwise, returns (false, 0).

public fun index_of<Element>(v: &vector<Element>, e: &Element): (bool, u64)
Implementation
public fun index_of<Element>(v: &vector<Element>, e: &Element): (bool, u64) {
    let mut i = 0;
    let len = v.length();
    while (i < len) {
        if (&v[i] == e) return (true, i);
        i = i + 1;
    };
    (false, 0)
}

Function remove​

Remove the ith element of the vector v, shifting all subsequent elements. This is O(n) and preserves ordering of elements in the vector. Aborts if i is out of bounds.

public fun remove<Element>(v: &mut vector<Element>, i: u64): Element
Implementation
public fun remove<Element>(v: &mut vector<Element>, mut i: u64): Element {
    let mut len = v.length();
    // i out of bounds; abort
    if (i >= len) abort EIndexOutOfBounds;

    len = len - 1;
    while (i < len) v.swap(i, { i = i + 1; i });
    v.pop_back()
}

Function insert​

Insert e at position i in the vector v. If i is in bounds, this shifts the old v[i] and all subsequent elements to the right. If i == v.length(), this adds e to the end of the vector. This is O(n) and preserves ordering of elements in the vector. Aborts if i > v.length()

public fun insert<Element>(v: &mut vector<Element>, e: Element, i: u64)
Implementation
public fun insert<Element>(v: &mut vector<Element>, e: Element, mut i: u64) {
    let len = v.length();
    // i too big abort
    if (i > len) abort EIndexOutOfBounds;

    v.push_back(e);
    while (i < len) {
        v.swap(i, len);
        i = i + 1
    }
}

Function swap_remove​

Swap the ith element of the vector v with the last element and then pop the vector. This is O(1), but does not preserve ordering of elements in the vector. Aborts if i is out of bounds.

public fun swap_remove<Element>(v: &mut vector<Element>, i: u64): Element
Implementation
public fun swap_remove<Element>(v: &mut vector<Element>, i: u64): Element {
    assert!(!v.is_empty(), EIndexOutOfBounds);
    let last_idx = v.length() - 1;
    v.swap(i, last_idx);
    v.pop_back()
}