# Builtin - 数组

## `arrayToFm(data, type_data)`

声明：function

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

| 参数        | 类型  | 说明                                                                 |
| ----------- | ----- | -------------------------------------------------------------------- |
| `data`      | array | 要转换的数字数组                                                     |
| `type_data` | any   | 单元格类型样例，`0` 表示 integer，`0L` 表示 int64，`0.0` 表示 double |

返回：fmarray

### 示例

范例01：转换为浮点 FMArray

```tsl
value := arrayToFm(array(1, 2, 3.5), 0.0);
echo value[2];
// 输出：3.5
```

## `deleteField(arr, index, merge)`

声明：function

删除数组或矩阵的二维下标。

| 参数    | 类型          | 说明                                    |
| ------- | ------------- | --------------------------------------- |
| `arr`   | array\|matrix | 要修改的数组或矩阵                      |
| `index` | any           | 要删除的数字或字符串列下标              |
| `merge` | bool          | 是否移动删除后的数字下标，默认值为 true |

返回：bool

### 示例

```tsl
data := array(("code": "A", "value": 1), ("code": "B", "value": 2));
deleteField(data, "value", true);
echo trim(toStn(data));
// 输出：
// array(
// ("code":"A"),
// ("code":"B"))
```

## `deleteIndex(arr, index, merge)`

声明：function

删除数组或矩阵的下标。

| 参数    | 类型          | 说明                                    |
| ------- | ------------- | --------------------------------------- |
| `arr`   | array\|matrix | 要修改的数组或矩阵                      |
| `index` | any           | 要删除的数字或字符串行下标              |
| `merge` | bool          | 是否移动删除后的数字下标，默认值为 true |

返回：bool

### 示例

```tsl
data := array("first": 1, "second": 2);
deleteIndex(data, "first", true);
echo trim(toStn(data));
// 输出：array("second":2)
```

## `filterIn(r, v, field, b_return_sub_result=true)`

声明：function

返回指定列的值在过滤集内的子结果集或者下标列表。

| 参数                  | 类型   | 说明                                                                           |
| --------------------- | ------ | ------------------------------------------------------------------------------ |
| `r`                   | array  | 待过滤的数据表或数组。                                                         |
| `v`                   | array  | 过滤集。                                                                       |
| `field`               | string | 指定列名；为 `nil` 时按整行或一维数组元素匹配。                                |
| `b_return_sub_result` | bool   | 可选参数，默认 `true`。为 `true` 时返回子结果集，为 `false` 时返回行下标列表。 |

返回：array,tablearray

### 示例

范例 01：过滤表中指定列的值。

```tsl
a := array(
    ("a": 0, "b": 0, "c": 0),
    ("a": 1, "b": 0, "c": 2),
    ("a": 2, "b": 1, "c": 4),
    ("a": 3, "b": 1, "c": 6),
    ("a": 4, "b": 2, "c": 8),
    ("a": 5, "b": 2, "c": 10),
    ("a": 6, "b": 3, "c": 12)
);
echo trim(toStn(filterIn(a, array(1, 2, 5), "a")));
// 输出：array(
// ("a":1, "b":0, "c":2),
// ("a":2, "b":1, "c":4),
// ("a":5, "b":2, "c":10)
// )
```

范例 02：按整行数据筛选子集。

```tsl
a := array();
for i := 0 to 15 do
begin
    a[i]["a"] := i;
    a[i]["b"] := i div 2;
    a[i]["c"] := i * 2;
end;
echo trim(toStn(filterIn(a, array(("a": 2, "b": 1, "c": 4), ("a": 3, "b": 1, "c": 4)), nil)));
// 输出：array(
// ("a":2, "b":1, "c":4)
// )
```

范例 03：按多列组合筛选子集。

```tsl
a := array();
for i := 0 to 15 do
begin
    a[i]["a"] := i;
    a[i]["b"] := i div 2;
    a[i]["c"] := i * 2;
end;
echo trim(toStn(filterIn(a, array(("a": 2, "b": 1), ("a": 3, "b": 1)), array("a", "b"))));
// 输出：array(
// ("a":2, "b":1, "c":4),
// ("a":3, "b":1, "c":6)
// )
```

范例 04：返回符合指定列数据的行下标。

