# Builtin - 运行时

## 运行时

## `setPrecision(number, precision)`

声明：function

从指定精度四舍五入截断小数点位数，返回number的保留小数点Precision位后的值

<!-- tags: 运行时 设置 修改 -->

| 参数        | 类型    | 说明                                       |
| ----------- | ------- | ------------------------------------------ |
| `number`    | real    | 实数/实数数组。                            |
| `precision` | integer | 整数，目的是为了截取实数后面小数点的位数。 |

返回：real

### 示例

范例01：保留三位小数

```tsl
echo setPrecision(123.4567, 3), "\n";
```

## `toStm(v, gtype, stm_type, p_n)`

声明：function

转换成为STM流数据。可以通过stmType参数控制是否转换为新流模式或超大流新流模式，新的stm流占用空间更少，访问效率更高

<!-- tags: 运行时 转换 编码 STM -->

| 参数       | 类型    | 说明                                                                                                       |
| ---------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `v`        |         | 任意类型数据                                                                                               |
| `gtype`    | integer | 可选。图型等特殊类型，默认为0                                                                              |
| `stm_type` | integer | 可选。流模式，0：普通模式；1：新流模式；2：超极大流的紧缩模式；默认为0。其中，超大流模式能处理超大结果集。 |
| `p_n`      | integer | 可选。精度，默认为-1，表示全精度                                                                           |

返回：binary

### 示例

范例01：将数组转换为 STM 后再还原

```tsl
stream := toStm(array(1, 2, 3));
echo toStn(stm(stream)), "\n";
```

## `toStn(v, n)`

声明：function

转换成为STN字符串。小数位四舍五入，尾数是五就进一

<!-- tags: 运行时 转换 编码 STN -->

| 参数 | 类型    | 说明                                                                  |
| ---- | ------- | --------------------------------------------------------------------- |
| `v`  | any     | 任意类型数据                                                          |
| `n`  | integer | 可选。整型，保留小数点后的位数。只对v是小数时且v的小数数位比N大有效。 |

返回：string

### 示例

范例01：将数值转换为 STN 字符串

```tsl
echo toStn(1.2345, 2), "\n";
```

## `exportCsv(data, csv_str, include_index, include_header)`

声明：function

将指定数组Data转换为csv格式字符串并存储在csvStr参数中。仅支持一维及二维数组的转换。和ExportCsvne的区别：在处理浮点数据时，ExportCsv的结果会输出为1E15等格式

<!-- tags: 运行时 转换 编码 -->

| 参数             | 类型   | 说明                                                        |
| ---------------- | ------ | ----------------------------------------------------------- |
| `data`           | array  | 数组类型，要转换成csv格式字符串的数组。                     |
| `csv_str`        | string | 字符串类型，转换成功的csv格式字符串（输出值）。             |
| `include_index`  | bool   | 可选。布尔类型。转换结果是否包含数组下标信息。默认为False。 |
| `include_header` | bool   | 可选。布尔类型。转换结果是否包含字段头部信息。默认为True。  |

返回：bool

### 示例

范例01：将二维数组转换为 CSV 字符串

```tsl
data := array(("name": "Tinysoft", "value": 1));
ok := exportCsv(data, csv_text);
echo ok, ":", csv_text, "\n";
```

## `setProfiler(flag)`

声明：function

设置需要记录的优化信息（当设置了记录优化信息的时候，运行速度可能会比正常运行慢很多）并返回设置前的状态值，如果设置了记录优化信息，在平台运行的模型结束的时候会在终端打开优化信息的窗口，用户也可以调用GetProfilerInfo来手动获得优化信息

<!-- tags: 运行时 设置 修改 -->

| 参数   | 类型 | 说明                                                                                                                        |
| ------ | ---- | --------------------------------------------------------------------------------------------------------------------------- |
| `flag` |      | 可选。整数，若省略则仅返回状态值而不设置。设置需要记录的优化信息，由一个四位二进制数组成，即以下几种常见组合说明: 取值 说明 |

返回：integer

### 示例

范例01：分析纯数值循环

```tsl
previous_flag := setProfiler(7);
sum := 0;
for i := 1 to 1000 do
    sum += i;
setProfiler(previous_flag);
echo sum, "\n";
```

## `randomfrom(avalues)`

声明：function

返回一个随机的数组元素，这个数组是由参数Avalue传递进来的

<!-- tags: 运行时 返回 获取 -->

| 参数      | 类型         | 说明                               |
| --------- | ------------ | ---------------------------------- |
| `avalues` | array of any | 数组名称，可以是整数数组或实数数组 |

