aptos-move/framework/aptos-stdlib/doc/table.md
<a id="0x1_table"></a>
0x1::tableType 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.
TableBoxnewaddborrowborrow_with_defaultborrow_mutborrow_mut_with_defaultupsertremovecontainsdestroy_known_empty_unsafenew_table_handleadd_boxborrow_boxborrow_box_mutcontains_boxremove_boxdestroy_empty_boxdrop_unchecked_box<a id="0x1_table_Table"></a>
TableType of tables
<pre><code><b>struct</b> <a href="table.md#0x1_table_Table">Table</a><K: <b>copy</b>, drop, V> <b>has</b> store </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>handle: <b>address</b></code> </dt> <dd> </dd> </dl> </details><a id="0x1_table_Box"></a>
BoxWrapper for values. Required for making values appear as resources in the implementation.
<pre><code><b>struct</b> <a href="table.md#0x1_table_Box">Box</a><V> <b>has</b> drop, store, key </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>val: V</code> </dt> <dd> </dd> </dl> </details><a id="0x1_table_new"></a>
newCreate a new Table.
<pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_new">new</a><K: <b>copy</b>, drop, V: store>(): <a href="table.md#0x1_table_Table">table::Table</a><K, V> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_new">new</a><K: <b>copy</b> + drop, V: store>(): <a href="table.md#0x1_table_Table">Table</a><K, V> { <a href="table.md#0x1_table_Table">Table</a> { handle: <a href="table.md#0x1_table_new_table_handle">new_table_handle</a><K, V>(), } } </code></pre> </details><a id="0x1_table_add"></a>
addAdd 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.
<pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_add">add</a><K: <b>copy</b>, drop, V>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">table::Table</a><K, V>, key: K, val: V) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_add">add</a><K: <b>copy</b> + drop, V>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">Table</a><K, V>, key: K, val: V) { <a href="table.md#0x1_table_add_box">add_box</a><K, V, <a href="table.md#0x1_table_Box">Box</a><V>>(self, key, <a href="table.md#0x1_table_Box">Box</a> { val }) } </code></pre> </details><a id="0x1_table_borrow"></a>
borrowAcquire an immutable reference to the value which <code>key</code> maps to. Aborts if there is no entry for <code>key</code>.
<pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_borrow">borrow</a><K: <b>copy</b>, drop, V>(self: &<a href="table.md#0x1_table_Table">table::Table</a><K, V>, key: K): &V </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_borrow">borrow</a><K: <b>copy</b> + drop, V>(self: &<a href="table.md#0x1_table_Table">Table</a><K, V>, key: K): &V { &<a href="table.md#0x1_table_borrow_box">borrow_box</a><K, V, <a href="table.md#0x1_table_Box">Box</a><V>>(self, key).val } </code></pre> </details><a id="0x1_table_borrow_with_default"></a>
borrow_with_defaultAcquire an immutable reference to the value which <code>key</code> maps to. Returns specified default value if there is no entry for <code>key</code>.
<pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_borrow_with_default">borrow_with_default</a><K: <b>copy</b>, drop, V>(self: &<a href="table.md#0x1_table_Table">table::Table</a><K, V>, key: K, default: &V): &V </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_borrow_with_default">borrow_with_default</a><K: <b>copy</b> + drop, V>(self: &<a href="table.md#0x1_table_Table">Table</a><K, V>, key: K, default: &V): &V { <b>if</b> (!self.<a href="table.md#0x1_table_contains">contains</a>(<b>copy</b> key)) { default } <b>else</b> { self.<a href="table.md#0x1_table_borrow">borrow</a>(<b>copy</b> key) } } </code></pre> </details><a id="0x1_table_borrow_mut"></a>
borrow_mutAcquire a mutable reference to the value which <code>key</code> maps to. Aborts if there is no entry for <code>key</code>.
<pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_borrow_mut">borrow_mut</a><K: <b>copy</b>, drop, V>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">table::Table</a><K, V>, key: K): &<b>mut</b> V </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_borrow_mut">borrow_mut</a><K: <b>copy</b> + drop, V>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">Table</a><K, V>, key: K): &<b>mut</b> V { &<b>mut</b> <a href="table.md#0x1_table_borrow_box_mut">borrow_box_mut</a><K, V, <a href="table.md#0x1_table_Box">Box</a><V>>(self, key).val } </code></pre> </details><a id="0x1_table_borrow_mut_with_default"></a>
borrow_mut_with_defaultAcquire a mutable reference to the value which <code>key</code> maps to. Insert the pair (<code>key</code>, <code>default</code>) first if there is no entry for <code>key</code>.
<pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_borrow_mut_with_default">borrow_mut_with_default</a><K: <b>copy</b>, drop, V: drop>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">table::Table</a><K, V>, key: K, default: V): &<b>mut</b> V </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_borrow_mut_with_default">borrow_mut_with_default</a><K: <b>copy</b> + drop, V: drop>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">Table</a><K, V>, key: K, default: V): &<b>mut</b> V { <b>if</b> (!self.<a href="table.md#0x1_table_contains">contains</a>(<b>copy</b> key)) { self.<a href="table.md#0x1_table_add">add</a>(<b>copy</b> key, default) }; self.<a href="table.md#0x1_table_borrow_mut">borrow_mut</a>(key) } </code></pre> </details><a id="0x1_table_upsert"></a>
upsertInsert the pair (<code>key</code>, <code>value</code>) if there is no entry for <code>key</code>. update the value of the entry for <code>key</code> to <code>value</code> otherwise
<pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_upsert">upsert</a><K: <b>copy</b>, drop, V: drop>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">table::Table</a><K, V>, key: K, value: V) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_upsert">upsert</a><K: <b>copy</b> + drop, V: drop>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">Table</a><K, V>, key: K, value: V) { <b>if</b> (!self.<a href="table.md#0x1_table_contains">contains</a>(<b>copy</b> key)) { self.<a href="table.md#0x1_table_add">add</a>(<b>copy</b> key, value) } <b>else</b> { <b>let</b> ref = self.<a href="table.md#0x1_table_borrow_mut">borrow_mut</a>(key); *ref = value; }; } </code></pre> </details><a id="0x1_table_remove"></a>
removeRemove from <code>self</code> and return the value which <code>key</code> maps to. Aborts if there is no entry for <code>key</code>.
<pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_remove">remove</a><K: <b>copy</b>, drop, V>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">table::Table</a><K, V>, key: K): V </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_remove">remove</a><K: <b>copy</b> + drop, V>(self: &<b>mut</b> <a href="table.md#0x1_table_Table">Table</a><K, V>, key: K): V { <b>let</b> <a href="table.md#0x1_table_Box">Box</a> { val } = <a href="table.md#0x1_table_remove_box">remove_box</a><K, V, <a href="table.md#0x1_table_Box">Box</a><V>>(self, key); val } </code></pre> </details><a id="0x1_table_contains"></a>
containsReturns true iff <code>self</code> contains an entry for <code>key</code>.
<pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_contains">contains</a><K: <b>copy</b>, drop, V>(self: &<a href="table.md#0x1_table_Table">table::Table</a><K, V>, key: K): bool </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="table.md#0x1_table_contains">contains</a><K: <b>copy</b> + drop, V>(self: &<a href="table.md#0x1_table_Table">Table</a><K, V>, key: K): bool { <a href="table.md#0x1_table_contains_box">contains_box</a><K, V, <a href="table.md#0x1_table_Box">Box</a><V>>(self, key) } </code></pre> </details><a id="0x1_table_destroy_known_empty_unsafe"></a>
destroy_known_empty_unsafeTable 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.
<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="table.md#0x1_table_destroy_known_empty_unsafe">destroy_known_empty_unsafe</a><K: <b>copy</b>, drop, V>(self: <a href="table.md#0x1_table_Table">table::Table</a><K, V>) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>friend</b> <b>fun</b> <a href="table.md#0x1_table_destroy_known_empty_unsafe">destroy_known_empty_unsafe</a><K: <b>copy</b> + drop, V>(self: <a href="table.md#0x1_table_Table">Table</a><K, V>) { <a href="table.md#0x1_table_destroy_empty_box">destroy_empty_box</a><K, V, <a href="table.md#0x1_table_Box">Box</a><V>>(&self); <a href="table.md#0x1_table_drop_unchecked_box">drop_unchecked_box</a><K, V, <a href="table.md#0x1_table_Box">Box</a><V>>(self) } </code></pre> </details><a id="0x1_table_new_table_handle"></a>
new_table_handle<a id="0x1_table_add_box"></a>
add_box<a id="0x1_table_borrow_box"></a>
borrow_box<a id="0x1_table_borrow_box_mut"></a>
borrow_box_mut<a id="0x1_table_contains_box"></a>
contains_box<a id="0x1_table_remove_box"></a>
remove_box<a id="0x1_table_destroy_empty_box"></a>
destroy_empty_box<a id="0x1_table_drop_unchecked_box"></a>
drop_unchecked_box<a id="@Specification_0"></a>
<a id="@Specification_0_Table"></a>
Table<a id="@Specification_0_new"></a>
new<a id="@Specification_0_add"></a>
add<a id="@Specification_0_borrow"></a>
borrow<a id="@Specification_0_borrow_with_default"></a>
borrow_with_default<a id="@Specification_0_borrow_mut"></a>
borrow_mut<a id="@Specification_0_borrow_mut_with_default"></a>
borrow_mut_with_default<a id="@Specification_0_upsert"></a>
upsert<a id="@Specification_0_remove"></a>
remove<a id="@Specification_0_contains"></a>
contains<a id="0x1_table_spec_contains"></a>
<pre><code><b>native</b> <b>fun</b> <a href="table.md#0x1_table_spec_contains">spec_contains</a><K, V>(t: <a href="table.md#0x1_table_Table">Table</a><K, V>, k: K): bool; </code></pre><a id="0x1_table_spec_remove"></a>
<pre><code><b>native</b> <b>fun</b> <a href="table.md#0x1_table_spec_remove">spec_remove</a><K, V>(t: <a href="table.md#0x1_table_Table">Table</a><K, V>, k: K): <a href="table.md#0x1_table_Table">Table</a><K, V>; </code></pre><a id="0x1_table_spec_set"></a>
<pre><code><b>native</b> <b>fun</b> <a href="table.md#0x1_table_spec_set">spec_set</a><K, V>(t: <a href="table.md#0x1_table_Table">Table</a><K, V>, k: K, v: V): <a href="table.md#0x1_table_Table">Table</a><K, V>; </code></pre><a id="0x1_table_spec_get"></a>
<pre><code><b>native</b> <b>fun</b> <a href="table.md#0x1_table_spec_get">spec_get</a><K, V>(t: <a href="table.md#0x1_table_Table">Table</a><K, V>, k: K): V; </code></pre><a id="@Specification_0_destroy_known_empty_unsafe"></a>
destroy_known_empty_unsafe