table - [mainnet]

Type of large-scale storage tables. source: https://github.com/move-language/move/blob/1b6b7513dcc1a5c866f178ca5c1e74beb2ce181e/language/extensions/move-table-extension/sources/Table.move#L1

It implements the Table type which supports individual table items to be represented by separate global state items. The number of items and a unique handle are tracked on the table struct itself, while the operations are implemented as native functions. No traversal is provided.

Structs

`Table`

Type of tables

struct Table<K: copy, drop, V> has store

Fields

handle: address

Resources

`Box`

Wrapper for values. Required for making values appear as resources in the implementation.

struct Box<V> has drop, store, key

Fields

val: V

Functions

`new`

Create a new Table.

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

Implementation

public fun new<K: copy + drop, V: store>(): Table<K, V> {
    Table {
        handle: new_table_handle<K, V>(),
    }
}

`add`

Add a new entry to the table. Aborts if an entry for this key already exists. The entry itself is not stored in the table, and cannot be discovered from it.

public fun add<K: copy, drop, V>(self: &mut table::Table<K, V>, key: K, val: V)

Implementation

public fun add<K: copy + drop, V>(self: &mut Table<K, V>, key: K, val: V) {
    add_box<K, V, Box<V>>(self, key, Box { val })
}

`borrow`

Acquire an immutable reference to the value which key maps to. Aborts if there is no entry for key.

public fun borrow<K: copy, drop, V>(self: &table::Table<K, V>, key: K): &V

Implementation

public fun borrow<K: copy + drop, V>(self: &Table<K, V>, key: K): &V {
    &borrow_box<K, V, Box<V>>(self, key).val
}

`borrow_with_default`

Acquire an immutable reference to the value which key maps to. Returns specified default value if there is no entry for key.

public fun borrow_with_default<K: copy, drop, V>(self: &table::Table<K, V>, key: K, default: &V): &V

Implementation

public fun borrow_with_default<K: copy + drop, V>(self: &Table<K, V>, key: K, default: &V): &V {
    if (!self.contains(copy key)) {
        default
    } else {
        self.borrow(copy key)
    }
}

`borrow_mut`

Acquire a mutable reference to the value which key maps to. Aborts if there is no entry for key.

public fun borrow_mut<K: copy, drop, V>(self: &mut table::Table<K, V>, key: K): &mut V

Implementation

public fun borrow_mut<K: copy + drop, V>(self: &mut Table<K, V>, key: K): &mut V {
    &mut borrow_box_mut<K, V, Box<V>>(self, key).val
}

`borrow_mut_with_default`

Acquire a mutable reference to the value which key maps to. Insert the pair (key, default) first if there is no entry for key.

public fun borrow_mut_with_default<K: copy, drop, V: drop>(self: &mut table::Table<K, V>, key: K, default: V): &mut V

Implementation

public fun borrow_mut_with_default<K: copy + drop, V: drop>(self: &mut Table<K, V>, key: K, default: V): &mut V {
    if (!self.contains(copy key)) {
        self.add(copy key, default)
    };
    self.borrow_mut(key)
}

`upsert`

Insert the pair (key, value) if there is no entry for key. update the value of the entry for key to value otherwise

public fun upsert<K: copy, drop, V: drop>(self: &mut table::Table<K, V>, key: K, value: V)

Implementation

public fun upsert<K: copy + drop, V: drop>(self: &mut Table<K, V>, key: K, value: V) {
    if (!self.contains(copy key)) {
        self.add(copy key, value)
    } else {
        let ref = self.borrow_mut(key);
        *ref = value;
    };
}

`remove`

Remove from self and return the value which key maps to. Aborts if there is no entry for key.

public fun remove<K: copy, drop, V>(self: &mut table::Table<K, V>, key: K): V

Implementation

public fun remove<K: copy + drop, V>(self: &mut Table<K, V>, key: K): V {
    let Box { val } = remove_box<K, V, Box<V>>(self, key);
    val
}

`contains`

Returns true iff self contains an entry for key.

public fun contains<K: copy, drop, V>(self: &table::Table<K, V>, key: K): bool

Implementation

public fun contains<K: copy + drop, V>(self: &Table<K, V>, key: K): bool {
    contains_box<K, V, Box<V>>(self, key)
}

`destroy_known_empty_unsafe`

Table cannot know if it is empty or not, so this method is not public, and can be used only in modules that know by themselves that table is empty.