返回：any

### 示例

范例01：从数组中随机选择元素

```tsl
candidates := array(10, 20, 30);
selected := randomFrom(candidates);
echo selected = 10 or selected = 20 or selected = 30, "\n";
// 输出：1
```

## `getSysParams()`

声明：function

获取所有系统参数的值

<!-- tags: 运行时 获取 查询 -->

返回：array

### 示例

范例01：读取全部系统参数

```tsl
echo toStn(getSysParams()), "\n";
```

## `call(func_name, p1, pn)`

声明：function

根据名称或者函数指针调用指定的函数，后面带的参数将自动送入该函数

<!-- tags: 运行时 -->

| 参数        | 类型              | 说明                                             |
| ----------- | ----------------- | ------------------------------------------------ |
| `func_name` | string\|tfunction | 如果是字符串，表示函数的名称，也可以是函数类型。 |
| `p1`        | any               | 整数，参数1                                      |
| `pn`        | any               | 整数，参数N。                                    |

返回：any

### 示例

范例01：按名称调用转换函数

```tsl
echo call("StrToIntDef", "123", 0), "\n";
```

## `callInArray(func_name, param_content)`

声明：function

根据名称或者函数指针调用指定的函数，将参数放入一个数组中送入该函数，不支持变参。另外，天软的函数指针可以用thisfunction()获得。该函数与call函数功能类似，注意两个函数设置参数的区别。Call函数直接列举，CallInArray函数将调用的函数的参数放在Array中

<!-- tags: 运行时 -->

| 参数            | 类型              | 说明                                                                         |
| --------------- | ----------------- | ---------------------------------------------------------------------------- |
| `func_name`     | string\|tfunction | 如果是字符串，表示函数名称，也可以是函数类型。                               |
| `param_content` | array             | 数组类型，第一个参数放在ParamContent[0]，第二个放在ParamContent[1]以此类推。 |

返回：any

### 示例

范例01：通过参数数组调用转换函数

```tsl
echo callInArray("StrToIntDef", array("123", 0)), "\n";
```

## `dupValue(value)`

声明：function

返回一份value的复制值，一般无需要使用，特别用于不需要变参的函数调用

<!-- tags: 运行时 返回 获取 -->

| 参数    | 类型 | 说明                   |
| ------- | ---- | ---------------------- |
| `value` | any  | 任意类型，被复制的数据 |

返回：any

### 示例

范例01：复制数组值

```tsl
source_values := array(1, 2);
copied_values := dupValue(source_values);
copied_values[0] := 9;
echo toStn(array(source_values, copied_values)), "\n";
```

## `eval(exp)`

声明：function

计算表达式并返回表达式的值。表达式可以引用当前作用域中的变量

<!-- tags: 运行时 计算 求解 -->

| 参数  | 类型        | 说明             |
| ----- | ----------- | ---------------- |
| `exp` | texpression | 要计算的表达式。 |

返回：any

### 示例

范例01：计算引用当前变量的语句表达式

```tsl
a := 1;
b := 2;
echo eval(@(a + b)), "\n";
// 输出：3
```

## `invoke(obj, member_name, member_value, p1, ..., pn)`

声明：function

按名称调用对象成员方法或设置成员属性，支持调用重载方法

<!-- tags: 运行时 -->

| 参数           | 类型      | 说明                                         |
| -------------- | --------- | -------------------------------------------- |
| `obj`          | tslobject | 实例对象。                                   |
| `member_name`  | string    | 成员方法或属性名称。                         |
| `member_value` | boolean   | 成员类型：0 表示方法，1 表示属性。           |
| `p1`           | any       | 设置属性时为属性值；调用方法时为第一个参数。 |
| `pn`           | any       | 可选。成员方法的后续参数。                   |

返回：any

设置属性时返回 0；调用方法时返回方法的执行结果。

### 示例

范例01：设置对象属性后调用成员方法

```tsl
obj := new RuntimeInvokeExample();
invoke(obj, "name", 1, "Tinysoft");
echo invoke(obj, "label", 0, "TSL"), "\n";
// 输出：TSL:Tinysoft

type RuntimeInvokeExample = class
public
    name;
    function label(prefix);
    begin
        return prefix + ":" + name;
    end;
end;
```

## `invokeinarray(obj, member_name, member_value, params)`

声明：function

按名称调用对象成员方法或设置成员属性，并用数组传递属性值或方法参数。该函数支持命名参数

<!-- tags: 运行时 -->

