starcoin-framework

Module 0x1::Table

Type of large-scale storage tables.

use 0x1::Errors;

Struct Table

Type of tables

struct Table<K: copy, drop, V> has store
Fields
handle: address
length: u64
Specification 
pragma intrinsic = map,
map_new = new,
map_destroy_empty = destroy_empty,
map_len = length,
map_is_empty = empty,
map_has_key = contains,
map_add_no_override = add,
map_del_must_exist = remove,
map_borrow = borrow,
map_borrow_mut = borrow_mut,
map_spec_get = spec_get,
map_spec_set = spec_set,
map_spec_del = spec_remove,
map_spec_len = spec_len,
map_spec_has_key = spec_contains;

Resource Box

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

struct Box<V> has drop, store, key
Fields
val: V

Constants

const EALREADY_EXISTS: u64 = 100;


const ENOT_EMPTY: u64 = 102;


const ENOT_FOUND: u64 = 101;

Function 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>(),
        length: 0,
    }
}
Specification 
pragma intrinsic;

Function destroy_empty

Destroy a table. The table must be empty to succeed.

public fun destroy_empty<K: copy, drop, V>(table: Table::Table<K, V>)
Implementation 
public fun destroy_empty<K: copy + drop, V>(table: Table<K, V>) {
    assert!(table.length == 0, Errors::invalid_state(ENOT_EMPTY));
    destroy_empty_box<K, V, Box<V>>(&table);
    drop_unchecked_box<K, V, Box<V>>(table)
}
Specification 
pragma intrinsic;

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>(table: &mut Table::Table<K, V>, key: K, val: V)
Implementation 
public fun add<K: copy + drop, V>(table: &mut Table<K, V>, key: K, val: V) {
    add_box<K, V, Box<V>>(table, key, Box{val});
    table.length = table.length + 1
}
Specification 
pragma intrinsic;

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>(table: &Table::Table<K, V>, key: K): &V
Implementation 
public fun borrow<K: copy + drop, V>(table: &Table<K, V>, key: K): &V {
    &borrow_box<K, V, Box<V>>(table, key).val
}
Specification 
pragma intrinsic;

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>(table: &Table::Table<K, V>, key: K, default: &V): &V
Implementation 
public fun borrow_with_default<K: copy + drop, V>(table: &Table<K, V>, key: K, default: &V): &V {
    if (!contains(table, copy key)) {
        default
    } else {
        borrow(table, 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>(table: &mut Table::Table<K, V>, key: K): &mut V
Implementation 
public fun borrow_mut<K: copy + drop, V>(table: &mut Table<K, V>, key: K): &mut V {
    &mut borrow_box_mut<K, V, Box<V>>(table, key).val
}
Specification 
pragma intrinsic;

Function length

Returns the length of the table, i.e. the number of entries.

public fun length<K: copy, drop, V>(table: &Table::Table<K, V>): u64
Implementation 
public fun length<K: copy + drop, V>(table: &Table<K, V>): u64 {
    table.length
}
Specification 
pragma intrinsic;

Function empty

Returns true if this table is empty.

public fun empty<K: copy, drop, V>(table: &Table::Table<K, V>): bool
Implementation 
public fun empty<K: copy + drop, V>(table: &Table<K, V>): bool {
    table.length == 0
}
Specification 
pragma intrinsic;

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>(table: &mut Table::Table<K, V>, key: K, default: V): &mut V
Implementation 
public fun borrow_mut_with_default<K: copy + drop, V: drop>(table: &mut Table<K, V>, key: K, default: V): &mut V {
    if (!contains(table, copy key)) {
        add(table, copy key, default)
    };
    borrow_mut(table, key)
}
Specification 
pragma opaque, verify=false;
aborts_if false;

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>(table: &mut Table::Table<K, V>, key: K, value: V)
Implementation 
public fun upsert<K: copy + drop, V: drop>(table: &mut Table<K, V>, key: K, value: V) {
    if (!contains(table, copy key)) {
        add(table, copy key, value)
    } else {
        let ref = borrow_mut(table, key);
        *ref = value;
    };
}

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, V>(table: &mut Table::Table<K, V>, key: K): V
Implementation 
public fun remove<K: copy + drop, V>(table: &mut Table<K, V>, key: K): V {
    let Box{val} = remove_box<K, V, Box<V>>(table, key);
    table.length = table.length - 1;
    val
}
Specification 
pragma intrinsic;

Function contains

Returns true iff table contains an entry for key.

public fun contains<K: copy, drop, V>(table: &Table::Table<K, V>, key: K): bool
Implementation 
public fun contains<K: copy + drop, V>(table: &Table<K, V>, key: K): bool {
    contains_box<K, V, Box<V>>(table, key)
}
Specification 
pragma intrinsic;

Function new_table_handle

fun new_table_handle<K, V>(): address
Implementation 
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>)
Implementation 
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>
Implementation 
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>
Implementation 
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
Implementation 
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>
Implementation 
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>)
Implementation 
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>)
Implementation 
native fun drop_unchecked_box<K: copy + drop, V, B>(table: Table<K, V>);

Module Specification

native fun spec_len<K, V>(t: Table<K, V>): num;


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


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


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


native fun spec_get<K, V>(t: Table<K, V>, k: K): V;
This site is open source. Improve this page.