Module sui::dynamic_field

In addition to the fields declared in its type definition, a Sui object can have dynamic fields that can be added after the object has been constructed. Unlike ordinary field names (which are always statically declared identifiers) a dynamic field name can be any value with the copy, drop, and store abilities, e.g. an integer, a boolean, or a string.
This gives Sui programmers the flexibility to extend objects on-the-fly, and it also serves as a building block for core collection types

use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::vector;
use sui::address;
use sui::hex;
use sui::object;
use sui::tx_context;

Struct Field

Internal object used for storing the field and value

public struct Field<Name: copy, drop, store, Value: store> has key

Click to open

Fields

id: sui::object::UID: Determined by the hash of the object ID, the field name value and it's type, i.e. hash(parent.id || name || Name)
name: Name: The value for the name of this field
value: Value: The value bound to this field

Constants

The object already has a dynamic field with this name (with the value and type specified)

const EFieldAlreadyExists: u64 = 0;

Cannot load dynamic field.
The object does not have a dynamic field with this name (with the value and type specified)

const EFieldDoesNotExist: u64 = 1;

The object has a field with that name, but the value type does not match

const EFieldTypeMismatch: u64 = 2;

Failed to serialize the field's name

const EBCSSerializationFailure: u64 = 3;

The object added as a dynamic field was previously a shared object

const ESharedObjectOperationNotSupported: u64 = 4;

Function add

Adds a dynamic field to the object object: &mut UID at field specified by name: Name.
Aborts with EFieldAlreadyExists if the object already has that field with that name.

public fun add<Name: copy, drop, store, Value: store>(object: &mut sui::object::UID, name: Name, value: Value)

Function borrow

Immutably borrows the objects dynamic field with the name specified by name: Name.
Aborts with EFieldDoesNotExist if the object does not have a field with that name.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public fun borrow<Name: copy, drop, store, Value: store>(object: &sui::object::UID, name: Name): &Value

Function borrow_mut

Mutably borrows the objects dynamic field with the name specified by name: Name.
Aborts with EFieldDoesNotExist if the object does not have a field with that name.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public fun borrow_mut<Name: copy, drop, store, Value: store>(object: &mut sui::object::UID, name: Name): &mut Value

Function remove

Removes the objects dynamic field with the name specified by name: Name and returns the bound value.
Aborts with EFieldDoesNotExist if the object does not have a field with that name.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public fun remove<Name: copy, drop, store, Value: store>(object: &mut sui::object::UID, name: Name): Value

Function exists

Returns true if and only if the object has a dynamic field with the name specified by name: Name but without specifying the Value type

public fun exists<Name: copy, drop, store>(object: &sui::object::UID, name: Name): bool

Function remove_opt

Removes the dynamic field if it exists. Returns some(Value) if it exists or none otherwise.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public fun remove_opt<Name: copy, drop, store, Value: store>(object: &mut sui::object::UID, name: Name): std::option::Option<Value>

Function replace

Removes the existing value at name (if any) and adds value in its place.
Returns the old value if it existed, or none otherwise.
Note: the old and new value types may differ.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified ValueOld type.

public fun replace<Name: copy, drop, store, ValueNew: store, ValueOld: store>(object: &mut sui::object::UID, name: Name, value: ValueNew): std::option::Option<ValueOld>

Function exists_with_type

Returns true if and only if the object has a dynamic field with the name specified by name: Name with an assigned value of type Value.

public fun exists_with_type<Name: copy, drop, store, Value: store>(object: &sui::object::UID, name: Name): bool

Macro function borrow_or_add

Immutably borrows the field value, adding it with $default if it doesn't exist.
Note that $default is evaluated only if the field does not already exist.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public macro fun borrow_or_add<$Name: copy, drop, store, $Value: store>($object: &mut sui::object::UID, $name: $Name, $default: $Value): &$Value

Macro function borrow_mut_or_add

Mutably borrows the field value, adding it with $default if it doesn't exist.
Note that $default is evaluated only if the field does not already exist.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public macro fun borrow_mut_or_add<$Name: copy, drop, store, $Value: store>($object: &mut sui::object::UID, $name: $Name, $default: $Value): &mut $Value

