# 基础函数 / 数组

## `descartesJoin(v_1, v_2, ...)`

声明：function

计算多个值或数组的笛卡尔积

<!-- tags: 数组 笛卡尔积 组合 连接 array cartesian product -->

| 参数  | 类型 | 说明               |
| ----- | ---- | ------------------ |
| `v_1` | any  | 第一个值或数组     |
| `v_2` | any  | 第二个值或数组     |
| `...` | any  | 可选。更多值或数组 |

返回：array

### 示例

范例01：连接三个输入值

```tsl
return descartesJoin(1->3, 21->22, 3);
// 输出：
// array(
// (1,21,3),
// (1,22,3),
// (2,21,3),
// (2,22,3),
// (3,21,3),
// (3,22,3))
```

## `framemerge(left, right, ons, how, suffixes, if_multi_field, keep_method)`

声明：function

按指定字段连接两个数据表

<!-- tags: 数组 数据表 联结 合并 join merge table -->

| 参数             | 类型            | 说明                                         |
| ---------------- | --------------- | -------------------------------------------- |
| `left`           | table           | 左表                                         |
| `right`          | table           | 右表                                         |
| `ons`            | string\|array   | 连接字段或左右表连接字段数组                 |
| `how`            | string\|integer | 可选。连接方式，默认 `inner`                 |
| `suffixes`       | array           | 可选。重名字段后缀，默认 `array('_x', '_y')` |
| `if_multi_field` | boolean         | 可选。是否按多个共同字段连接，默认 false     |
| `keep_method`    | integer         | 可选。重名字段保留方式，默认 0               |

返回：array

### 示例

范例01：按 id 执行内连接

```tsl
left := `array('id': (1, 2), 'left_value': (10, 20));
right := `array('id': (2, 3), 'right_value': (30, 40));
return framemerge(
    left, right, 'id', 'inner', array('_x', '_y'), false, 0);
// 输出：array(("id_x":2,"left_value":20,"id_y":2,"right_value":30))
```

## `frameupdate(left, right, ons, type)`

声明：function

按键字段用右表补充或更新左表中的缺失值，并直接修改左表

<!-- tags: 数组 数据表 更新 缺失值 merge update table -->

| 参数    | 类型          | 说明                            |
| ------- | ------------- | ------------------------------- |
| `left`  | table         | 待更新的左表                    |
| `right` | table         | 提供更新值的右表                |
| `ons`   | string\|array | 可选。键字段，省略时按下标连接  |
| `type`  | integer       | 可选。缺失值类型位掩码，默认 15 |

返回：array

### 示例

范例01：用右表填充左表缺失值

```tsl
left := `array('id': (1, 2), 'value': (nil, 20));
right := `array('id': (1, 2), 'value': (10, 30));
return frameupdate(left, right, 'id', 15);
// 输出：
// array(
// ("id":1,"value":10),
// ("id":2,"value":20))
```

## `getSubTableByField(t, fields)`

声明：function

按字段名称提取数据表的指定列

<!-- tags: 数组 数据表 字段 列 提取 查询 select column -->

| 参数     | 类型   | 说明                         |
| -------- | ------ | ---------------------------- |
| `t`      | array  | 数据表                       |
| `fields` | string | 字段名称，多个名称用分号分隔 |

返回：array

### 示例

范例01：提取 name 和 price 两列

```tsl
value := array(
    ("name": "A", "price": 1, "amount": 10),
    ("name": "B", "price": 2, "amount": 20));
return getSubTableByField(value, "name;price");
// 输出：
// array(
// ("name":"A","price":1),
// ("name":"B","price":2))
```

## `renameFieldByFormat(t, suffix, if_copy)`

声明：function

按格式字符串批量修改数据表字段名

<!-- tags: 数组 数据表 字段 重命名 格式 rename column -->

| 参数      | 类型    | 说明                              |
| --------- | ------- | --------------------------------- |
| `t`       | array   | 待处理数据表                      |
| `suffix`  | string  | 格式字符串，`%s` 表示原字段名     |
| `if_copy` | boolean | 可选。是否在副本上修改，默认 true |

返回：array

### 示例

范例01：为全部字段添加后缀

```tsl
value := array(("a": 1, "b": 2));
return renameFieldByFormat(value, "%s_x", true);
// 输出：array(("a_x":1,"b_x":2))
```

## `speye(m)`

声明：function

创建指定阶数的稀疏单位矩阵

<!-- tags: 数组 稀疏矩阵 单位矩阵 sparse identity matrix -->

| 参数 | 类型    | 说明     |
| ---- | ------- | -------- |
| `m`  | integer | 矩阵阶数 |

返回：array

### 示例

范例01：创建三阶稀疏单位矩阵

```tsl
return speye(3);
// 输出：
// array(
// (1),
// (1:1),
// (2:1))
```

## `tableType(t)`

声明：function

判断数组的数据表下标类型

<!-- tags: 数组 数据表 类型 下标 table type -->

| 参数 | 类型  | 说明       |
| ---- | ----- | ---------- |
| `t`  | array | 待判断数组 |

不是数组时返回 `-1`，字符串下标数组返回 `0`，数字下标数组返回 `1`

返回：integer

### 示例

范例01：判断数字下标二维数组

```tsl
return tableType(array((1, 2), (3, 4)));
// 输出：1
```

## `webFormatToRung(a, type, zero_eps)`

声明：function

将数组中的 nan、nil、正负无穷和接近零的数值替换为短横线

<!-- tags: 数组 缺失值 格式化 nan nil inf web -->

| 参数       | 类型    | 说明                                  |
| ---------- | ------- | ------------------------------------- |
| `a`        | array   | 待处理数组                            |
| `type`     | integer | 可选。替换类型位掩码，默认 15         |
| `zero_eps` | real    | 可选。接近零的判断阈值，默认 `epsi()` |

返回：any

### 示例

范例01：替换 nil 和 nan

```tsl
value := array(nil, nan, 1);
return webFormatToRung(value, 15, 1e-10);
// 输出：array("-","-",1)
```