table.md

Module 0x2::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.

• Resource TablePlaceholder
• Struct Table
• Function new
• Function new_with_object_id_by_system
• Function add
• Function borrow
• Function borrow_with_default
• Function borrow_mut
• Function borrow_mut_with_default
• Function upsert
• Function remove
• Function contains
• Function destroy_empty
• Function length
• Function is_empty
• Function drop
• Function handle

use 0x2::core_addresses;
use 0x2::object;

Resource TablePlaceholder

struct TablePlaceholder has key

Struct Table

Type of tables

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

Function new

Create a new Table.

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

Function new_with_object_id_by_system

Create a new Table with object id.

public fun new_with_object_id_by_system<K: copy, drop, store, V: store>(system: &signer, id: object::ObjectID): table::Table<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, store, V: store>(table: &mut table::Table<K, V>, key: K, val: V)

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, store, V: store>(table: &table::Table<K, V>, key: K): &V

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, store, V: store>(table: &table::Table<K, V>, key: K, default: &V): &V

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, store, V: store>(table: &mut table::Table<K, V>, key: K): &mut V

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, store, V: drop, store>(table: &mut table::Table<K, V>, key: K, default: V): &mut V

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, store, V: drop, store>(table: &mut table::Table<K, V>, key: K, value: V)

Function remove

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

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

Function contains

Returns true if table contains an entry for key.

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

Function destroy_empty

Destroy a table. Aborts if the table is not empty.

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

Function length

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

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

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: &table::Table<K, V>): bool

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>(table: table::Table<K, V>)

Function handle

Returns table handle of table.

public fun handle<K: copy, drop, store, V: store>(table: &table::Table<K, V>): object::ObjectID