Skip to content

Latest commit

 

History

History
1170 lines (535 loc) · 37.2 KB

object.md

File metadata and controls

1170 lines (535 loc) · 37.2 KB
Raw

Module 0x2::object

Move Object For more details, please refer to https://rooch.network/docs/developer-guides/object

use 0x1::hash;
use 0x1::string;
use 0x1::vector;
use 0x2::address;
use 0x2::bcs;
use 0x2::signer;
use 0x2::tx_context;
use 0x2::type_info;

Struct ObjectID

ObjectID is a unique identifier for the Object

struct ObjectID has copy, drop, store

Resource Root

struct Root has key

Struct ObjectEntity

ObjectEntity is a box of the value of T It does not have any ability, so it can not be drop, copy, or store, and can only be handled by storage API after creation.

struct ObjectEntity<T>

Resource Object

Object is a pointer to the ObjectEntity, It has key and store ability. It has the same lifetime as the ObjectEntity Developers only need to use Object related APIs and do not need to know the ObjectEntity.

struct Object<T> has store, key

Resource FieldValue

Wrapper for file values. Required for making values appear as struct in the implementation. Because the GlobalValue in MoveVM must be a struct.

struct FieldValue<V> has drop, store, key

Struct TestStructID

struct TestStructID has copy, drop, store

Constants

The type of the object or field is mismatch

const ErrorTypeMismatch: u64 = 10;


const BOUND_OBJECT_FLAG_MASK: u8 = 4;

The Object or dynamic field already exists

const ErrorAlreadyExists: u64 = 1;

The child object level is too deep

const ErrorChildObjectTooDeep: u64 = 11;

The dynamic fields is not empty

const ErrorFieldsNotEmpty: u64 = 8;


const ErrorInvalidOwnerAddress: u64 = 3;

Can not found the Object or dynamic field

const ErrorNotFound: u64 = 2;


const ErrorObjectAlreadyBorrowed: u64 = 7;


const ErrorObjectFrozen: u64 = 9;

Can not take out the object which is bound to the account

const ErrorObjectIsBound: u64 = 6;


const ErrorObjectNotShared: u64 = 5;


const ErrorObjectOwnerNotMatch: u64 = 4;

The object runtime error

const ErrorObjectRuntimeError: u64 = 14;

The parent object is not match

const ErrorParentNotMatch: u64 = 13;

The object has no parent

const ErrorWithoutParent: u64 = 12;


const FROZEN_OBJECT_FLAG_MASK: u8 = 2;


const SHARED_OBJECT_FLAG_MASK: u8 = 1;


const SPARSE_MERKLE_PLACEHOLDER_HASH: address = 0x5350415253455f4d45524b4c455f504c414345484f4c4445525f484153480000;


const SYSTEM_OWNER_ADDRESS: address = 0x0;

Function has_parent

Check if the object_id has parent The object_id has parent means the object_id is not the root object_id

public fun has_parent(object_id: &object::ObjectID): bool

Function parent_id

public fun parent_id(object_id: &object::ObjectID): object::ObjectID

Function is_parent

Check if the parent is the parent of the child

public fun is_parent(parent: &object::ObjectID, child: &object::ObjectID): bool

Function is_root

public fun is_root(object_id: &object::ObjectID): bool

Function address_to_object_id

Generate a new ObjectID from an address

public(friend) fun address_to_object_id(address: address): object::ObjectID

Function named_object_id

public fun named_object_id<T>(): object::ObjectID

Function account_named_object_id

public fun account_named_object_id<T>(account: address): object::ObjectID

Function custom_object_id

public fun custom_object_id<ID: drop, T>(id: ID): object::ObjectID

Function custom_child_object_id

public fun custom_child_object_id<ID: drop, T>(parent_id: object::ObjectID, id: ID): object::ObjectID

Function new

Create a new Object, Add the Object to the global object storage and return the Object

#[private_generics(#[T])]
public fun new<T: key>(value: T): object::Object<T>

Function new_with_id

Create a new object with custom ID, the ObjectID is generated by the id and type_name of T The caller must ensure that the id is unique

#[private_generics(#[T])]
public fun new_with_id<ID: drop, T: key>(id: ID, value: T): object::Object<T>

Function new_named_object

Create a new named Object, the ObjectID is generated by the type_name of T

#[private_generics(#[T])]
public fun new_named_object<T: key>(value: T): object::Object<T>

Function new_account_named_object

Create a new account named object, the ObjectID is generated by the account address and type_name of T

#[private_generics(#[T])]
public fun new_account_named_object<T: key>(account: address, value: T): object::Object<T>

Function new_with_object_id

public(friend) fun new_with_object_id<T: key>(id: object::ObjectID, value: T): object::Object<T>

