Module 0x2::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
- Resource
Field
- Constants
- Function
add
- Function
borrow
- Function
borrow_mut
- Function
remove
- Function
exists_
- Function
remove_if_exists
- Function
exists_with_type
- 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
use 0x1::option;
use 0x2::object;
Resource Field
Internal object used for storing the field and value
struct Field<Name: copy, drop, store, Value: store> has key
Fields
Constants
Failed to serialize the field's name
const EBCSSerializationFailure: u64 = 3;
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;
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 object::UID, name: Name, value: Value)
Implementation
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: &object::UID, name: Name): &Value
Implementation
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 object::UID, name: Name): &mut Value
Implementation
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 object::UID, name: Name): Value
Implementation
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: &object::UID, name: Name): bool
Implementation
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 object::UID, name: Name): option::Option<Value>
Implementation
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: &object::UID, name: Name): bool
Implementation
Function field_info
public(friend) fun field_info<Name: copy, drop, store>(object: &object::UID, name: Name): (&object::UID, address)
Implementation
Function field_info_mut
public(friend) fun field_info_mut<Name: copy, drop, store>(object: &mut object::UID, name: Name): (&mut object::UID, address)
Implementation
Function hash_type_and_key
May abort with EBCSSerializationFailure.
public(friend) fun hash_type_and_key<K: copy, drop, store>(parent: address, k: K): address
Implementation
Function add_child_object
public(friend) fun add_child_object<Child: key>(parent: address, child: Child)
Implementation
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(friend) fun borrow_child_object<Child: key>(object: &object::UID, id: address): &Child
Implementation
Function borrow_child_object_mut
public(friend) fun borrow_child_object_mut<Child: key>(object: &mut object::UID, id: address): &mut Child
Implementation
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(friend) fun remove_child_object<Child: key>(parent: address, id: address): Child
Implementation
Function has_child_object
public(friend) fun has_child_object(parent: address, id: address): bool
Implementation
Function has_child_object_with_ty
public(friend) fun has_child_object_with_ty<Child: key>(parent: address, id: address): bool