Skip to main content

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_if_exists​

Removes the dynamic field if it exists. Returns the some(Value) if it exists or none otherwise.

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

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

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, store>(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