playbook/skills/tsl-api-reference/references/codegen/builtin/object.md

Builtin - 对象

createObject(class_name, ...)

声明：function

创建一个已在 TSL 语言中注册的对象，类名或类类型无效时调用出错

参数	类型	说明
class_name	string|classtype	已注册的对象类名，或通过 class()、findClass() 获得的类类型
...	any	可选。按顺序传给类构造函数的参数

返回：tslobject

示例

范例01：向构造函数传递参数

obj := createObject('CreationExample', 42);
echo obj.value, "\n";

type CreationExample = class
public
    value;
    function create(initial_value);
    begin
        value := initial_value;
    end;
end;
// 输出：42

findClass(class_name)

声明：function

按名称查找类，找不到时返回 0

参数	类型	说明
class_name	string	类名称

返回：tclass|integer

示例

范例01：查找脚本中声明的类

class_value := findClass("DemoClass");
echo class_value <> 0;
// 输出：1

type DemoClass = class
end;

findClass(class_name, obj)

声明：function

将对象转换为指定类，类不匹配时返回 0

参数	类型	说明
class_name	string	类名称
obj	object	要转换的对象

返回：object|integer

示例

范例01：转换为指定类

obj := new DemoClass();
typed_obj := findClass("DemoClass", obj);
echo typed_obj <> 0;
// 输出：1

type DemoClass = class
end;

objectstate(obj_name)

声明：function

返回对象当前所处的生命周期状态

参数	类型	说明
obj_name	object	要检查状态的对象

返回：integer

状态编码：1 表示构造中，2 表示构造完成，3 表示析构中，4 表示析构完成，0 表示未知状态，-1 表示参数不是对象

示例

obj := new StateProbe("ready");
echo objectstate(obj), "\n";

type StateProbe = class
public
    function create(value);
    begin
        echo objectstate(self), "\n";
    end;
end;
// 输出：1
// 输出：2

tslObjects(type)

声明：function

获取当前运行环境中 TSL 对象的引用信息，可选取回对象本身

参数	类型	说明
type	boolean	0 只返回引用计数，1 同时返回对象本身

返回：array|tablearray

返回结果按类名分组，每个对象包含 refs、orefs 字段；type 为 1 时还包含 obj 字段

示例

first := new ObjectProbe(100);
second := new ObjectProbe(101);
objects := tslObjects(1);
echo length(objects["ObjectProbe"]), "\n";
restored := objects["ObjectProbe"][0, "obj"];
echo restored is class(ObjectProbe), "\n";
echo restored.add(1, 2), "\n";

type ObjectProbe = class
public
    value;
    function create(initial_value);
    begin
        value := initial_value;
    end;
    class function add(a, b);
    begin
        return a + b;
    end;
end;
// 输出：2
// 输出：1
// 输出：3

makeWeakRef(obj)

声明：function

为对象或函数创建弱引用，不支持的类型会抛出异常

参数	类型	说明
obj	object|function	支持弱引用的对象或函数

返回：weak_object

示例

范例01：创建对象的弱引用

source := new TStringList();
source.append("A");
weak := makeWeakRef(source);
echo checkWeakRef(weak), "\n";
// 输出：1

makeWeakRef(obj, result)

声明：function

尝试为对象或函数创建弱引用，并通过输出参数报告是否成功

参数	类型	说明
obj	object|function	要创建弱引用的对象或函数
result	boolean	输出变量，创建成功时为真值

返回：weak_object

示例

范例01：处理不支持弱引用的值

weak := makeWeakRef(10, result);
echo result, "\n";
// 输出：0

weakRef(obj)

声明：function

为对象或函数创建弱引用，是 makeWeakRef 的别名

参数	类型	说明
obj	object|function	支持弱引用的对象或函数

返回：weak_object

示例

范例01：通过弱引用访问对象

source := new TStringList();
source.append("A");
weak := weakRef(source);
weak.append("B");
echo weak.commaText, "\n";
// 输出：A,B

weakRef(obj, result)

声明：function

尝试为对象或函数创建弱引用，并通过输出参数报告是否成功

参数	类型	说明
obj	object|function	要创建弱引用的对象或函数
result	boolean	输出变量，创建成功时为真值

返回：weak_object

示例

范例01：处理不支持弱引用的值

weak := weakRef(10, result);
echo result, "\n";
// 输出：0

makeStrongRef(weak_obj)

声明：function

从有效弱引用取得强引用，弱引用已经失效时会抛出异常

参数	类型	说明
weak_obj	weak_object	有效弱引用

返回：object

示例

范例01：从弱引用取得强引用

source := new TStringList();
source.append("A");
weak := weakRef(source);
strong := makeStrongRef(weak);
strong.append("B");
echo strong.commaText, "\n";
// 输出：A,B

makeStrongRef(weak_obj, result)

声明：function

尝试从弱引用取得强引用，并通过输出参数报告是否成功

参数	类型	说明
weak_obj	weak_object	要转换的弱引用
result	boolean	输出变量，转换成功时为真值

返回：object

示例

范例01：安全取得强引用

source := new TStringList();
source.append("A");
weak := weakRef(source);
strong := makeStrongRef(weak, result);
echo result, ",", strong.commaText, "\n";
// 输出：1,A

weakref_get(weak_obj)

声明：function

从有效弱引用取得强引用，是 makeStrongRef 的别名

参数	类型	说明
weak_obj	weak_object	有效弱引用

返回：object

示例

范例01：从弱引用取得强引用

source := new TStringList();
source.append("A");
weak := weakRef(source);
strong := weakref_get(weak);
strong.append("B");
echo strong.commaText, "\n";
// 输出：A,B

weakref_get(weak_obj, result)

声明：function

尝试从弱引用取得强引用，并通过输出参数报告是否成功

参数	类型	说明
weak_obj	weak_object	要转换的弱引用
result	boolean	输出变量，转换成功时为真值

返回：object

示例

范例01：安全取得强引用

source := new TStringList();
source.append("A");
weak := weakRef(source);
strong := weakref_get(weak, result);
echo result, ",", strong.commaText, "\n";
// 输出：1,A

checkWeakRef(weak_obj)

声明：function

返回弱引用的引用计数，有效对象已释放时返回 -1，参数不是弱引用时返回 -2

参数	类型	说明
weak_obj	weak_object	要检查的弱引用

返回：integer

示例

范例01：检查有效弱引用

source := new TStringList();
weak := weakRef(source);
echo checkWeakRef(weak), "\n";
// 输出：1

weakref_check(weak_obj)

声明：function

返回弱引用的引用计数，是 checkWeakRef 的别名

参数	类型	说明
weak_obj	weak_object	要检查的弱引用

返回：integer

示例

范例01：检查有效弱引用

source := new TStringList();
weak := weakRef(source);
echo weakref_check(weak), "\n";
// 输出：1