```tsl
a := array();
for i := 0 to 15 do
begin
    a[i]["a"] := i;
    a[i]["b"] := i div 2;
    a[i]["c"] := i * 2;
end;
echo trim(toStn(filterIn(a, array(("a": 2, "b": 1), ("a": 3, "b": 1)), array("a", "b"), false)));
// 输出：array(2, 3)
```

范例 05：过滤一维数组。

```tsl
echo trim(toStn(filterIn(array(1, -5, 10, 2, 10, 14, -5), array(2, 3, 10), nil)));
// 输出：array(10, 2, 10)
```

## `filterNotIn(r, v, field, b_return_sub_result=true)`

声明：function

返回指定列的值不在过滤集内的子结果集或者下标列表。

| 参数                  | 类型   | 说明                                                                           |
| --------------------- | ------ | ------------------------------------------------------------------------------ |
| `r`                   | array  | 待过滤的数据表或数组。                                                         |
| `v`                   | array  | 过滤集。                                                                       |
| `field`               | string | 指定列名；为 `nil` 时按整行或一维数组元素匹配。                                |
| `b_return_sub_result` | bool   | 可选参数，默认 `true`。为 `true` 时返回子结果集，为 `false` 时返回行下标列表。 |

返回：array,tablearray

### 示例

范例 01：按指定列过滤数据表，并同时查看子结果集和行下标。

```tsl
a := array();
for i := 0 to 5 do
begin
    a[i]["a"] := i;
    a[i]["b"] := i div 2;
    a[i]["c"] := i * 2;
end;

b := array(1, 3, 5);
c1 := filterNotIn(a, b, "a"); // 过滤结果
c2 := filterNotIn(a, b, "a", false); // 过滤仅返回下标
echo trim(toStn(array(c1, c2)));
// 输出：
// array(
// (
// ("a":0, "b":0, "c":0),
// ("a":2, "b":1, "c":4),
// ("a":4, "b":2, "c":8)),
// (0, 2, 4))
```

范例 02：按整行数据过滤二维数组，保留重复行。

```tsl
t := array(
    ("a": 0, "b": 0, "c": 0),
    ("a": 1, "b": 0, "c": 2),
    ("a": 2, "b": 1, "c": 4),
    ("a": 2, "b": 1, "c": 4),
    ("a": 4, "b": 2, "c": 8),
    ("a": 4, "b": 2, "c": 8),
    ("a": 6, "b": 3, "c": 12)
);
echo trim(toStn(filterNotIn(t, array(("a": 2, "b": 1, "c": 4)), nil)));
// 输出：
// array(
// ("a":0, "b":0, "c":0),
// ("a":1, "b":0, "c":2),
// ("a":4, "b":2, "c":8),
// ("a":4, "b":2, "c":8),
// ("a":6, "b":3, "c":12))
```

范例 03：过滤一维数组。

```tsl
echo trim(toStn(filterNotIn(array(1, -5, 10, 2, 10, 14, -5), array(2, 3, 10), nil)));
// 输出：array(1, -5, 14, -5)
```

## `getAllIndexs(value)`

声明：function

返回数组类型，存储数组Value的所有下标

| 参数    | 类型  | 说明     |
| ------- | ----- | -------- |
| `value` | array | 数组类型 |

返回：array

### 示例

```tsl
arr := array("p1": 1, "p2": 2, "p3": 3);
echo trim(toStn(getAllIndexs(arr)));
// 输出：array("p1","p2","p3")
```

## `getintindexs(value)`

声明：function

返回数组类型，存储数组Value的所有的数字下标

| 参数    | 类型  | 说明     |
| ------- | ----- | -------- |
| `value` | array | 数组类型 |

返回：array of integer

### 示例

```tsl
arr := array(1: "p1", 2: "p2", 3: "p3", "a4": "p4");
echo trim(toStn(getintindexs(arr)));
// 输出：array(1,2,3)
```

## `getStrindexnum(value)`

声明：function

返回字符串下标的个数

| 参数    | 类型  | 说明     |
| ------- | ----- | -------- |
| `value` | array | 数组类型 |

返回：integer

### 示例

```tsl
arr := array("a1": 1, "a2": 2, 1: 3);
echo getStrindexnum(arr);
// 输出：2
```

## `getstrindexs(value)`

声明：function

返回数组类型，存储参数Value的所有的字符串下标

| 参数    | 类型  | 说明     |
| ------- | ----- | -------- |
| `value` | array | 数组类型 |