Macro function get_do

If the field exists, calls $f on an immutable reference to the value; otherwise, does nothing.
This is like getting an Option<&Value> then calling std::option::do.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public macro fun get_do<$Name: copy, drop, store, $Value: store, $R: drop>($object: &sui::object::UID, $name: $Name, $f: |&$Value| -> $R)

Macro function get_mut_do

If the field exists, calls $f on a mutable reference to the value; otherwise, does nothing.
This is like getting an Option<&mut Value> then calling std::option::do.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public macro fun get_mut_do<$Name: copy, drop, store, $Value: store, $R: drop>($object: &mut sui::object::UID, $name: $Name, $f: |&mut $Value| -> $R)

Macro function get_fold

If the field exists, applies $some to an immutable reference to the value; otherwise, returns $none.
This is like getting an Option<&Value> then calling std::option::fold.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public macro fun get_fold<$Name: copy, drop, store, $Value: store, $R>($object: &sui::object::UID, $name: $Name, $none: $R, $some: |&$Value| -> $R): $R

Macro function get_mut_fold

If the field exists, applies $some to a mutable reference to the value; otherwise, returns $none.
This is like getting an Option<&mut Value> then calling std::option::fold.
Aborts with EFieldTypeMismatch if the field exists, but the value does not have the specified type.

public macro fun get_mut_fold<$Name: copy, drop, store, $Value: store, $R>($object: &mut sui::object::UID, $name: $Name, $none: $R, $some: |&mut $Value| -> $R): $R

Function exists_

public fun exists_<Name: copy, drop, store>(object: &sui::object::UID, name: Name): bool

Function remove_if_exists

public fun remove_if_exists<Name: copy, drop, store, Value: store>(object: &mut sui::object::UID, name: Name): std::option::Option<Value>

Function field_info

public(package) fun field_info<Name: copy, drop, store>(object: &sui::object::UID, name: Name): (&sui::object::UID, address)

Function field_info_mut

public(package) fun field_info_mut<Name: copy, drop, store>(object: &mut sui::object::UID, name: Name): (&mut sui::object::UID, address)

Function hash_type_and_key

May abort with EBCSSerializationFailure.

public(package) fun hash_type_and_key<K: copy, drop>(parent: address, k: K): address

Function add_child_object

public(package) fun add_child_object<Child: key>(parent: address, child: Child)

Function borrow_child_object

throws EFieldDoesNotExist if a child does not exist with that ID or throws EFieldTypeMismatch if the type does not match, and may also abort with EBCSSerializationFailure we need two versions to return a reference or a mutable reference

public(package) fun borrow_child_object<Child: key>(object: &sui::object::UID, id: address): &Child

Function borrow_child_object_mut

public(package) fun borrow_child_object_mut<Child: key>(object: &mut sui::object::UID, id: address): &mut Child

Function remove_child_object

throws EFieldDoesNotExist if a child does not exist with that ID or throws EFieldTypeMismatch if the type does not match, and may also abort with EBCSSerializationFailure.

public(package) fun remove_child_object<Child: key>(parent: address, id: address): Child

Function has_child_object

public(package) fun has_child_object(parent: address, id: address): bool

Function has_child_object_with_ty

public(package) fun has_child_object_with_ty<Child: key>(parent: address, id: address): bool

Struct Field​

Constants​

Function add​

Function borrow​

Function borrow_mut​

Function remove​

Function exists​

Function remove_opt​

Function replace​

Function exists_with_type​

Macro function borrow_or_add​

Macro function borrow_mut_or_add​

Macro function get_do​

Macro function get_mut_do​

Macro function get_fold​

Macro function get_mut_fold​

Function exists_​

Function remove_if_exists​

Function field_info​

Function field_info_mut​

Function hash_type_and_key​

Function add_child_object​

Function borrow_child_object​

Function borrow_child_object_mut​

Function remove_child_object​

Function has_child_object​

Function has_child_object_with_ty​