Module 0x1::table

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.

• Struct Table
• Resource Box
• Function new
• Function add
• Function borrow
• Function borrow_with_default
• Function borrow_mut
• Function borrow_mut_with_default
• Function upsert
• Function remove
• Function contains
• Function destroy_known_empty_unsafe
• Function new_table_handle
• Function add_box
• Function borrow_box
• Function borrow_box_mut
• Function contains_box
• Function remove_box
• Function destroy_empty_box
• Function drop_unchecked_box
• Specification
  • Struct Table
  • Function new
  • Function add
  • Function borrow
  • Function borrow_with_default
  • Function borrow_mut
  • Function borrow_mut_with_default
  • Function upsert
  • Function remove
  • Function contains
  • Function destroy_known_empty_unsafe

Struct Table

Type of tables

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

Resource Box

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

struct Box<V> has drop, store, key

Function new

Create a new Table.

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

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

Function 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)

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

Function 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

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

Function 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

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

Function 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

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
}

Function 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

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

Function 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)

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;
    };
}

Function 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

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
}

Function 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

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

Function 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>)

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

Function new_table_handle

fun new_table_handle<K, V>(): address

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

Function add_box

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

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

Function borrow_box

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

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

Function borrow_box_mut

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

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

Function contains_box

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

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

Function remove_box

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

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

Function destroy_empty_box

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

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

Function drop_unchecked_box

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

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

Specification

Struct 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_borrow_with_default = borrow_with_default,
    map_spec_get = spec_get,
    map_spec_set = spec_set,
    map_spec_del = spec_remove,
    map_spec_has_key = spec_contains;

Function new

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

pragma intrinsic;

Function add

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

pragma intrinsic;

Function borrow

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

pragma intrinsic;

Function borrow_with_default

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

pragma intrinsic;

Function borrow_mut

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

pragma intrinsic;

Function 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;

Function upsert

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

pragma intrinsic;

Function remove

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

pragma intrinsic;

Function 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;

Function destroy_known_empty_unsafe

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

pragma intrinsic;