# Builtin - 基础 / 数组

## `getStrindexnum(value)`

声明：function

返回字符串下标的个数

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

返回：integer

### 示例

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

## `getstrindexs(value)`

声明：function

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

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

返回：array of string

### 示例

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

## `getintindexs(value)`

声明：function

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

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

返回：array of integer

### 示例

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

## `getAllIndexs(value)`

声明：function

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

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

返回：array

### 示例

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

## `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));
return length(arr); // 输出：2
```

## `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反序
return 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))
```

## `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)
);
return 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;
return 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;
return 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;
return filterIn(a, array(("a": 2, "b": 1), ("a": 3, "b": 1)), array("a", "b"), false);
// 输出：array(2, 3)
```

范例 05：过滤一维数组。

```tsl
return 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); // 过滤仅返回下标
return 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)
);
return 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
return filterNotIn(array(1, -5, 10, 2, 10, 14, -5), array(2, 3, 10), nil);
// 输出：array(1, -5, 14, -5)
```

## `sortArray(value, sortdir)`

声明：function

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

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

返回：integer

### 示例

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

## `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);
return 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);
return 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));
return 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));
return 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));
return a;
// 输出：array(5,2,3,4,1)
```

## `arrayToFm(value, sample_value)`

声明：function

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

| 参数           | 类型  | 说明                                                                                                                                          |
| -------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`        | array | 要转换的数字数组                                                                                                                              |
| `sample_value` | any   | 指定 fmarray 单元格类型的样例；类型取决于样例自身：`0` 整型、`0.0` 浮点、`0L` 64位整型。类型不符时强制转换。样例也可是其它数值(如 5、5.5、5L) |

返回：fmarray。转换后的 fmarray 矩阵。

### 示例

范例01：第二个参数为整型 `0`，结果为整型 fmarray（3.5 强制转为 3）

```tsl
t := array(1, 2, 3.5);
return arrayToFm(t, 0);
// 输出：fmarray[1,2,3]
```

范例02：第二个参数改为浮点 `0.0`，结果为浮点 fmarray

```tsl
t := array(1, 2, 3.5);
return arrayToFm(t, 0.0);
// 输出：fmarray[1.0,2.0,3.5]
```

若第二个参数为 `0L`（64位整型），则返回 `fmarray[1L,2L,3L]`。