Skip to main content

Module iota::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 IOTA'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 iota::address;
use iota::dynamic_field;
use iota::hex;
use iota::object;
use iota::tx_context;
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::vector;

Struct Table​

public struct Table<phantom K: copy, drop, store, phantom V: store> has key, store
Fields
id: iota::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 iota::tx_context::TxContext): iota::table::Table<K, V>
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 iota::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 iota::table::Table<K, V>, k: K, v: V)
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 iota::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: &iota::table::Table<K, V>, k: K): &V
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 iota::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 iota::table::Table<K, V>, k: K): &mut V
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 iota::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 iota::table::Table<K, V>, k: K): V
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 contains<K: copy, drop, store, V: store>(table: &iota::table::Table<K, V>, k: K): bool
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 length<K: copy, drop, store, V: store>(table: &iota::table::Table<K, V>): u64
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_empty<K: copy, drop, store, V: store>(table: &iota::table::Table<K, V>): bool
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_empty<K: copy, drop, store, V: store>(table: iota::table::Table<K, V>)
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 drop<K: copy, drop, store, V: drop, store>(table: iota::table::Table<K, V>)
Implementation
public fun drop<K: copy + drop + store, V: drop + store>(table: Table<K, V>) {
let Table { id, size: _ } = table;
id.delete()
}