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 Table<phantom K: copy, drop, store, phantom V: store> 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 new<K: copy, drop, store, V: store>(ctx: &mut sui::tx_context::TxContext): sui::table::Table<K, V>

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 add<K: copy, drop, store, V: store>(table: &mut sui::table::Table<K, V>, k: K, v: V)

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 borrow<K: copy, drop, store, V: store>(table: &sui::table::Table<K, V>, k: K): &V

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_mut<K: copy, drop, store, V: store>(table: &mut sui::table::Table<K, V>, k: K): &mut V

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 remove<K: copy, drop, store, V: store>(table: &mut sui::table::Table<K, V>, k: K): V

Function contains

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

public fun contains<K: copy, drop, store, V: store>(table: &sui::table::Table<K, V>, k: K): bool

Function length

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

public fun length<K: copy, drop, store, V: store>(table: &sui::table::Table<K, V>): u64

Function is_empty

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

public fun is_empty<K: copy, drop, store, V: store>(table: &sui::table::Table<K, V>): bool

Function destroy_empty

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

public fun destroy_empty<K: copy, drop, store, V: store>(table: sui::table::Table<K, V>)

Function drop

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

public fun drop<K: copy, drop, store, V: drop, store>(table: sui::table::Table<K, V>)