Module table.move

Function: new

This function can be used to create a new table. Note that this is the only function that allows to create a table object. Therefore, other generic functions in this module do not normally require to constrain the type of the table key/values, as table objects are guaranteed to have been created using types that have, respectively, copy + drop and store.

Inputs

• Type K<copy + drop>

  • Validation: No additional validation required besides ability constraints.

  • Impact: Type of the keys used to address elements of the table.

• Type V<store>

  • Validation: No additional validation required besides ability constraints.

  • Impact: Type of the values stored in the table.

Function: destroy_empty

This function can be used to destroy an empty table.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table: Table<K, V>

  • Validation: The table is checked to be empty.

  • Impact: Table to be deleted.

Function: add

This function can be used to add an element to a table. The function reverts if an element is already associated to the given key.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table: &Table<K, V>

  • Validation: None required.

  • Impact: Table to which an element is to be added.

• key: K

  • Validation: Table must not contain an entry at the same key.

  • Impact: Key at which the new element is associated.

• val: V

  • Validation: None required.

  • Impact: Element to add to the table.

Functions: borrow, borrow_mut

These functions can be used to get a reference (immutable or mutable) to an element of the table. The function reverts if there is no element associated with the given key.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table: &Table<K, V>

  • Validation: None required.

  • Impact: Table to borrow from.

• key: K

  • Validation: An element associated with this key must exist.

  • Impact: Key identifying which element to borrow.

Functions: borrow_with_default, borrow_mut_with_default

These functions can be used to get a reference (immutable or mutable) to an element of the given table. Unlike their borrow/borrow_mut counterpart, they allow to specify a default value to be used if the table does not contain an element associated with the given key.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table: &Table<K, V>

  • Validation: None required.

  • Impact: Table to borrow from.

• key: K

  • Validation: An element associated with this key must exist.

  • Impact: Key identifying which element to borrow.

• default: &V

  • Validation: None required.

  • Impact: Default value used if no element is associated with the given key.

Function: length

This function can be used to get the length of a table.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table: &Table<K, V>

  • Validation: None required.

  • Impact: Table to operate on.

Function: empty

This function can be used to determine whether a table is empty or not.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table: &Table<K, V>

  • Validation: None required.

  • Impact: Table to operate on.

Function: upsert

This function can be used to perform an upsert operation on a table, inserting an element into the table and discarding the existing value associated with the given key if such a value already exists.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V<drop>

  • Validation: Importantly, this function ensures that the value has drop, preventing an element without the ability from being silently discarded.

  • Impact: Type of the table values.

• table: &Table<K, V>

  • Validation: None required.

  • Impact: Table to operate on.

• key: K

  • Validation: None required.

  • Impact: Key that identifies the table position where the value is inserted (and the old value removed when applicable).

• value: V

  • Validation: None required.

  • Impact: Value to be inserted into the table.

Function: remove

This function can be used to remove an element from a table.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table: &Table<K, V>

  • Validation: None required.

  • Impact: Table to operate on.

• key: K

  • Validation: None required.

  • Impact: Identifies the element to be removed.

Function: contains

This function can be used to check whether a table contains an element associated with a given key.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table: &Table<K, V>

  • Validation: None required.

  • Impact: Table to operate on.

• key: K

  • Validation: None required.

  • Impact: Key value to test.

Functions: iter, iter_mut

These functions can be used to create an object that allows to iterate on the keys and values contained in the table, in a mutable and immutable fashion. Note that these functions were involved in Finding ref↗, which allowed to bypass critical security invariants, including the reference safety verifier. They were changed to remediate the vulnerability.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table: &Table<K, V>

  • Validation: None required.

  • Impact: Table to operate on.

• start: Option<K>

  • Validation: None required.

  • Impact: Start point for the iterator. The start is exclusive.

• end: Option<K>

  • Validation: None required.

  • Impact: End point for the iterator. The end point is inclusive.

• order: u8

  • Validation: Must be either 1 or 2.

  • Impact: Determines whether the iteration has to occur in ascending or descending order.

Functions: prepare, prepare_mut

This function must be used to prepare an iterator before obtaining the next element. It returns a boolean that tells if the iterator can yield another element.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table_iter: &TableIter<K, V>

  • Validation: None required.

  • Impact: Iterator to prepare.

Functions: next, next_mut

This function can be used to obtain the next element from an iterator. It returns the key and a reference (mutable or immutable) to the table value.

Inputs

• Type K<copy + drop>

  • Validation: None required.

  • Impact: Type of the table keys.

• Type V

  • Validation: None required.

  • Impact: Type of the table values.

• table_iter: &TableIter<K, V>/&mut TableIter<K, V>

  • Validation: None required.

  • Impact: Table iterator to act on.