| 参数           | 类型      | 说明                                                               |
| -------------- | --------- | ------------------------------------------------------------------ |
| `obj`          | tslobject | 实例对象。                                                         |
| `member_name`  | string    | 成员方法或属性名称。                                               |
| `member_value` | boolean   | 成员类型：0 表示方法，1 表示属性。                                 |
| `params`       | array     | 属性值或方法参数；无参数方法传入空数组，字符串下标可作为命名参数。 |

返回：any

设置属性时返回 0；调用方法时返回方法的执行结果。

### 示例

范例01：通过数组设置对象属性并调用成员方法

```tsl
obj := new RuntimeInvokeArrayExample();
invokeinarray(obj, "name", 1, array("Tinysoft"));
echo invokeinarray(obj, "label", 0, array("TSL")), "\n";
// 输出：TSL:Tinysoft

type RuntimeInvokeArrayExample = class
public
    name;
    function label(prefix);
    begin
        return prefix + ":" + name;
    end;
end;
```

## `ifThen(avalue, atrue, a_false)`

声明：function

如果Avalue值为真，返回参数Atrue，否则返回参数Afalse

<!-- tags: 运行时 判断 检查 -->

| 参数      | 类型 | 说明                       |
| --------- | ---- | -------------------------- |
| `avalue`  | bool | 布尔类型，判定条件         |
| `atrue`   | any  | 任意类型，Avalue为真返回值 |
| `a_false` | any  | 任意类型，Avalue为假返回值 |

返回：any

### 示例

范例01：根据条件选择较大值

```tsl
a := 1;
b := 2;
echo ifThen(a > b, a, b), "\n";
```

## `integer(value)`

声明：function

强制成整数，类型转换，对有些必需要指定类型的函数有用,如format

<!-- tags: 运行时 转换 编码 -->

| 参数    | 类型 | 说明       |
| ------- | ---- | ---------- |
| `value` | real | 实数或整数 |

返回：integer

### 示例

范例01：将实数转换为整数

```tsl
echo integer(123.456), "\n";
```

## `int64(value)`

声明：function

强制成整数，类型转换，对有些必需要指定类型的函数有用,如format

<!-- tags: 运行时 转换 编码 -->

| 参数    | 类型 | 说明       |
| ------- | ---- | ---------- |
| `value` | real | 实数或整数 |

返回：int64

### 示例

范例01：将数值转换为 64 位整数

```tsl
echo int64(123), "\n";
```

## `real(value)`

声明：function

强制为实数，类型转换，对有些必需要指定类型的函数有用，如format

<!-- tags: 运行时 转换 编码 -->

| 参数    | 类型 | 说明       |
| ------- | ---- | ---------- |
| `value` | real | 实数或整数 |

返回：real

### 示例

范例01：将整数转换为实数

```tsl
echo real(123), "\n";
```

## `wideString(value)`

声明：function

将字符串转为Unicode字符串，或者强制让二进制为Unicode字符串

<!-- tags: 运行时 -->

| 参数    | 类型                       | 说明                 |
| ------- | -------------------------- | -------------------- |
| `value` | string\|binary\|widestring | 字符串或者二进制数据 |

返回：widestring

### 示例

范例01：将字符串转换为宽字符串

```tsl
echo wideString("Tinysoft"), "\n";
```

## `binary(value)`

声明：function

强制把字符串或者Unicode字符串转化为二进制流，对有些必需要指定类型的函数有用

<!-- tags: 运行时 -->

| 参数    | 类型                       | 说明                 |
| ------- | -------------------------- | -------------------- |
| `value` | string\|binary\|widestring | 字符串或者二进制数据 |

返回：binary

### 示例

范例01：将字符串转换为二进制值

```tsl
echo toStn(binary("Tinysoft")), "\n";
```

## `stn(v)`

声明：function

把STN串转换为任意类型

<!-- tags: 运行时 转换 编码 STN -->

| 参数 | 类型   | 说明          |
| ---- | ------ | ------------- |
| `v`  | string | 字符串，STN串 |

返回：any

### 示例

范例01：还原 STN 字符串

```tsl
serialized := toStn(array(1, 2, 3));
echo toStn(stn(serialized)), "\n";
```

## `randomize()`

声明：function

已废弃函数

<!-- tags: 运行时 -->

返回：any

### 示例

范例01：初始化随机数状态

```tsl
randomize();
echo random(), "\n";
```

## `random()`

声明：function

（参考文档未提供简述。）

<!-- tags: 运行时 -->

返回：real

### 示例

范例01：生成随机数

```tsl
echo random(), "\n";
```

