# Builtin - 系统相关函数

## 函数

### `dataType(value, mode)`

返回数据类型编号，支持数组遍历模式。

| 参数    | 类型 | 说明                                                    |
| ------- | ---- | ------------------------------------------------------- |
| `value` | any  | 输入数据                                                |
| `mode`  | any  | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：array

### `ifInt(value, mode)`

判断是否为 32 位整数类型。

| 参数    | 类型  | 说明                                                    |
| ------- | ----- | ------------------------------------------------------- |
| `value` | array | 输入数据                                                |
| `mode`  | any   | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：bool

### `ifInt64(value, mode)`

判断是否为 64 位整数类型。

| 参数    | 类型 | 说明                                                    |
| ------- | ---- | ------------------------------------------------------- |
| `value` | any  | 输入数据                                                |
| `mode`  | any  | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：bool

### `ifReal(value, mode)`

判断是否为 实数类型。

| 参数    | 类型  | 说明                                                    |
| ------- | ----- | ------------------------------------------------------- |
| `value` | array | 输入数据                                                |
| `mode`  | any   | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：bool

### `ifNumber(value, mode)`

判断是否为 数字（整数或实数）类型。

| 参数    | 类型  | 说明                                                    |
| ------- | ----- | ------------------------------------------------------- |
| `value` | array | 输入数据                                                |
| `mode`  | any   | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：bool

### `ifString(value, mode)`

判断是否为 字符串类型。

| 参数    | 类型  | 说明                                                    |
| ------- | ----- | ------------------------------------------------------- |
| `value` | array | 输入数据                                                |
| `mode`  | any   | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：bool

### `ifArray(value, mode)`

判断是否为 数组类型。

| 参数    | 类型 | 说明                                                    |
| ------- | ---- | ------------------------------------------------------- |
| `value` | any  | 输入数据                                                |
| `mode`  | any  | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：bool

### `ifNil(value, mode)`

判断是否为 Nil类型。

| 参数    | 类型 | 说明                                                    |
| ------- | ---- | ------------------------------------------------------- |
| `value` | any  | 输入数据                                                |
| `mode`  | any  | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：bool

### `ifNone(value[, tag])`

判断对象 `operator[1]` 多级下标写入时传入的 None 标记值。

| 参数    | 类型 | 说明                                             |
| ------- | ---- | ------------------------------------------------ |
| `value` | void | `operator[1]` 中间层或回滚层传入的 None 值       |
| `tag`   | any  | None 标记值；中间层第一层为 `0`，回滚标记为 `-1` |

返回：bool

### `ifExp(value, mode)`

判断是否为 表达式类型。

| 参数    | 类型 | 说明                                                    |
| ------- | ---- | ------------------------------------------------------- |
| `value` | any  | 输入数据                                                |
| `mode`  | any  | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：bool

### `ifGraph(value)`

判断是否为 图形类型。

| 参数    | 类型 | 说明     |
| ------- | ---- | -------- |
| `value` | any  | 输入数据 |

返回：bool

### `ifGraphGroup(value)`

判断是否为 图形组类型。

| 参数    | 类型 | 说明     |
| ------- | ---- | -------- |
| `value` | any  | 输入数据 |

返回：bool

### `ifBinary(value, mode)`

判断是否为 二进制/Buffer类型。

| 参数    | 类型 | 说明                                                    |
| ------- | ---- | ------------------------------------------------------- |
| `value` | any  | 输入数据                                                |
| `mode`  | any  | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） |

返回：bool

### `ifMatrix(value)`

判断是否为 Matrix类型。

| 参数    | 类型 | 说明     |
| ------- | ---- | -------- |
| `value` | any  | 输入数据 |

返回：bool

### `ifFmarray(value)`

判断是否为 FMArray 类型。

| 参数    | 类型 | 说明     |
| ------- | ---- | -------- |
| `value` | any  | 输入数据 |

返回：bool

### `ifObj(value)`

判断是否为对象类型。

| 参数    | 类型 | 说明     |
| ------- | ---- | -------- |
| `value` | any  | 输入数据 |

返回：bool

### `createBinary(size)`

创建 Binary 缓冲区。

| 参数   | 类型 | 说明     |
| ------ | ---- | -------- |
| `size` | any  | 字节长度 |

返回：binary

## 复制函数

### `dupValue(value)`

