Table and Bag
You can extend existing objects using dynamic fields. Note that it's possible to delete an object that still has (potentially non-drop) dynamic fields. This might not be a concern when adding a small number of statically known additional fields to an object, but is particularly undesirable for on-chain collection types that could be holding unboundedly many key-value pairs as dynamic fields.
This topic describes two such collections -- Table and Bag -- built using dynamic fields, but with additional support to count the number of entries they contain, and protect against accidental deletion when non-empty.
The types and function discussed in this section are built into the IOTA framework in modules table and bag. As with dynamic fields, there is also an object_ variant of both: ObjectTable in object_table and ObjectBag in object_bag. The relationship between Table and ObjectTable, and Bag and ObjectBag are the same as between a field and an object field: The former can hold any store type as a value, but objects stored as values are hidden when viewed from external storage. The latter can only store objects as values, but keeps those objects visible at their ID in external storage.
Tables
module iota::table {
public struct Table<K: copy + drop + store, V: store> has key, store { /* ... */ }
public fun new<K: copy + drop + store, V: store>(
ctx: &mut TxContext,
): Table<K, V>;
}
Table<K, V> is a homogeneous map, meaning that all its keys have the same type as each other (K), and all its values have the same type as each other as well (V). It is created with iota::table::new, which requires access to a &mut TxContext because Tables are objects themselves, which can be transferred, shared, wrapped, or unwrapped, just like any other object.
See iota::object_table::ObjectTable for the object-preserving version of Table.
Bags
module iota::bag {
public struct Bag has key, store { /* ... */ }
public fun new(ctx: &mut TxContext): Bag;
}
Bag is a heterogeneous map, so it can hold key-value pairs of arbitrary types (they don't need to match each other). Note that the Bag type does not have any type parameters for this reason. Like Table, Bag is also an object, so creating one with iota::bag::new requires supplying a &mut TxContext to generate an ID.
See iota::bag::ObjectBag for the object-preserving version of Bag.
The following sections explain the collection APIs. They use iota::table as the basis for code examples, with explanations where other modules differ.
Interacting with collections
All collection types come with the following functions, defined in their respective modules:
module iota::table {
public fun add<K: copy + drop + store, V: store>(
table: &mut Table<K, V>,
k: K,
v: V,
);
public fun borrow<K: copy + drop + store, V: store>(
table: &Table<K, V>,
k: K
): &V;
public fun borrow_mut<K: copy + drop + store, V: store>(
table: &mut Table<K, V>,
k: K
): &mut V;
public fun remove<K: copy + drop + store, V: store>(
table: &mut Table<K, V>,
k: K,
): V;
}
These functions add, read, write, and remove entries from the collection, respectively, and all accept keys by value. Table has type parameters for K and V so it is not possible to call these functions with different instantiations of K and V on the same instance of Table, however Bag does not have these type parameters, and so does permit calls with different instantiations on the same instance.
Like with dynamic fields, it is an error to attempt to overwrite an existing key, or access or remove a non-existent key.
The extra flexibility of Bag's heterogeneity means the type system doesn't statically prevent attempts to add a value with one type, and then borrow or remove it at another type. This pattern fails at runtime, similar to the behavior for dynamic fields.
Querying length
It is possible to query all collection types for their length and check whether they are empty using the following family of functions:
module iota::table {
public fun length<K: copy + drop + store, V: store>(
table: &Table<K, V>,
): u64;
public fun is_empty<K: copy + drop + store, V: store>(
table: &Table<K, V>
): bool;
}
Bag has these functions, but they are not generic on K and V because Bag does not have these type parameters.
Querying for containment
Tables can be queried for key containment with:
module iota::table {
public fun contains<K: copy + drop + store, V: store>(
table: &Table<K, V>
k: K
): bool;
}
The equivalent functions for Bag are:
module iota::bag {
public fun contains<K: copy + drop + store>(bag: &Bag, k: K): bool;
public fun contains_with_type<K: copy + drop + store, V: store>(
bag: &Bag,
k: K
): bool;
}
The first function tests whether bag contains a key-value pair with key k: K, and the second function additionally tests whether its value has type V.
Clean-up
Collection types protect against accidental deletion when they might not be empty. This protection comes from the fact that they do not have drop, so must be explicitly deleted, using this API:
module iota::table {
public fun destroy_empty<K: copy + drop + store, V: store>(
table: Table<K, V>,
);
}
This function takes the collection by value. If it contains no entries, it is deleted, otherwise the call fails. iota::table::Table also has a convenience function:
module iota::table {
public fun drop<K: copy + drop + store, V: drop + store>(
table: Table<K, V>,
);
}
You can call the convenience function only for tables where the value type also has drop ability, which allows it to delete tables whether they are empty or not.
Note that drop is not called implicitly on eligible tables before they go out of scope. It must be called explicitly, but it is guaranteed to succeed at runtime.
Bag and ObjectBag cannot support drop because they could be holding a variety of types, some of which may have drop and some which may not.
ObjectTable does not support drop because its values must be objects, which cannot be dropped (because they must contain an id: UID field and UID does not have drop).
Equality
Equality on collections is based on identity, for example, an instance of a collection type is only considered equal to itself and not to all collections that hold the same entries:
let t1 = iota::table::new<u64, u64>(ctx);
let t2 = iota::table::new<u64, u64>(ctx);
assert!(&t1 == &t1, 0);
assert!(&t1 != &t2, 1);
This is unlikely to be the definition of equality that you want.