文档章节
集合函数
用这些函数操作与查询映射(map)、切片(slice)和字符串。
这一页解决什么问题
collections 下的函数做的事可以概括成四类:造数据(slice、dict、seq)、筛选与截取(where、first、last、after、in)、集合运算(intersect、union、complement、symdiff、uniq)、排序与派生(sort、reverse、shuffle、D、apply、merge、querify),外加两个查找工具 index、isset。
写列表页、标签云、相关文章、随机推荐时,几乎都要从这一章挑函数。反过来说,模板里大多数「没报错但结果不对」的问题,也都出在这些函数的参数顺序与类型上——各页末尾的「返回值边界(实测)」小节就是为这个准备的。
读完本章你应该能够
- 用
slice、dict、seq造出模板里的数据与测试用例,并说清切片与映射的区别; - 用
where筛选、用first/last/after截取,并说明为什么不能拿first去按字符截断中文; - 用
intersect/union/complement/symdiff表达交集、并集、单向减法、对称差,并指出四者的顺序语义差别; - 用
sort/uniq/reverse得到想要的顺序,知道标量切片降序必须写成"value" "desc"; - 用
index/isset取值,并解释「取不到也不报错」会带来什么风险; - 判断什么时候该改用页面集合自带的方法(
GroupBy、ByDate等)。
什么时候用本章的函数,什么时候别用
该用:
- 处理的是纯数据(
slice、dict、配置项、hugo.Data读入的数据),而不是页面集合; - 需要集合运算:交集、并集、单向减法、去重;
- 需要把结果继续交给
range、len、delimit处理。
别用:
- 要排序、分组、分页页面集合 → 优先用页面集合自带的方法(methods/pages),它们更贴合 Page,还能直接配合分页;
- 要处理字符串(截断、替换、大小写)→ 用 functions/strings 下的函数;
- 要做算术 → 用 functions/math;
- 要格式化日期 → 用 functions/time。
阅读顺序
按「先造、再筛、再运算、最后查找」用:
- 造数据:collections.Slice → collections.Dictionary → collections.Seq
- 筛选与截取:collections.Where → collections.First → collections.Last → collections.After → collections.In
- 集合运算:collections.Intersect → collections.Union → collections.Complement → collections.SymDiff → collections.Uniq
- 排序与随机:collections.Sort → collections.Reverse → collections.Shuffle → collections.D
- 查找、合并与转换:collections.Index → collections.IsSet → collections.KeyVals → collections.Merge → collections.Querify → collections.Apply → collections.Group
映射(map)与切片(slice)的取舍贯穿全章:要按键查找用映射,要保持顺序、去重、做切片操作用切片。
完整示例:把多篇文章的标签汇总成一张表
layouts/_partials/tag-table.htmlgo-html-template
{{ $posts := slice
(dict "title" "A" "tags" (slice "Hugo" "Go"))
(dict "title" "B" "tags" (slice "Go"))
(dict "title" "C" "tags" (slice "Hugo")) }}
{{ $tags := slice }}
{{ range $posts }}{{ range .tags }}{{ $tags = $tags | append . }}{{ end }}{{ end }}
<p>全部(含重复):{{ $tags }}</p>
<p>去重:{{ $tags | uniq }}</p>
<p>去重并排序:{{ $tags | uniq | collections.Sort }}</p>
<p>带 Go 的文章:{{ range where $posts "tags" "intersect" (slice "Go") }}{{ .title }} {{ end }}</p>Hugo 渲染为:
html
<p>全部(含重复):[Hugo Go Go Hugo]</p>
<p>去重:[Hugo Go]</p>
<p>去重并排序:[Go Hugo]</p>
<p>带 Go 的文章:A B </p>你应当看到什么:append 只追加、不去重;uniq 保序去重;sort 才真正排序。筛选时字段本身是切片,所以要用 "intersect" 这类匹配切片的运算符——实测把 "intersect" 换成 "in" 会得到空结果。
本章内容
- collections.After 返回给定切片中位于前 N 个元素之后的元素所组成的切片。 (今天)
- collections.Append 把单个或多个元素,或者另一个完整切片,追加到给定切片的末尾并返回新切片。 (今天)
- collections.Apply 用指定的函数及参数逐个转换给定切片的元素,返回新切片。 (今天)
- collections.Complement 找出只出现在最后一个给定切片中、而不出现在前面任何切片中的元素,返回这些元素组成的切片。 (今天)
- collections.D 根据给定的种子、数量和最大值,返回一个已排序且互不重复的随机整数切片。 (今天)
- collections.Delimit 用指定的分隔符连接给定切片或映射中的值,返回一个字符串。 (今天)
- collections.Dictionary 根据给定的键值对创建一个映射(map)。 (今天)
- collections.First 返回给定切片或字符串的前 N 个元素。 (今天)
- collections.Group 按指定 key 对给定的页面集合(切片)分组,返回一个映射。 (今天)
- collections.In 报告某个值是否存在于给定的切片或字符串中。 (今天)
- collections.Index 按指定的一个或多个 key,从给定的切片或映射中取出元素或值。 (今天)
- collections.Intersect 返回两个给定切片中的公共元素,顺序与第一个切片一致。 (今天)
- collections.IsSet 报告给定的映射或切片中是否存在指定的 key 或索引。 (今天)
- collections.KeyVals 把给定的 key 与一组值配对,返回一个 KeyVals 结构。 (今天)
- collections.Last 返回给定切片或字符串的最后 N 个元素。 (今天)
- collections.Merge 把两个或多个给定映射合并为一个映射并返回。 (今天)
- collections.NewScratch 返回一个局部作用域的持久化数据结构,用于存储和操作带 key 的值。 (今天)
- collections.Querify 根据给定的映射、切片或键值对序列,返回 URL 查询字符串。 (今天)
- collections.Reverse 把给定切片中的元素顺序反转后返回。 (今天)
- collections.Seq 返回一个整数切片:从 1 或指定值开始,按 1 或指定步长递增,到指定值结束。 (今天)
- collections.Shuffle 把给定切片中的元素顺序随机打乱后返回。 (今天)
- collections.Slice 根据给定的值创建一个切片。 (今天)
- collections.Sort 按指定的 key 与顺序重排给定集合,返回排序后的映射或切片。 (今天)
- collections.SymDiff 返回两个给定切片的对称差集(symmetric difference)。 (今天)
- collections.Union 返回两个给定切片中的全部不重复元素。 (今天)
- collections.Uniq 去掉给定切片中的重复元素后返回。 (今天)
- collections.Where 按指定的 key、运算符和值筛选给定切片,返回满足条件的元素。 (今天)