Files
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

1179 lines
36 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
markup: occlusion
title: lib/表
description: >-
列表与字典。优先用「改」(路径 1-based,与access 取元同构);取/改位/切片为 0-based。
json 只管解析/序列化。
---
列表与字典。嵌套写入优先「改」;作者程序里读元用access 取元,不要新写脚注取元。
用明确的数据形态变换列表、字典和行记录。
能力与边界:access 与改的整数路径从一开始;取、切片、插入、删位等旧接口从零开始。更新返回新值,必须保存。行数只是长度别名;列转行、行转列明确转换形态。相等比较沿用运行时的类型和字典顺序规则。
本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。
实现入口:[src/host/collection.rs](../src/host/collection.rs)、[src/host/collection_ops.rs](../src/host/collection_ops.rs)
开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。
## 改
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 入 | any | 必填 | 输入集合;None 用于创建新记录 |
| 于 | any | 必填 | 文本键、从一开始的下标,或由键与下标组成的嵌套路径 |
| 值 | any | 必填 | 待转换或保存的值;不会就地修改输入 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 把集合入在路径于上的那一元改成值 |
这里使用`入`、`于`、`值`。
调用效应:pure。
把集合入在路径于上的那一元改成值。
于可以是文本键、1-based 下标,或键/下标组成的路径列表(与access 取元嵌套同构)。
调用例:[表.改] 入=None 于="Authorization" 值="Bearer-x"
完成后返回*[把集合入在路径于上的那一元改成值](> host_collection_put in=`入` at=`于` value=`值`)*。
## 长度
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| xs | any | 必填 | 本操作要求的输入列表或集合 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | 列表或字典 xs 的长度 |
这里使用`xs`。
调用效应:pure。
列表或字典 xs 的长度。
完成后返回*[调用 len](len(`xs`))*。
## 行数
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| xs | any | 必填 | 本操作要求的输入列表或集合 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | 列表 xs 的行数(同长度) |
这里使用`xs`。
调用效应:pure。
列表 xs 的行数(同长度)。
完成后返回*[调用 len](len(`xs`))*。
## 取
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| xs | any | 必填 | 本操作要求的输入列表或集合 |
| i | number | 必填 | 从零开始的元素或行下标 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 从零起取 xs 的第 i 项(与内置 at 相同) |
这里使用`xs`、`i`。
调用效应:pure。
从零起取 xs 的第 i 项(与内置 at 相同)。越界 → None。
完成后返回*[调用 at](at(value=`xs`, index=`i`))*。
## 取行
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| xs | any | 必填 | 本操作要求的输入列表或集合 |
| i | number | 必填 | 从零开始的元素或行下标 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 从零起取 xs 的第 i 行 |
这里使用`xs`、`i`。
调用效应:pure。
从零起取 xs 的第 i 行。
完成后返回*[调用 at](at(value=`xs`, index=`i`))*。
## 追加
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 在 list 末尾追加 item |
这里使用`list`、`item`。
调用效应:pure。
在 list 末尾追加 item。
完成后返回*[在 list 末尾追加 item](> host_list_append list=`list` item=`item`)*。
## 前插
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 在 list 开头插入 item |
这里使用`list`、`item`。
调用效应:pure。
在 list 开头插入 item。
完成后返回*[在 list 开头插入 item](> host_list_prepend list=`list` item=`item`)*。
## 拼接
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | 必填 | 第一个列表;None 用作空列表种子 |
| b | any | 必填 | 追加到 a 后面的列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 拼接列表 a 与 b |
这里使用`a`、`b`。
调用效应:pure。
拼接列表 a 与 b。
完成后返回*[拼接列表 a 与 b](> host_list_concat a=`a` b=`b`)*。
## 插入
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| index | number | 必填 | 插入、替换或删除的位置,从零开始 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 在 list 的从零起 index 处插入 item |
这里使用`list`、`index`、`item`。
调用效应:pure。
在 list 的从零起 index 处插入 item。
完成后返回*[在 list 的从零起 index 处插入 item](> host_list_insert list=`list` index=`index` item=`item`)*。
## 改位
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| index | number | 必填 | 插入、替换或删除的位置,从零开始 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 从零起替换 list 的 index 为 item;日常嵌套改写请用「改」 |
这里使用`list`、`index`、`item`。
调用效应:pure。
从零起替换 list 的 index 为 item;日常嵌套改写请用「改」。
完成后返回*[从零起替换 list 的 index 为 item;日常嵌套改写请用「改」](> host_list_set_at list=`list` index=`index` item=`item`)*。
## 删位
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| index | number | 必填 | 插入、替换或删除的位置,从零开始 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 删去 list 从零起的 index |
这里使用`list`、`index`。
调用效应:pure。
删去 list 从零起的 index。
完成后返回*[删去 list 从零起的 index](> host_list_remove_at list=`list` index=`index`)*。
## 弹出
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 去掉 list 末项(空表报错) |
这里使用`list`。
调用效应:pure。
去掉 list 末项(空表报错)。需要末值时先「末」。
得到**`n` = [调用 len](len(`list`))**。
1. `n` > 0
完成后返回*[去掉 list 末项(空表报错)](> host_list_remove_at list=`list` index=`n` - 1)*。
2. *
完成后返回*[去掉 list 末项(空表报错)](> host_list_remove_at list=`list` index=0)*。
## 首
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | list 的首项 |
这里使用`list`。
调用效应:pure。
list 的首项。
完成后返回*[list 的首项](> host_list_first list=`list`)*。
## 末
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | list 的末项 |
这里使用`list`。
调用效应:pure。
list 的末项。
完成后返回*[list 的末项](> host_list_last list=`list`)*。
## 切片
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| start | number | 必填 | 切片起点,从零开始且包含端点 |
| end | any | None | 切片终点,从零开始且不包含端点;None 表示到末尾 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 list 做从零起的半开切片,从 start 到 end |
这里使用`list`、`start`、`end`=None。
调用效应:pure。
对 list 做从零起的半开切片,从 start 到 end。
完成后返回*[对 list 做从零起的半开切片,从 start 到 end](> host_list_slice list=`list` start=`start` end=`end`)*。
## 含有
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | bool | list 是否含有 item |
这里使用`list`、`item`。
调用效应:pure。
list 是否含有 item。
完成后返回*[list 是否含有 item](> host_list_contains list=`list` item=`item`)*。
## 下标
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | item 在 list 中从零起的下标;没有 → None |
这里使用`list`、`item`。
调用效应:pure。
item 在 list 中从零起的下标;没有 → None。
完成后返回*[item 在 list 中从零起的下标;没有 → None](> host_list_index_of list=`list` item=`item`)*。
## 反转
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 反转 list |
这里使用`list`。
调用效应:pure。
反转 list。
完成后返回*[反转 list](> host_list_reverse list=`list`)*。
## 排序
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 list 升序排序(优先 int/num/text) |
这里使用`list`。
调用效应:pure。
对 list 升序排序(优先 int/num/text)。
完成后返回*[对 list 升序排序(优先 int/num/text)](> host_list_sort list=`list`)*。
## 按键排序
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| key | text | 必填 | 本操作需要的字段名或键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 map 列表 list 按字段 key 排序 |
这里使用`list`、`key`。
调用效应:pure。
对 map 列表 list 按字段 key 排序。
完成后返回*[对 map 列表 list 按字段 key 排序](> host_list_sort_by list=`list` key=`key`)*。
## 去重
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 list 保序去重(保留首次) |
这里使用`list`。
调用效应:pure。
对 list 保序去重(保留首次)。
完成后返回*[对 list 保序去重(保留首次)](> host_list_unique list=`list`)*。
## 分块
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| size | number | 必填 | 每块包含的元素数,必须为正数 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 把 list 按 size 分块 |
这里使用`list`、`size`。
调用效应:pure。
把 list 按 size 分块。
完成后返回*[把 list 按 size 分块](> host_list_chunk list=`list` size=`size`)*。
## 拉链
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | 必填 | 各配对中第一项来自的列表 |
| b | any | 必填 | 各配对中第二项来自的列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 将 a 与 b 配对,取较短长度 |
这里使用`a`、`b`。
调用效应:pure。
将 a 与 b 配对,取较短长度。
完成后返回*[将 a 与 b 配对,取较短长度](> host_list_zip a=`a` b=`b`)*。
## 展平
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 list 做一层展平 |
这里使用`list`。
调用效应:pure。
对 list 做一层展平。
完成后返回*[对 list 做一层展平](> host_list_flatten list=`list`)*。
## 清空
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | 必填 | 运行时值;具体规则见下方操作说明 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 按类型清空 value(空列表或空字典) |
这里使用`value`。
调用效应:pure。
按类型清空 value(空列表或空字典)。
完成后返回*[按类型清空 value(空列表或空字典)](> host_collection_clear value=`value`)*。
## 取键
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| key | text | 必填 | 本操作需要的字段名或键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 浅取 map 的 key;缺键 → None |
这里使用`map`、`key`。
调用效应:pure。
浅取 map 的 key;缺键 → None。作者侧优先access 取元。
完成后返回*[浅取 map 的 key;缺键 → None](> host_map_get map=`map` key=`key`)*。
## 设
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| key | text | 必填 | 本操作需要的字段名或键 |
| value | any | 必填 | 运行时值;具体规则见下方操作说明 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 浅设 map 的 key 为 value;嵌套请用「改」 |
这里使用`map`、`key`、`value`。
调用效应:pure。
浅设 map 的 key 为 value;嵌套请用「改」。
完成后返回*[浅设 map 的 key 为 value;嵌套请用「改」](> host_map_set map=`map` key=`key` value=`value`)*。
## 删键
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| key | text | 必填 | 本操作需要的字段名或键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 从 map 删除 key |
这里使用`map`、`key`。
调用效应:pure。
从 map 删除 key。
完成后返回*[从 map 删除 key](> host_map_delete map=`map` key=`key`)*。
## 有键
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| key | text | 必填 | 本操作需要的字段名或键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | bool | map 是否有 key |
这里使用`map`、`key`。
调用效应:pure。
map 是否有 key。
完成后返回*[map 是否有 key](> host_map_has map=`map` key=`key`)*。
## 键表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | map 的键表 |
这里使用`map`。
调用效应:pure。
map 的键表。
完成后返回*[map 的键表](> host_map_keys map=`map`)*。
## 值表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | map 的值表 |
这里使用`map`。
调用效应:pure。
map 的值表。
完成后返回*[map 的值表](> host_map_values map=`map`)*。
## 项表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | map 的键值对行表 |
这里使用`map`。
调用效应:pure。
map 的键值对行表。
完成后返回*[map 的键值对行表](> host_map_items map=`map`)*。
## 合并
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | 必填 | 基础记录;None 用作空记录种子 |
| b | any | 必填 | 合入 a 的记录;后面的值覆盖同名键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 合并 a 与 b(右侧覆盖左侧) |
这里使用`a`、`b`。
调用效应:pure。
合并 a 与 b(右侧覆盖左侧)。
完成后返回*[合并 a 与 b(右侧覆盖左侧)](> host_map_merge a=`a` b=`b`)*。
## 键数
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | map 的键数 |
这里使用`map`。
调用效应:pure。
map 的键数。
完成后返回*[map 的键数](> host_map_size map=`map`)*。
## 空表
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 空列表 |
调用效应:pure。
空列表。
完成后返回*[空列表](> host_list_concat a=None b=None)*。
## 空字典
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 返回新的空字典,作为不可变更新的种子;它与空列表不同 |
调用效应:pure。
返回新的空字典,作为不可变更新的种子;它与空列表不同。
完成后返回*[返回新的空字典,作为不可变更新的种子;它与空列表不同](> host_map_merge a=None b=None)*。
## 序列
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 起 | number | 必填 | 序列的第一个数值 |
| 止 | number | 必填 | 序列不包含的终止边界 |
| 步长 | number | 1 | 非零序列步长;符号必须朝向终点 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 生成左闭右开的整数序列;允许负步长,拒绝零步长,最多一百万项。 |
这里使用`起`、`止`、`步长`=1。
调用效应:pure。
生成左闭右开的整数序列;允许负步长,拒绝零步长,最多一百万项。
完成后返回*[生成左闭右开的整数序列;允许负步长,拒绝零步长,最多一百万项](> host_table_range start=`起` end=`止` step=`步长`)*。
## 编号
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 起 | number | 0 | 第一条记录所用的索引值;默认从一开始 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 返回 index/value 记录列表;编号从 start 开始,输入不变。 |
这里使用`列表`、`起`=0。
调用效应:pure。
返回 index/value 记录列表;编号从 start 开始,输入不变。
完成后返回*[返回 index/value 记录列表;编号从 start 开始,输入不变](> host_table_enumerate list=`列表` start=`起`)*。
## 提列
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 逐行提取一个字段;缺少字段时报错,不悄悄变为空。 |
这里使用`列表`、`键`。
调用效应:pure。
逐行提取一个字段;缺少字段时报错,不悄悄变为空。
完成后返回*[逐行提取一个字段;缺少字段时报错,不悄悄变为空](> host_table_pluck list=`列表` key=`键`)*。
## 投影
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键表 | list | 必填 | 按顺序排列的字段名列表 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 按 keys 顺序保留字段;每个字段必须存在。 |
这里使用`列表`、`键表`。
调用效应:pure。
按 keys 顺序保留字段;每个字段必须存在。
完成后返回*[按 keys 顺序保留字段;每个字段必须存在](> host_table_project list=`列表` keys=`键表`)*。
## 筛选
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 值 | any | 必填 | 待转换或保存的值;不会就地修改输入 |
| 操作 | text | "eq" | 本接口支持的操作名 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 筛选匹配记录。op 为 eq/ne/gt/ge/lt/le/contains/in;这是固定操作名,不执行文本代码。 |
这里使用`列表`、`键`、`值`、`操作`="eq"。
调用效应:pure。
筛选匹配记录。op 为 eq/ne/gt/ge/lt/le/contains/in;这是固定操作名,不执行文本代码。
完成后返回*[筛选匹配记录](> host_table_where list=`列表` key=`键` value=`值` op=`操作`)*。
## 分组
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 按首次出现顺序返回 key/count/rows 记录;分组键保留原类型。 |
这里使用`列表`、`键`。
调用效应:pure。
直接调用此函数:
```sh
marqdo call lib/表.mq.md 分组 '列表=[{"team":"a","n":3},{"team":"b","n":1},{"team":"a","n":2}]' '键="team"' --effects none --json
```
按首次出现顺序返回 key/count/rows 记录;分组键保留原类型。
完成后返回*[按首次出现顺序返回 key/count/rows 记录;分组键保留原类型](> host_table_group_by list=`列表` key=`键`)*。
## 按键去重
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 每个字段值保留第一条记录,维持输入顺序。 |
这里使用`列表`、`键`。
调用效应:pure。
每个字段值保留第一条记录,维持输入顺序。
完成后返回*[每个字段值保留第一条记录,维持输入顺序](> host_table_unique_by list=`列表` key=`键`)*。
## 聚合
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | any | None | 要读取、比较或更新的字段名或存储键 |
| 操作 | text | "sum" | 本接口支持的操作名 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | number | 聚合标量列表或一个字段:sum/count/min/max/mean。空表求和与计数为零;空表最值与均值失败;整数求和检查溢出。 |
这里使用`列表`、`键`=None、`操作`="sum"。
调用效应:pure。
聚合标量列表或一个字段:sum/count/min/max/mean。空表求和与计数为零;空表最值与均值失败;整数求和检查溢出。
完成后返回*[聚合标量列表或一个字段:sum/count/min/max/mean](> host_table_aggregate list=`列表` key=`键` op=`操作`)*。
## 多键排序
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键表 | list | 必填 | 按顺序排列的字段名列表 |
| 降序 | bool | False | 是否按多键降序排列 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 按 keys 的字段顺序稳定排序;descending 改变比较方向,相同键保持顺序。 |
这里使用`列表`、`键表`、`降序`=False。
调用效应:pure。
按 keys 的字段顺序稳定排序;descending 改变比较方向,相同键保持顺序。
完成后返回*[按 keys 的字段顺序稳定排序;descending 改变比较方向,相同键保持顺序](> host_table_sort_keys list=`列表` keys=`键表` descending=`降序`)*。
## 改字段名
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 字段 | map | 必填 | 附加到日志事件的结构化字段与值记录 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 用旧名到新名的字典改字段名;输出字段重名时报错。 |
这里使用`列表`、`字段`。
调用效应:pure。
用旧名到新名的字典改字段名;输出字段重名时报错。
完成后返回*[用旧名到新名的字典改字段名;输出字段重名时报错](> host_table_rename list=`列表` fields=`字段`)*。
## 列转行
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列 | map | 必填 | 列名与列表记录;各列长度必须一致 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 把列式字典转为行记录;各列必须是等长列表,不猜测普通对象字段。 |
这里使用`列`。
调用效应:pure。
把列式字典转为行记录;各列必须是等长列表,不猜测普通对象字段。
完成后返回*[把列式字典转为行记录;各列必须是等长列表,不猜测普通对象字段](> host_table_from_columns columns=`列`)*。
## 行转列
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 行 | list | 必填 | 行记录列表,不是隐式列式表 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | map | 把字段集合相同的行记录转为列式字典;空输入返回空字典。 |
这里使用`行`。
调用效应:pure。
把字段集合相同的行记录转为列式字典;空输入返回空字典。
完成后返回*[把字段集合相同的行记录转为列式字典;空输入返回空字典](> host_table_to_columns rows=`行`)*。
## 连接
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 左 | list | 必填 | 第一个操作数;适用范围见本操作说明 |
| 右 | list | 必填 | 第二个操作数;适用范围见本操作说明 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 右键 | text | 必填 | 右侧记录中用于匹配的字段 |
| 模式 | text | "inner" | 连接方式:inner 或 left |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 按字段相等连接;保持左表和右表匹配顺序。mode 为 inner/left;右侧重名字段加 right_ 前缀,仍冲突则失败。 |
这里使用`左`、`右`、`键`、`右键`、`模式`="inner"。
调用效应:pure。
按字段相等连接;保持左表和右表匹配顺序。mode 为 inner/left;右侧重名字段加 right_ 前缀,仍冲突则失败。
完成后返回*[按字段相等连接;保持左表和右表匹配顺序](> host_table_join a=`左` b=`右` key=`键` right_key=`右键` mode=`模式`)*。
## 转字段类型
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 行 | list | 必填 | 行记录列表,不是隐式列式表 |
| 规则 | map | 必填 | 字段与类型记录,采用标准契约类型词汇 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 按 schema 转换 text/int/number/bool/any 字段;缺失或无效值报告行号和字段,保留其他字段。 |
这里使用`行`、`规则`。
调用效应:pure。
按 schema 转换 text/int/number/bool/any 字段;缺失或无效值报告行号和字段,保留其他字段。
完成后返回*[按 schema 转换 text/int/number/bool/any 字段;缺失或无效值报告行号和字段,保留其他字段](> host_table_cast rows=`行` schema=`规则`)*。
## 并集
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 左 | list | 必填 | 第一个操作数;适用范围见本操作说明 |
| 右 | list | 必填 | 第二个操作数;适用范围见本操作说明 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 保持首次出现顺序的并集;值相等规则与去重一致,区分类型。 |
这里使用`左`、`右`。
调用效应:pure。
保持首次出现顺序的并集;值相等规则与去重一致,区分类型。
完成后返回*[保持首次出现顺序的并集;值相等规则与去重一致,区分类型](> host_table_union a=`左` b=`右`)*。
## 交集
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 左 | list | 必填 | 第一个操作数;适用范围见本操作说明 |
| 右 | list | 必填 | 第二个操作数;适用范围见本操作说明 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 保持输入顺序的交集,去除重复值。 |
这里使用`左`、`右`。
调用效应:pure。
保持输入顺序的交集,去除重复值。
完成后返回*[保持输入顺序的交集,去除重复值](> host_table_intersection a=`左` b=`右`)*。
## 差集
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 左 | list | 必填 | 第一个操作数;适用范围见本操作说明 |
| 右 | list | 必填 | 第二个操作数;适用范围见本操作说明 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 保留左表中不在右表的值,维持顺序并去重。 |
这里使用`左`、`右`。
调用效应:pure。
保留左表中不在右表的值,维持顺序并去重。
完成后返回*[保留左表中不在右表的值,维持顺序并去重](> host_table_difference a=`左` b=`右`)*。
## 尝试转类型
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 行 | list | 必填 | 行记录列表,不是隐式列式表 |
| 规则 | map | 必填 | 字段与类型记录,采用标准契约类型词汇 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | map | 可恢复地转换字段;无效字段返回结果记录,不中断调用方。 |
这里使用`行`、`规则`。
调用效应:pure。
可恢复地转换字段;无效字段返回结果记录,不中断调用方。
完成后返回*[可恢复地转换字段;无效字段返回结果记录,不中断调用方](> host_table_try_cast rows=`行` schema=`规则`)*。
## 校验记录
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 行 | list | 必填 | 行记录列表,不是隐式列式表 |
| 规则 | map | 必填 | 字段与类型记录,采用标准契约类型词汇 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | map | 按核心渐进式类型校验必需字段,结果错误含 details 行号与字段诊断;int 是核心 number 别名,严格整数转换使用转字段类型。 |
这里使用`行`、`规则`。
调用效应:pure。
按核心渐进式类型校验必需字段,结果错误含 details 行号与字段诊断;int 是核心 number 别名,严格整数转换使用转字段类型。
完成后返回*[按核心渐进式类型校验必需字段,结果错误含 details 行号与字段诊断;int 是核心 number 别名,严格整数转换使用转字段类型](> host_table_validate rows=`行` schema=`规则`)*。
## 查找首项
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 按原有顺序检查的行记录列表,不会就地修改 |
| 键 | text | 必填 | 每行需要读取并比较的字段名 |
| 值 | any | 必填 | 比较右值;in 操作在此集合中测试成员关系 |
| 操作 | text | "eq" | eq、ne、gt、ge、lt、le、contains 或 in;无效操作会失败 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 首个匹配行;没有匹配时为空值 |
这里使用`列表`、`键`、`值`、`操作`="eq"。
调用效应:pure。
复用同一筛选规则,保持原行顺序且不修改输入;缺失字段或无效操作仍会产生诊断。
得到**`selected` = [调用 筛选](筛选(列表=`列表`, 键=`键`, 值=`值`, 操作=`操作`))**。
完成后返回*[调用 首](首(list=`selected`))*。
## 任一满足
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 按原有顺序检查的行记录列表,不会就地修改 |
| 键 | text | 必填 | 每行需要读取并比较的字段名 |
| 值 | any | 必填 | 比较右值;in 操作在此集合中测试成员关系 |
| 操作 | text | "eq" | eq、ne、gt、ge、lt、le、contains 或 in;无效操作会失败 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | bool | 是否至少一行匹配;空列表为假 |
这里使用`列表`、`键`、`值`、`操作`="eq"。
调用效应:pure。
复用同一筛选规则,保持原行顺序且不修改输入;缺失字段或无效操作仍会产生诊断。
得到**`selected` = [调用 筛选](筛选(列表=`列表`, 键=`键`, 值=`值`, 操作=`操作`))**。
得到**`matched` = [调用 len](len(`selected`))**。
完成后返回*matched > 0*。
## 全部满足
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 按原有顺序检查的行记录列表,不会就地修改 |
| 键 | text | 必填 | 每行需要读取并比较的字段名 |
| 值 | any | 必填 | 比较右值;in 操作在此集合中测试成员关系 |
| 操作 | text | "eq" | eq、ne、gt、ge、lt、le、contains 或 in;无效操作会失败 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | bool | 是否每行都匹配;空列表为真 |
这里使用`列表`、`键`、`值`、`操作`="eq"。
调用效应:pure。
复用同一筛选规则,保持原行顺序且不修改输入;缺失字段或无效操作仍会产生诊断。
得到**`selected` = [调用 筛选](筛选(列表=`列表`, 键=`键`, 值=`值`, 操作=`操作`))**。
得到**`matched` = [调用 len](len(`selected`))**。
得到**`total` = [调用 len](len(`列表`))**。
完成后返回*matched == total*。
## 分组汇总
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 分组键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 字段 | text | 必填 | 各分组内需要聚合的数值字段 |
| 操作 | text | "sum" | 本接口支持的操作名 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 批量按键分组并聚合一个字段,返回 key/count/value 行记录,保持首次分组顺序;操作规则同聚合,避免在作者循环中反复复制增长的结果列表。 |
这里使用`列表`、`分组键`、`字段`、`操作`="sum"。
调用效应:pure。
批量按键分组并聚合一个字段,返回 key/count/value 行记录,保持首次分组顺序;操作规则同聚合,避免在作者循环中反复复制增长的结果列表。
完成后返回*[批量按键分组并聚合一个字段,返回 key/count/value 行记录,保持首次分组顺序;操作规则同聚合,避免在作者循环中反复复制增长的结果列表](> host_table_summarize list=`列表` key=`分组键` field=`字段` op=`操作`)*。
## 键值转记录
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 键值对 | list | 必填 | 有序行记录,每行含文本 key 与任意 value 字段;其他字段不参与构造 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | map | 新记录;首次出现的键决定顺序,后续同名键替换其值 |
调用效应:pure。
输入`键值对`采用普通 @ 行记录表,把过宽的横向记录改写成可逐行阅读的 key/value 数据。
适合提示章节、配置片段和具名字段较多的记录;这里复用本库既有的不可变更新,
不解析 JSON 文本,也不另造表格方言。空列表得到空记录,缺少或无效的键交给改操作报告,
不会为了制造字典而添加一个无意义的占位列。
先准备**记录 = [创建新的空记录](空字典())**,再按行读取字段,使每一项的来源都保持可见。
- [把每条具名字段写入新记录](遍历 键值对 为 键值行)
读取**键 = [取出本行的字段名](access(键值行, "key"))**,
以及**值 = [取出本行的字段值](access(键值行, "value"))**。
然后保留**记录 = [设置字段而不修改输入行](改(入=`记录`, 于=`键`, 值=`值`))**。
处理完有序行后,返回*记录*。同名字段保留第一次出现的位置并更新其值;
原来的键值对仍可继续使用,本操作没有文件、网络或插件副作用。