public(friend) fun destroy_known_empty_unsafe<K: copy, drop, V>(self: table::Table<K, V>)

Implementation

friend fun destroy_known_empty_unsafe<K: copy + drop, V>(self: Table<K, V>) {
    destroy_empty_box<K, V, Box<V>>(&self);
    drop_unchecked_box<K, V, Box<V>>(self)
}

`new_table_handle`

fun new_table_handle<K, V>(): address

Implementation

native fun new_table_handle<K, V>(): address;

`add_box`

fun add_box<K: copy, drop, V, B>(table: &mut table::Table<K, V>, key: K, val: table::Box<V>)

Implementation

native fun add_box<K: copy + drop, V, B>(table: &mut Table<K, V>, key: K, val: Box<V>);

`borrow_box`

fun borrow_box<K: copy, drop, V, B>(table: &table::Table<K, V>, key: K): &table::Box<V>

Implementation

native fun borrow_box<K: copy + drop, V, B>(table: &Table<K, V>, key: K): &Box<V>;

`borrow_box_mut`

fun borrow_box_mut<K: copy, drop, V, B>(table: &mut table::Table<K, V>, key: K): &mut table::Box<V>

Implementation

native fun borrow_box_mut<K: copy + drop, V, B>(table: &mut Table<K, V>, key: K): &mut Box<V>;

`contains_box`

fun contains_box<K: copy, drop, V, B>(table: &table::Table<K, V>, key: K): bool

Implementation

native fun contains_box<K: copy + drop, V, B>(table: &Table<K, V>, key: K): bool;

`remove_box`

fun remove_box<K: copy, drop, V, B>(table: &mut table::Table<K, V>, key: K): table::Box<V>

Implementation

native fun remove_box<K: copy + drop, V, B>(table: &mut Table<K, V>, key: K): Box<V>;

`destroy_empty_box`

fun destroy_empty_box<K: copy, drop, V, B>(table: &table::Table<K, V>)

Implementation

native fun destroy_empty_box<K: copy + drop, V, B>(table: &Table<K, V>);

`drop_unchecked_box`

fun drop_unchecked_box<K: copy, drop, V, B>(table: table::Table<K, V>)

Implementation

native fun drop_unchecked_box<K: copy + drop, V, B>(table: Table<K, V>);

Specification

`Table`

struct Table<K: copy, drop, V> has store

handle: address

pragma intrinsic = map,
    map_new = new,
    map_destroy_empty = destroy_known_empty_unsafe,
    map_has_key = contains,
    map_add_no_override = add,
    map_add_override_if_exists = upsert,
    map_del_must_exist = remove,
    map_borrow = borrow,
    map_borrow_mut = borrow_mut,
    map_borrow_mut_with_default = borrow_mut_with_default,
    map_spec_get = spec_get,
    map_spec_set = spec_set,
    map_spec_del = spec_remove,
    map_spec_has_key = spec_contains;

`new`

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

pragma intrinsic;

`add`

public fun add<K: copy, drop, V>(self: &mut table::Table<K, V>, key: K, val: V)

pragma intrinsic;

`borrow`

public fun borrow<K: copy, drop, V>(self: &table::Table<K, V>, key: K): &V

pragma intrinsic;

`borrow_mut`

public fun borrow_mut<K: copy, drop, V>(self: &mut table::Table<K, V>, key: K): &mut V

pragma intrinsic;

`borrow_mut_with_default`

public fun borrow_mut_with_default<K: copy, drop, V: drop>(self: &mut table::Table<K, V>, key: K, default: V): &mut V

pragma intrinsic;

`upsert`

public fun upsert<K: copy, drop, V: drop>(self: &mut table::Table<K, V>, key: K, value: V)

pragma intrinsic;

`remove`

public fun remove<K: copy, drop, V>(self: &mut table::Table<K, V>, key: K): V

pragma intrinsic;

`contains`

public fun contains<K: copy, drop, V>(self: &table::Table<K, V>, key: K): bool

pragma intrinsic;

native fun spec_contains<K, V>(t: Table<K, V>, k: K): bool;

native fun spec_remove<K, V>(t: Table<K, V>, k: K): Table<K, V>;

native fun spec_set<K, V>(t: Table<K, V>, k: K, v: V): Table<K, V>;

native fun spec_get<K, V>(t: Table<K, V>, k: K): V;

`destroy_known_empty_unsafe`

public(friend) fun destroy_known_empty_unsafe<K: copy, drop, V>(self: table::Table<K, V>)

pragma intrinsic;