# 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(); let table2 = table::new(); 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); ``` - [Struct `Table`](#iota_table_Table) - [Constants](#@Constants_0) - [Function `new`](#iota_table_new) - [Function `add`](#iota_table_add) - [Function `borrow`](#iota_table_borrow) - [Function `borrow_mut`](#iota_table_borrow_mut) - [Function `remove`](#iota_table_remove) - [Function `contains`](#iota_table_contains) - [Function `length`](#iota_table_length) - [Function `is_empty`](#iota_table_is_empty) - [Function `destroy_empty`](#iota_table_destroy_empty) - [Function `drop`](#iota_table_drop)

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()
}