返回：array of string

### 示例

```tsl
arr := array("a1": 1, "a2": 2, "a3": 3);
echo trim(toStn(getstrindexs(arr)));
// 输出：array("a1","a2","a3")
```

## `length(value)`

声明：function

返回字符串、二进制流或者数组或者Matrix的行长度。

| 参数    | 类型                          | 说明                                 |
| ------- | ----------------------------- | ------------------------------------ |
| `value` | string\|binary\|array\|matrix | 字符串、二进制流或数组或者Matrix类型 |

返回：integer

### 示例

```tsl
arr := array(("p1": 1, "p2": 2, "p3": 3), ("p1": 4, "p2": 5, "p3": 6));
echo length(arr); // 输出：2
```

## `magicGetArray(arr, n1, n2, ..., nn)`

声明：function

获取数组指定下标的值，支持多维数组。中间的参数可以是直接列出的数组各维下标，也可以以数组的形式表现，数组内的数据就是下标。

| 参数  | 类型                   | 说明                                             |
| ----- | ---------------------- | ------------------------------------------------ |
| `arr` | array                  | 数组                                             |
| `n1`  | integer\|string\|array | 第一维下标；传入数组时，数组元素依次作为各维下标 |
| `n2`  | integer\|string        | 第二维下标，可省略                               |
| `nn`  | integer\|string        | 第 N 维下标，可省略                              |

返回：any

### 示例

```tsl
data := array(("code": "A", "value": 1), ("code": "B", "value": 2));
echo magicGetArray(data, 1, "value");
// 输出：2
```

## `magicSetArray(arr, n1, n2, ..., nn, value)`

声明：function

对数组进行操作，对数组指定下标的数据进行赋值，支持多维数组。中间的参数可以是直接列出的数组各维下标，也可以以数组的形式表现，数组内的数据就是下标。

| 参数    | 类型                   | 说明                                             |
| ------- | ---------------------- | ------------------------------------------------ |
| `arr`   | array                  | 要修改的数组                                     |
| `n1`    | integer\|string\|array | 第一维下标；传入数组时，数组元素依次作为各维下标 |
| `n2`    | integer\|string        | 第二维下标，可省略                               |
| `nn`    | integer\|string        | 第 N 维下标，可省略                              |
| `value` | any                    | 要写入的值                                       |

返回：integer（成功时为 0）

### 示例

```tsl
data := array(("code": "A", "value": 1), ("code": "B", "value": 2));
result := magicSetArray(data, 1, "value", 9);
echo trim(toStn(array("data": data, "result": result)));
// 输出：
// array("data":
// (
// ("code":"A","value":1),
// ("code":"B","value":9)),"result":0)
```

## `reIndex(data, index_info1, index_info2, index_info_n)`

声明：function

修改数组下标

| 参数           | 类型       | 说明                                                                                        |
| -------------- | ---------- | ------------------------------------------------------------------------------------------- |
| `data`         | array      | 需要重构的数组                                                                              |
| `index_info1`  | nil\|array | 第一维的重构信息，如果为NIL则表示该维度不重构，数组以需要重构的下标为下标新下标为值的模式。 |
| `index_info2`  | nil\|array | 第二维的重构信息，可省略                                                                    |
| `index_info_n` | nil\|array | 第N维的重构信息，可省略                                                                     |

返回：any

### 示例

范例01：修改数字列名数组为字符串列名数组，即将 0,1,2（自增数字）列名重构为 "a","b","c" 列名的数组。

```tsl
a := rand(10, 3);
s := array("a", "b", "c");
reIndex(a, nil, s);
echo trim(toStn(a));
// 输出：列名由 0,1,2 重构为 "a","b","c"；单元格值来自 rand，每次运行不同
```

范例02：修改数字行标数组为字符串行标数组，即将 0,1,2（自增数字）行标重构为 "a","b","c" 行标的数组。

```tsl
a := rand(3, 3);
s := array("a", "b", "c");
reIndex(a, s);
echo trim(toStn(a));
// 输出：行标由 0,1,2 重构为 "a","b","c"；单元格值来自 rand，每次运行不同
```

范例03：通过设置行标为 nil 删除该行记录。

```tsl
a := array("A": 0, "B": 1, "D": 2, "E": 3);
reIndex(a, array("A": "A1", "D": nil));
echo trim(toStn(a));
// 输出：array("A1":0,"B":1,"E":3)
```