Function borrow

Borrow the object value

public fun borrow<T: key>(self: &object::Object<T>): &T

Function borrow_mut

Borrow the object mutable value

public fun borrow_mut<T: key>(self: &mut object::Object<T>): &mut T

Function exists_object

Check if the object with object_id exists in the global object storage

public fun exists_object(object_id: object::ObjectID): bool

Function exists_object_with_type

Check if the object exists in the global object storage and the type of the object is T

public fun exists_object_with_type<T: key>(object_id: object::ObjectID): bool

Function borrow_object

Borrow Object from object store by object_id Any one can borrow an &Object<T> from the global object storage

public fun borrow_object<T: key>(object_id: object::ObjectID): &object::Object<T>

Function borrow_mut_object

Borrow mut Object by owner and object_id

public fun borrow_mut_object<T: key>(owner: &signer, object_id: object::ObjectID): &mut object::Object<T>

Function borrow_mut_object_extend

Borrow mut Object by object_id

#[private_generics(#[T])]
public fun borrow_mut_object_extend<T: key>(object_id: object::ObjectID): &mut object::Object<T>

Function take_object

Take out the UserOwnedObject by owner and object_id The T must have key + store ability. Note: When the Object is taken out, the Object will auto become SystemOwned Object.

public fun take_object<T: store, key>(owner: &signer, object_id: object::ObjectID): object::Object<T>

Function take_object_extend

Take out the UserOwnedObject by object_id, return the owner and Object This function is for developer to extend, Only the module of T can take out the UserOwnedObject with object_id.

#[private_generics(#[T])]
public fun take_object_extend<T: key>(object_id: object::ObjectID): (address, object::Object<T>)

Function borrow_mut_object_shared

Borrow mut Shared Object by object_id

public fun borrow_mut_object_shared<T: key>(object_id: object::ObjectID): &mut object::Object<T>

Function remove

Remove the object from the global storage, and return the object value This function is only can be called by the module of T. The caller must ensure that the dynamic fields are empty before delete the Object

#[private_generics(#[T])]
public fun remove<T: key>(self: object::Object<T>): T

Function remove_unchecked

Remove the object from the global storage, and return the object value Do not check if the dynamic fields are empty

public(friend) fun remove_unchecked<T: key>(self: object::Object<T>): T

Function to_shared

Make the Object shared, Any one can get the &mut Object from shared object The shared object also can be removed from the object storage.

public fun to_shared<T: key>(self: object::Object<T>)

Function is_shared

public fun is_shared<T: key>(self: &object::Object<T>): bool

Function to_frozen

Make the Object frozen, Any one can not get the &mut Object from frozen object

public fun to_frozen<T: key>(self: object::Object<T>)

Function is_frozen

public fun is_frozen<T: key>(self: &object::Object<T>): bool

Function is_bound

public fun is_bound<T: key>(self: &object::Object<T>): bool

Function is_bound_internal

public(friend) fun is_bound_internal<T>(self: &object::ObjectEntity<T>): bool

Function to_user_owned

public(friend) fun to_user_owned<T: key>(self: &mut object::Object<T>, new_owner: address)

Function to_system_owned

public(friend) fun to_system_owned<T: key>(self: &mut object::Object<T>)

Function to_system_owned_internal

public(friend) fun to_system_owned_internal<T>(self: &mut object::ObjectEntity<T>)

Function transfer

Transfer the object to the new owner Only the T with store can be directly transferred.

public fun transfer<T: store, key>(self: object::Object<T>, new_owner: address)

Function transfer_extend

Transfer the object to the new owner This function is for the module of T to extend the transfer function.

#[private_generics(#[T])]
public fun transfer_extend<T: key>(self: object::Object<T>, new_owner: address)

Function id

public fun id<T>(self: &object::Object<T>): object::ObjectID

Function owner

public fun owner<T: key>(self: &object::Object<T>): address

Function owner_internal

public(friend) fun owner_internal<T: key>(self: &object::ObjectEntity<T>): address

Function is_system_owned

public fun is_system_owned<T: key>(self: &object::Object<T>): bool

Function is_user_owned_internal

public(friend) fun is_user_owned_internal<T: key>(self: &object::ObjectEntity<T>): bool

Function is_user_owned

public fun is_user_owned<T: key>(self: &object::Object<T>): bool

Function as_ref

public(friend) fun as_ref<T: key>(object_entity: &object::ObjectEntity<T>): &object::Object<T>

Function as_mut_ref

public(friend) fun as_mut_ref<T: key>(object_entity: &mut object::ObjectEntity<T>): &mut object::Object<T>

Function mut_entity_as_object

