--- 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"))**。 然后保留**记录 = [设置字段而不修改输入行](改(入=`记录`, 于=`键`, 值=`值`))**。 处理完有序行后,返回*记录*。同名字段保留第一次出现的位置并更新其值; 原来的键值对仍可继续使用,本操作没有文件、网络或插件副作用。