范例04：对多维数组进行处理。第 2 个参数为 nil 表示对第一维的下标不进行变动，因此修改列 "A" 为 "A1"，并删除 "D" 列。

```tsl
a := rand(10, array("A", "B", "D", "E")); // 初始化一个四列的二维矩阵
reIndex(a, nil, array("A": "A1", "D": nil));
echo trim(toStn(a));
// 输出：列 "A" 改名为 "A1" 并删除 "D" 列，剩 "A1","B","E" 三列；单元格值来自 rand，每次运行不同
```

范例05：利用 reIndex 做列的交换。

```tsl
a := array(1, 2, 3, 4, 5);
reIndex(a, array(0: 4, 4: 0));
echo trim(toStn(a));
// 输出：array(5,2,3,4,1)
```

## `reIndexCopy(data, index_info1, index_info2, ..., index_info_n)`

声明：function

ReIndexCopy和Reindex的差异：ReIndex修改原有的结果集，而ReIndexCopy不修改原结果集返回一个新结果集。

| 参数           | 类型       | 说明                    |
| -------------- | ---------- | ----------------------- |
| `data`         | array      | 需要重构的数组          |
| `index_info1`  | nil\|array | 第一维重构信息          |
| `index_info2`  | nil\|array | 第二维重构信息，可省略  |
| `index_info_n` | nil\|array | 第 N 维重构信息，可省略 |

返回：array

### 示例

```tsl
source := array("A": 10, "B": 20);
copied := reIndexCopy(source, array("A": "X", "B": "Y"));
echo trim(toStn(array("source": source, "copied": copied)));
// 输出：
// array("source":
// ("A":10,"B":20),"copied":
// ("X":10,"Y":20))
```

## `reshape(a, count1, ..., count_n)`

声明：function

将原数组A的元素重构为一个新的指定行列大小的数组，支持行列重命名。要求重构后的数组的元素个数与原数组的元素个数保持一致。 当只有一个参数时，将原数组A重构为一个一维数组，当有多个参数时，重构为指定结构的N维数组。

| 参数      | 类型           | 说明                          |
| --------- | -------------- | ----------------------------- |
| `a`       | array          | 需要重构的数组                |
| `count1`  | integer\|array | 第一维长度或下标数组，可省略  |
| `count_n` | integer\|array | 第 N 维长度或下标数组，可省略 |

返回：array

### 示例

```tsl
echo trim(toStn(reshape(array(1, 2, 3, 4), 2, 2)));
// 输出：
// array(
// (1,2),
// (3,4))
```

## `sortArray(value, sortdir)`

声明：function

对一个一维数组进行排序，方向为sortdir；如果省略sortdir参数，默认为1，正序排序；设置为0时，逆序排序。

| 参数      | 类型  | 说明             |
| --------- | ----- | ---------------- |
| `value`   | array | 一维数组         |
| `sortdir` | bool  | 布尔型，排序方向 |

返回：integer

### 示例

```tsl
arr := array(1, 6, 3);
sortArray(arr);
echo trim(toStn(arr));
// 输出：array(1,3,6)
```

## `sortTableByField(value, field, sortdir)`

声明：function

对一个表类型的数组Value用字段名Field排序，排序方向由sortdir决定，如果省略sortdir参数或者设置sortdir为1，正序排序，否则逆序排序。

| 参数      | 类型   | 说明                                     |
| --------- | ------ | ---------------------------------------- |
| `value`   | array  | 二维数组；                               |
| `field`   | string | 字符串，数组的列下标；                   |
| `sortdir` | bool   | 布尔型，排序方向，1表示正序，0表示逆序。 |

返回：integer

### 示例

```tsl
arr := array(
    ("p1": 1, "p2": 2, "p3": 3),
    ("p1": 4, "p2": 5, "p3": 6),
    ("p1": 66, "p2": 200, "p3": 36),
    ("p1": 30, "p2": 500, "p3": 40)
);
sortTableByField(arr, "p1", 1); // sortdir=1按"p1"正序，sortdir=0反序
echo trim(toStn(arr));
// 输出：
// array(
// ("p1":1, "p2":2, "p3":3),
// ("p1":4, "p2":5, "p3":6),
// ("p1":30, "p2":500, "p3":40),
// ("p1":66, "p2":200, "p3":36))
```