## `random(value)`

声明：function

返回从 `0` 到 `value - 1` 的随机整数

<!-- tags: 运行时 返回 获取 -->

| 参数    | 类型    | 说明                     |
| ------- | ------- | ------------------------ |
| `value` | integer | 随机范围上限，不包含该值 |

返回：integer

### 示例

```tsl
echo random(1), "\n";
// 输出：0
```

## `tslfilename()`

声明：function

获取正在执行的 `.tsl` 主脚本完整路径

<!-- tags: 运行时 获取 查询 -->

返回：string

### 示例

范例01：读取当前主脚本路径

```tsl
echo tslfilename(), "\n";
```

## `sysgettsllibpath()`

声明：function

获取当前函数库查找路径

<!-- tags: 运行时 查找 搜索 lookup 获取 查询 -->

返回：string

### 示例

范例01：读取当前函数库查找路径

```tsl
echo sysgettsllibpath(), "\n";
```

## 错误与断言函数

## `getProfilerInfo(clear)`

声明：function

获取记录的优化信息

<!-- tags: 运行时 获取 查询 -->

| 参数    | 类型 | 说明      |
| ------- | ---- | --------- |
| `clear` | bool | Boolean。 |

返回：array

### 示例

范例01：读取纯数值循环的分析信息

```tsl
previous_flag := setProfiler(7);
sum := 0;
for i := 1 to 1000 do
    sum += i;
profiler_info := getProfilerInfo(1);
setProfiler(previous_flag);
echo length(profiler_info), "\n";
```

## `importCsv(csv_str, data, include_index, include_header, single_arr)`

声明：function

将指定csv格式字符串csvStr转换为数组，并存储在Data参数中

<!-- tags: 运行时 -->

| 参数             | 类型   | 说明                                                            |
| ---------------- | ------ | --------------------------------------------------------------- |
| `csv_str`        | string | 字符串类型，csv格式字符串。                                     |
| `data`           | array  | 数组类型，转换成功的数组（输出值）。                            |
| `include_index`  | bool   | 可选。布尔类型。指定字符串中是否包含数组下标信息。默认为False。 |
| `include_header` | bool   | 可选。布尔类型。指定字符串中是否包含字段头部信息。默认为True。  |
| `single_arr`     | bool   | 可选。布尔类型。是否转换为一个一维数组。默认为False。           |

返回：bool

### 示例

范例01：解析内存中的 CSV 字符串

```tsl
csv_text := "name,value\nTinysoft,1\n";
ok := importCsv(csv_text, data);
echo ok, ":", toStn(data), "\n";
```

## `stm(v)`

声明：function

把STM流转换为任意类型

<!-- tags: 运行时 转换 编码 STM -->

| 参数 | 类型   | 说明              |
| ---- | ------ | ----------------- |
| `v`  | binary | 二进制类型，STM流 |

返回：any

### 示例

范例01：还原 STM 二进制流

```tsl
stream := toStm(array(1, 2, 3));
echo toStn(stm(stream)), "\n";
```

## `debugRunEnv(sys_param)`

声明：function

将当前变量递交到客户端调试窗口

<!-- tags: 运行时 -->

| 参数        | 类型    | 说明                 |
| ----------- | ------- | -------------------- |
| `sys_param` | boolean | 是否同时输出系统参数 |

返回：integer

### 示例

范例01：不输出系统参数

```tsl
result := debugRunEnv(false);
echo result;
// 输出：0
```

## `getEstSize(value)`

声明：function

获取估算变量占用的内存空间

<!-- tags: 运行时 获取 查询 -->

| 参数    | 类型 | 说明         |
| ------- | ---- | ------------ |
| `value` | any  | 要估算的变量 |

返回：integer

### 示例

范例01：估算数组占用的空间

```tsl
value := array(1, 2, 3);
echo getEstSize(value) >= 0;
// 输出：1
```

## `mToc(tick)`

声明：function

返回指定计时点或最近一次 `mTic` 之后经过的秒数

<!-- tags: 运行时 返回 获取 -->

| 参数   | 类型 | 说明                                                    |
| ------ | ---- | ------------------------------------------------------- |
| `tick` | real | 可选。由 `mTic` 返回的计时点，省略时使用最近一次 `mTic` |

返回：real

### 示例

范例01：计算指定计时点之后经过的秒数

```tsl
tick := mTic;
echo mToc(tick) >= 0;
// 输出：1
```

范例02：使用最近一次计时点

```tsl
mTic;
echo mToc() >= 0;
// 输出：1
```