Skip to content

Latest commit

 

History

History
982 lines (452 loc) · 31.3 KB

object.md

File metadata and controls

982 lines (452 loc) · 31.3 KB

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

#[data_struct]
struct ObjectID has copy, drop, store

Resource Object

Object is a pointer type to the Object in storage, It has key and store ability.

struct Object<T> has store, key

Resource DynamicField

The dynamic field

struct DynamicField<Name, Value> has store, key

Constants

The type of the object or field is mismatch

const ErrorTypeMismatch: u64 = 10;

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;

The object or field is already borrowed

const ErrorObjectAlreadyBorrowed: u64 = 7;

The object or field is already taken out or embedded in other struct

const ErrorObjectAlreadyTakenOutOrEmbeded: u64 = 15;


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 child_id

public(friend) fun child_id(parent_id: object::ObjectID, key: address): 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: key>(account: address): object::ObjectID

Function custom_object_id

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

Function custom_object_id_with_parent

public fun custom_object_id_with_parent<ID: copy, drop, store, T: key>(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: copy, drop, store, 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 new_with_parent

Create a new object under the parent object

#[private_generics(#[P], #[T])]
public fun new_with_parent<P: key, T: key>(parent: &mut object::Object<P>, value: T): object::Object<T>

Function new_with_parent_and_id

Create a new object under the parent object with custom ID, the ObjectID is generated by custom_object_id_with_parent

#[private_generics(#[P], #[T])]
public fun new_with_parent_and_id<P: key, ID: copy, drop, store, T: key>(parent: &mut object::Object<P>, id: ID, value: T): object::Object<T>

Function new_with_parent_and_key

public(friend) fun new_with_parent_and_key<P: key, T: key>(parent: &mut object::Object<P>, child_key: address, 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 Except the object is embedded in other struct

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, Only the module of T can borrow the Object<T> with object_id. Except the object is frozen or is embedded in other struct

#[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 Object by owner and object_id The T must have key + store ability.

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

Function take_object_extend

Take out the Object by object_id This function is for developer to extend, Only the module of T can call this function.

#[private_generics(#[T])]
public fun take_object_extend<T: key>(object_id: object::ObjectID): 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 module of T can call take_object_extend to take out the shared object, then remove the shared object.

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, No 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 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 is_system_owned

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

Function is_user_owned

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

Function add_field

Add a dynamic field 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, Name: copy, drop, store, Value: store>(obj: &mut object::Object<T>, name: Name, val: Value)

Function add_field_internal

public(friend) fun add_field_internal<Name: copy, drop, store, Value>(obj_id: object::ObjectID, name: Name, value: Value)

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, Name: copy, drop, store, Value: store>(obj: &object::Object<T>, name: Name): &Value

Function borrow_field_internal

Borrow FieldValue and return the val of FieldValue

public(friend) fun borrow_field_internal<Name: copy, drop, store, Value>(obj_id: object::ObjectID, name: Name): &Value

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, Name: copy, drop, store, Value: store>(obj: &object::Object<T>, name: Name, default: &Value): &Value

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, Name: copy, drop, store, Value: store>(obj: &mut object::Object<T>, name: Name): &mut Value

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<Name: copy, drop, store, Value>(obj_id: object::ObjectID, name: Name): &mut Value

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, Name: copy, drop, store, Value: drop, store>(obj: &mut object::Object<T>, name: Name, default: Value): &mut Value

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, Name: copy, drop, store, Value: drop, store>(obj: &mut object::Object<T>, name: Name, value: Value)

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, Name: copy, drop, store, Value: store>(obj: &mut object::Object<T>, name: Name): Value

Function remove_field_internal

public(friend) fun remove_field_internal<T: key, Name: copy, drop, store, Value>(obj_id: object::ObjectID, name: Name): Value

Function contains_field

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

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

Function contains_field_internal

public(friend) fun contains_field_internal<Name: copy, drop, store>(obj_id: object::ObjectID, name: Name): bool

Function contains_field_with_type

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

public fun contains_field_with_type<T: key, Name: copy, drop, store, Value: store>(obj: &object::Object<T>, name: Name): 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