Skip to main content

Module sui::table

A table is a map-like collection. But unlike a traditional collection, it's keys and values are not stored within the Table value, but instead are stored using Sui's object system. The Table struct acts only as a handle into the object system to retrieve those keys and values. Note that this means that Table values with exactly the same key-value mapping will not be equal, with ==, at runtime. For example

let table1 = table::new<u64, bool>();
let table2 = table::new<u64, bool>();
table::add(&mut table1, 0, false);
table::add(&mut table1, 1, true);
table::add(&mut table2, 0, false);
table::add(&mut table2, 1, true);
// table1 does not equal table2, despite having the same entries
assert!(&table1 != &table2);
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::vector;
use sui::address;
use sui::dynamic_field;
use sui::hex;
use sui::object;
use sui::tx_context;

Struct Table​

public struct TableK, V has key, store
Click to open
Fields
id: sui::object::UID
the ID of this table
size: u64
the number of key-value pairs in the table

Constants​

const ETableNotEmpty: u64 = 0;

Function new​

Creates a new, empty table

public fun newK, V(ctx: &mut sui::tx_context::TxContext): sui::table::Table<K, V>
Click to open
Implementation
public fun new<K: copy + drop + store, V: store>(ctx: &mut TxContext): Table<K, V> {
    Table {
        id: object::new(ctx),
        size: 0,
    }
}

Function add​

Adds a key-value pair to the table table: &mut Table<K, V> Aborts with sui::dynamic_field::EFieldAlreadyExists if the table already has an entry with that key k: K.

public fun addK, V(table: &mut sui::table::Table<K, V>, k: K, v: V)
Click to open
Implementation
public fun add<K: copy + drop + store, V: store>(table: &mut Table<K, V>, k: K, v: V) {
    field::add(&mut table.id, k, v);
    table.size = table.size + 1;
}

Function borrow​

Immutable borrows the value associated with the key in the table table: &Table<K, V>. Aborts with sui::dynamic_field::EFieldDoesNotExist if the table does not have an entry with that key k: K.

public fun borrowK, V(table: &sui::table::Table<K, V>, k: K): &V
Click to open
Implementation
public fun borrow<K: copy + drop + store, V: store>(table: &Table<K, V>, k: K): &V {
    field::borrow(&table.id, k)
}

Function borrow_mut​

Mutably borrows the value associated with the key in the table table: &mut Table<K, V>. Aborts with sui::dynamic_field::EFieldDoesNotExist if the table does not have an entry with that key k: K.

public fun borrow_mutK, V(table: &mut sui::table::Table<K, V>, k: K): &mut V
Click to open
Implementation
public fun borrow_mut<K: copy + drop + store, V: store>(table: &mut Table<K, V>, k: K): &mut V {
    field::borrow_mut(&mut table.id, k)
}

Function remove​

Removes the key-value pair in the table table: &mut Table<K, V> and returns the value. Aborts with sui::dynamic_field::EFieldDoesNotExist if the table does not have an entry with that key k: K.

public fun removeK, V(table: &mut sui::table::Table<K, V>, k: K): V
Click to open
Implementation
public fun remove<K: copy + drop + store, V: store>(table: &mut Table<K, V>, k: K): V {
    let v = field::remove(&mut table.id, k);
    table.size = table.size - 1;
    v
}

Function contains​

Returns true iff there is a value associated with the key k: K in table table: &Table<K, V>

public fun containsK, V(table: &sui::table::Table<K, V>, k: K): bool
Click to open
Implementation
public fun contains<K: copy + drop + store, V: store>(table: &Table<K, V>, k: K): bool {
    field::exists_with_type<K, V>(&table.id, k)
}

Function length​

Returns the size of the table, the number of key-value pairs

public fun lengthK, V(table: &sui::table::Table<K, V>): u64
Click to open
Implementation
public fun length<K: copy + drop + store, V: store>(table: &Table<K, V>): u64 {
    table.size
}

Function is_empty​

Returns true iff the table is empty (if length returns 0)

public fun is_emptyK, V(table: &sui::table::Table<K, V>): bool
Click to open
Implementation
public fun is_empty<K: copy + drop + store, V: store>(table: &Table<K, V>): bool {
    table.size == 0
}

Function destroy_empty​

Destroys an empty table Aborts with ETableNotEmpty if the table still contains values

public fun destroy_emptyK, V(table: sui::table::Table<K, V>)
Click to open
Implementation
public fun destroy_empty<K: copy + drop + store, V: store>(table: Table<K, V>) {
    let Table { id, size } = table;
    assert!(size == 0, ETableNotEmpty);
    id.delete()
}

Function drop​

Drop a possibly non-empty table. Usable only if the value type V has the drop ability

public fun dropK, V(table: sui::table::Table<K, V>)
Click to open
Implementation
public fun drop<K: copy + drop + store, V: drop + store>(table: Table<K, V>) {
    let Table { id, size: _ } = table;
    id.delete()
}