复制值，避免被调用函数修改原变量。

| 参数    | 类型 | 说明   |
| ------- | ---- | ------ |
| `value` | any  | 输入值 |

返回：any

## 条件选择函数

### `ifThen(condition, true_value, false_value)`

条件成立返回 true_value，否则返回 false_value。

| 参数          | 类型 | 说明               |
| ------------- | ---- | ------------------ |
| `condition`   | any  | 判断条件           |
| `true_value`  | any  | 条件成立时返回值   |
| `false_value` | any  | 条件不成立时返回值 |

返回：bool

## 数据类型转换函数

### `integer(value)`

将数值转换为整数。

| 参数    | 类型  | 说明     |
| ------- | ----- | -------- |
| `value` | float | 输入数值 |

返回：any

### `int64(value)`

将数值转换为 64 位整数。

| 参数    | 类型  | 说明     |
| ------- | ----- | -------- |
| `value` | float | 输入数值 |

返回：any

### `real(value)`

将数值转换为实数。

| 参数    | 类型  | 说明     |
| ------- | ----- | -------- |
| `value` | float | 输入数值 |

返回：float

### `wideString(value)`

将数据转换为 Unicode 字符串。

| 参数    | 类型   | 说明     |
| ------- | ------ | -------- |
| `value` | string | 输入数据 |

返回：string

### `binary(value)`

将数据转换为二进制流。

| 参数    | 类型   | 说明     |
| ------- | ------ | -------- |
| `value` | string | 输入数据 |

返回：binary

### `setPrecision(value, digits)`

设置数值的小数精度。

| 参数     | 类型  | 说明     |
| -------- | ----- | -------- |
| `value`  | float | 输入数值 |
| `digits` | any   | 小数位数 |

返回：float

### `toStm(value, mode, precision[, arg4])`

将数据序列化为 STM 二进制流。

| 参数        | 类型  | 说明               |
| ----------- | ----- | ------------------ |
| `value`     | array | 输入数据           |
| `mode`      | any   | 序列化模式（可选） |
| `precision` | any   | 小数位数（可选）   |
| `arg4`      | any   |                    |

返回：binary

### `toStn(value, digits)`

将数值格式化为 STN 字符串。

| 参数     | 类型  | 说明             |
| -------- | ----- | ---------------- |
| `value`  | float | 输入数值         |
| `digits` | any   | 小数位数（可选） |

返回：string

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

将数组导出为 CSV 格式字符串。

| 参数             | 类型   | 说明                      |
| ---------------- | ------ | ------------------------- |
| `data`           | array  | 数组数据                  |
| `out_text`       | string | 输出字符串（引用返回）    |
| `include_index`  | any    | 是否包含下标（可选，1/0） |
| `include_header` | any    | 是否包含表头（可选，1/0） |

返回：array

### `stn(v)`

解析 STN 数值字符串。

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

返回：string

## 全局缓存函数

### `ifCache(value)`

判断值是否仍是全局缓存引用。

| 参数    | 类型 | 说明       |
| ------- | ---- | ---------- |
| `value` | any  | 待判断的值 |

返回：bool

## 随机函数

### `randomize()`

随机函数相关函数。

返回：any

### `random([value])`

生成随机数。

| 参数    | 类型 | 说明                 |
| ------- | ---- | -------------------- |
| `value` | any  | value 为上限（可选） |

返回：float

### `randomFrom(avalues)`

从数组中随机取一个元素。

| 参数      | 类型  | 说明     |
| --------- | ----- | -------- |
| `avalues` | array | 候选数组 |

返回：array

## 表达式相关函数

### `tslfilename()`

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

返回：string

### `sysgettsllibpath()`

获取当前函数库查找路径。

返回：string

## 错误与断言函数

### `assert(check, error_message)`

断言 `check` 是否为真值；为真时返回 `0` 并继续执行，为假时抛出 `error_message` 指定的运行时错误。

| 参数            | 类型   | 说明                                    |
| --------------- | ------ | --------------------------------------- |
| `check`         | any    | 按 TSL 真值规则判断；真值通过，假值失败 |
| `error_message` | string | 断言失败时抛出的错误信息                |

返回：any

## 性能优化相关函数

### `setProfiler(flags)`

设置性能分析开关与统计范围。

| 参数    | 类型 | 说明           |
| ------- | ---- | -------------- |
| `flags` | any  | 统计选项位掩码 |