public(friend) fun mut_entity_as_object<T: key>(object_entity: &mut object::ObjectEntity<T>): object::Object<T>

Function add_field

Add a dynamic filed to the object. Aborts if an field for this key already exists. The field itself is not stored in the object, and cannot be discovered from it.

#[private_generics(#[T])]
public fun add_field<T: key, K: copy, drop, V: store>(obj: &mut object::Object<T>, key: K, val: V)

Function add_field_internal

public(friend) fun add_field_internal<T: key, K: copy, drop, V>(obj_id: object::ObjectID, key: K, val: V)

Function add_object_field

Add a object field to the object. return the child object The parent object must be a shared object

#[private_generics(#[T], #[V])]
public fun add_object_field<T: key, V: key>(obj: &mut object::Object<T>, v: V): object::Object<V>

Function add_object_field_with_id

Add a object field to the object with custom ID. return the child object The child ObjectID can be generated via the custom_child_object_id function

#[private_generics(#[T], #[V])]
public fun add_object_field_with_id<T: key, ID: drop, V: key>(obj: &mut object::Object<T>, id: ID, v: V): object::Object<V>

Function borrow_field

Acquire an immutable reference to the value which key maps to. Aborts if there is no field for key.

public fun borrow_field<T: key, K: copy, drop, V: store>(obj: &object::Object<T>, key: K): &V

Function borrow_object_field

Borrow the child object by key

public fun borrow_object_field<T: key, V: key>(obj: &object::Object<T>, key: object::ObjectID): &object::Object<V>

Function borrow_field_internal

Borrow FieldValue and return the val of FieldValue

public(friend) fun borrow_field_internal<K: copy, drop, V>(obj_id: object::ObjectID, key: K): &V

Function borrow_field_with_default

Acquire an immutable reference to the value which key maps to. Returns specified default value if there is no field for key.

public fun borrow_field_with_default<T: key, K: copy, drop, V: store>(obj: &object::Object<T>, key: K, default: &V): &V

Function borrow_mut_field

Acquire a mutable reference to the value which key maps to. Aborts if there is no field for key.

#[private_generics(#[T])]
public fun borrow_mut_field<T: key, K: copy, drop, V: store>(obj: &mut object::Object<T>, key: K): &mut V

Function borrow_mut_field_internal

Acquire a mutable reference to the value which key maps to. Aborts if there is no field for key.

public(friend) fun borrow_mut_field_internal<K: copy, drop, V>(obj_id: object::ObjectID, key: K): &mut V

Function borrow_mut_field_with_default

Acquire a mutable reference to the value which key maps to. Insert the pair (key, default) first if there is no field for key.

#[private_generics(#[T])]
public fun borrow_mut_field_with_default<T: key, K: copy, drop, V: drop, store>(obj: &mut object::Object<T>, key: K, default: V): &mut V

Function borrow_mut_object_field

Borrow the child object by key Because the parent object must be a shared object, so we do not require the #[private_generics(T)] here

public fun borrow_mut_object_field<T: key, V: key>(obj: &mut object::Object<T>, key: object::ObjectID): &mut object::Object<V>

Function upsert_field

Insert the pair (key, value) if there is no field for key. update the value of the field for key to value otherwise

#[private_generics(#[T])]
public fun upsert_field<T: key, K: copy, drop, V: drop, store>(obj: &mut object::Object<T>, key: K, value: V)

Function remove_field

Remove from object and return the value which key maps to. Aborts if there is no field for key.

#[private_generics(#[T])]
public fun remove_field<T: key, K: copy, drop, V: store>(obj: &mut object::Object<T>, key: K): V

Function remove_field_internal

public(friend) fun remove_field_internal<T: key, K: copy, drop, V>(obj_id: object::ObjectID, key: K): V

Function remove_object_field

#[private_generics(#[T])]
public fun remove_object_field<T: key, V: key>(obj: &mut object::Object<T>, child: object::Object<V>): V

Function contains_field

Returns true if object contains an field for key, include normal field and object field

public fun contains_field<T: key, K: copy, drop>(obj: &object::Object<T>, key: K): bool

Function contains_field_internal

public(friend) fun contains_field_internal<K: copy, drop>(obj_id: object::ObjectID, key: K): bool

Function contains_field_with_type

Returns true if object contains an field for key and the value type is V. only for normal field

public fun contains_field_with_type<T: key, K: copy, drop, V: store>(obj: &object::Object<T>, key: K): bool

Function contains_object_field

Returns true if object contains an Object field for key and the value type is V.

public fun contains_object_field<T: key, V: key>(obj: &object::Object<T>, key: object::ObjectID): bool

Function field_size

Returns the size of the object fields, the number of key-value pairs

public fun field_size<T: key>(obj: &object::Object<T>): u64