434 lines
9.8 KiB
Markdown
434 lines
9.8 KiB
Markdown
# Builtin - 对象
|
|
|
|
## `createObject(class_name, ...)`
|
|
|
|
声明：function
|
|
|
|
创建一个已在 TSL 语言中注册的对象，类名或类类型无效时调用出错
|
|
|
|
<!-- tags: 对象 创建 实例 类 生成 object -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ------------ | ----------------- | -------------------------------------------------------------- |
|
|
| `class_name` | string\|classtype | 已注册的对象类名，或通过 `class()`、`findClass()` 获得的类类型 |
|
|
| `...` | any | 可选。按顺序传给类构造函数的参数 |
|
|
|
|
返回：tslobject
|
|
|
|
### 示例
|
|
|
|
范例01：向构造函数传递参数
|
|
|
|
```tsl
|
|
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`
|
|
|
|
<!-- tags: 对象 查找 搜索 lookup 获取 查询 实例 object -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ------------ | ------ | ------ |
|
|
| `class_name` | string | 类名称 |
|
|
|
|
返回：tclass\|integer
|
|
|
|
### 示例
|
|
|
|
范例01：查找脚本中声明的类
|
|
|
|
```tsl
|
|
class_value := findClass("DemoClass");
|
|
echo class_value <> 0;
|
|
// 输出：1
|
|
|
|
type DemoClass = class
|
|
end;
|
|
```
|
|
|
|
## `findClass(class_name, obj)`
|
|
|
|
声明：function
|
|
|
|
将对象转换为指定类，类不匹配时返回 `0`
|
|
|
|
<!-- tags: 对象 查找 搜索 lookup 转换 编码 实例 object -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ------------ | ------ | ------------ |
|
|
| `class_name` | string | 类名称 |
|
|
| `obj` | object | 要转换的对象 |
|
|
|
|
返回：object\|integer
|
|
|
|
### 示例
|
|
|
|
范例01：转换为指定类
|
|
|
|
```tsl
|
|
obj := new DemoClass();
|
|
typed_obj := findClass("DemoClass", obj);
|
|
echo typed_obj <> 0;
|
|
// 输出：1
|
|
|
|
type DemoClass = class
|
|
end;
|
|
```
|
|
|
|
## `objectstate(obj_name)`
|
|
|
|
声明：function
|
|
|
|
返回对象当前所处的生命周期状态
|
|
|
|
<!-- tags: 对象 状态 生命周期 构造 析构 运行时 introspection object -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ---------- | ------ | ---------------- |
|
|
| `obj_name` | object | 要检查状态的对象 |
|
|
|
|
返回：integer
|
|
|
|
状态编码：`1` 表示构造中，`2` 表示构造完成，`3` 表示析构中，`4` 表示析构完成，`0` 表示未知状态，`-1` 表示参数不是对象
|
|
|
|
### 示例
|
|
|
|
```tsl
|
|
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 对象的引用信息，可选取回对象本身
|
|
|
|
<!-- tags: 对象 枚举 引用计数 生命周期 运行时 introspection object -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ------ | ------- | ---------------------------------------- |
|
|
| `type` | boolean | `0` 只返回引用计数，`1` 同时返回对象本身 |
|
|
|
|
返回：array\|tablearray
|
|
|
|
返回结果按类名分组，每个对象包含 `refs`、`orefs` 字段；`type` 为 `1` 时还包含 `obj` 字段
|
|
|
|
### 示例
|
|
|
|
```tsl
|
|
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
|
|
|
|
为对象或函数创建弱引用，不支持的类型会抛出异常
|
|
|
|
<!-- tags: 对象 弱引用 引用计数 生命周期 weak reference -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ----- | ---------------- | ---------------------- |
|
|
| `obj` | object\|function | 支持弱引用的对象或函数 |
|
|
|
|
返回：weak_object
|
|
|
|
### 示例
|
|
|
|
范例01：创建对象的弱引用
|
|
|
|
```tsl
|
|
source := new TStringList();
|
|
source.append("A");
|
|
weak := makeWeakRef(source);
|
|
echo checkWeakRef(weak), "\n";
|
|
// 输出：1
|
|
```
|
|
|
|
## `makeWeakRef(obj, result)`
|
|
|
|
声明：function
|
|
|
|
尝试为对象或函数创建弱引用，并通过输出参数报告是否成功
|
|
|
|
<!-- tags: 对象 弱引用 安全创建 输出参数 weak reference try -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| -------- | ---------------- | -------------------------- |
|
|
| `obj` | object\|function | 要创建弱引用的对象或函数 |
|
|
| `result` | boolean | 输出变量，创建成功时为真值 |
|
|
|
|
返回：weak_object
|
|
|
|
### 示例
|
|
|
|
范例01：处理不支持弱引用的值
|
|
|
|
```tsl
|
|
weak := makeWeakRef(10, result);
|
|
echo result, "\n";
|
|
// 输出：0
|
|
```
|
|
|
|
## `weakRef(obj)`
|
|
|
|
声明：function
|
|
|
|
为对象或函数创建弱引用，是 `makeWeakRef` 的别名
|
|
|
|
<!-- tags: 对象 弱引用 引用计数 生命周期 weak reference alias -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ----- | ---------------- | ---------------------- |
|
|
| `obj` | object\|function | 支持弱引用的对象或函数 |
|
|
|
|
返回：weak_object
|
|
|
|
### 示例
|
|
|
|
范例01：通过弱引用访问对象
|
|
|
|
```tsl
|
|
source := new TStringList();
|
|
source.append("A");
|
|
weak := weakRef(source);
|
|
weak.append("B");
|
|
echo weak.commaText, "\n";
|
|
// 输出：A,B
|
|
```
|
|
|
|
## `weakRef(obj, result)`
|
|
|
|
声明：function
|
|
|
|
尝试为对象或函数创建弱引用，并通过输出参数报告是否成功
|
|
|
|
<!-- tags: 对象 弱引用 安全创建 输出参数 weak reference try alias -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| -------- | ---------------- | -------------------------- |
|
|
| `obj` | object\|function | 要创建弱引用的对象或函数 |
|
|
| `result` | boolean | 输出变量，创建成功时为真值 |
|
|
|
|
返回：weak_object
|
|
|
|
### 示例
|
|
|
|
范例01：处理不支持弱引用的值
|
|
|
|
```tsl
|
|
weak := weakRef(10, result);
|
|
echo result, "\n";
|
|
// 输出：0
|
|
```
|
|
|
|
## `makeStrongRef(weak_obj)`
|
|
|
|
声明：function
|
|
|
|
从有效弱引用取得强引用，弱引用已经失效时会抛出异常
|
|
|
|
<!-- tags: 对象 强引用 弱引用 恢复 获取 weak strong reference -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ---------- | ----------- | ---------- |
|
|
| `weak_obj` | weak_object | 有效弱引用 |
|
|
|
|
返回：object
|
|
|
|
### 示例
|
|
|
|
范例01：从弱引用取得强引用
|
|
|
|
```tsl
|
|
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
|
|
|
|
尝试从弱引用取得强引用，并通过输出参数报告是否成功
|
|
|
|
<!-- tags: 对象 强引用 弱引用 安全获取 输出参数 weak strong reference try -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ---------- | ----------- | -------------------------- |
|
|
| `weak_obj` | weak_object | 要转换的弱引用 |
|
|
| `result` | boolean | 输出变量，转换成功时为真值 |
|
|
|
|
返回：object
|
|
|
|
### 示例
|
|
|
|
范例01：安全取得强引用
|
|
|
|
```tsl
|
|
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` 的别名
|
|
|
|
<!-- tags: 对象 强引用 弱引用 恢复 获取 weak strong reference alias -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ---------- | ----------- | ---------- |
|
|
| `weak_obj` | weak_object | 有效弱引用 |
|
|
|
|
返回：object
|
|
|
|
### 示例
|
|
|
|
范例01：从弱引用取得强引用
|
|
|
|
```tsl
|
|
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
|
|
|
|
尝试从弱引用取得强引用，并通过输出参数报告是否成功
|
|
|
|
<!-- tags: 对象 强引用 弱引用 安全获取 输出参数 weak strong reference try alias -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ---------- | ----------- | -------------------------- |
|
|
| `weak_obj` | weak_object | 要转换的弱引用 |
|
|
| `result` | boolean | 输出变量，转换成功时为真值 |
|
|
|
|
返回：object
|
|
|
|
### 示例
|
|
|
|
范例01：安全取得强引用
|
|
|
|
```tsl
|
|
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`
|
|
|
|
<!-- tags: 对象 弱引用 检查 判断 引用计数 状态 weak reference -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ---------- | ----------- | -------------- |
|
|
| `weak_obj` | weak_object | 要检查的弱引用 |
|
|
|
|
返回：integer
|
|
|
|
### 示例
|
|
|
|
范例01：检查有效弱引用
|
|
|
|
```tsl
|
|
source := new TStringList();
|
|
weak := weakRef(source);
|
|
echo checkWeakRef(weak), "\n";
|
|
// 输出：1
|
|
```
|
|
|
|
## `weakref_check(weak_obj)`
|
|
|
|
声明：function
|
|
|
|
返回弱引用的引用计数，是 `checkWeakRef` 的别名
|
|
|
|
<!-- tags: 对象 弱引用 检查 判断 引用计数 状态 weak reference alias -->
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| ---------- | ----------- | -------------- |
|
|
| `weak_obj` | weak_object | 要检查的弱引用 |
|
|
|
|
返回：integer
|
|
|
|
### 示例
|
|
|
|
范例01：检查有效弱引用
|
|
|
|
```tsl
|
|
source := new TStringList();
|
|
weak := weakRef(source);
|
|
echo weakref_check(weak), "\n";
|
|
// 输出：1
|
|
```
|