返回：void

### `getProfilerInfo(mode)`

获取性能分析信息。

| 参数   | 类型 | 说明                        |
| ------ | ---- | --------------------------- |
| `mode` | any  | 可选；传 1 仅返回信息不弹窗 |

返回：any

## 数据类型函数

### `ifGraph(value, n)`

判断value是否是一个图形类型。可通过可选参数N对数组中的行或元素进行判断。

| 参数    | 类型 | 说明                             |
| ------- | ---- | -------------------------------- |
| `value` | any  | 任意类型数据                     |
| `n`     | any  | 可选参数，整数。具体参考返回说明 |

返回：bool

### `ifGraphgroup(value, n)`

判断value是否是一个图形组合类型。可通过可选参数N对数组中的行或元素进行判断。

| 参数    | 类型 | 说明                             |
| ------- | ---- | -------------------------------- |
| `value` | any  | 任意类型数据                     |
| `n`     | any  | 可选参数，整数。具体参考返回说明 |

返回：bool

### `ifMatrix(value, n)`

判断value是否是一个Matrix类型。可通过可选参数N对数组中的行或元素进行判断。

| 参数    | 类型 | 说明                             |
| ------- | ---- | -------------------------------- |
| `value` | any  | 任意类型数据                     |
| `n`     | any  | 可选参数，整数。具体参考返回说明 |

返回：bool

### `ifObj(value, n)`

判断value是否是一个ComObj对象或者一个TSL的对象类型。可通过可选参数N对数组中的行或元素进行判断。

| 参数    | 类型 | 说明                             |
| ------- | ---- | -------------------------------- |
| `value` | any  | 任意类型数据                     |
| `n`     | any  | 可选参数，整数。具体参考返回说明 |

返回：bool

### `getOleObject(class_name, method, obj)`

获取一个ComObj对象类型。

| 参数         | 类型   | 说明                                                                                                          |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------- |
| `class_name` | string | 字符串，对象的类名。                                                                                          |
| `method`     | any    | 整数，产生方法的方法，1:获取一个存在的对象，2:新建一个对象，其他值:如果存在则获取一个存在对象，不存在则创建。 |
| `obj`        | object | 保存返回的对象。                                                                                              |

返回：bool

## 数据类型转换函数

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

将指定csv格式字符串csvStr转换为数组，并存储在Data参数中。 支持范围：新一代TSL支持。

| 参数             | 类型   | 说明                                 |
| ---------------- | ------ | ------------------------------------ |
| `csv_str`        | string | 字符串类型，csv格式字符串。          |
| `data`           | array  | 数组类型，转换成功的数组（输出值）。 |
| `include_index`  | bool   | object                               |
| `include_header` | bool   | object                               |
| `single_arr`     | bool   | object                               |

返回：array

## 表达式相关函数

### `arrayToFm(value, sample_value)`

将数组转换为 FMArray，并按样例值确定单元格类型。

| 参数           | 类型  | 说明                                                        |
| -------------- | ----- | ----------------------------------------------------------- |
| `value`        | array | 输入数组                                                    |
| `sample_value` | float | 单元格类型样例；如 `0` 生成整型单元格，`0.0` 生成浮点单元格 |

返回：array

### `importCsv(csv_text, out_data, has_header)`

将 CSV 字符串解析为数组。

| 参数         | 类型   | 说明                      |
| ------------ | ------ | ------------------------- |
| `csv_text`   | string | CSV 字符串                |
| `out_data`   | array  | 输出数组（引用返回）      |
| `has_header` | any    | 是否包含表头（可选，1/0） |

返回：array

### `stm(value)`

解析 STM 序列化数据。

| 参数    | 类型   | 说明   |
| ------- | ------ | ------ |
| `value` | string | binary |

返回：any

### `setGlobalCache(name, value)`

写入全局缓存。

| 参数    | 类型   | 说明         |
| ------- | ------ | ------------ |
| `name`  | string | 缓存键       |
| `value` | any    | 写入缓存的值 |

返回：any

### `getGlobalCache(name, out_value)`

按键读取全局缓存。

| 参数        | 类型   | 说明                 |
| ----------- | ------ | -------------------- |
| `name`      | string | 缓存键               |
| `out_value` | any    | 输出变量，接收缓存值 |

返回：any