文档章节

集合函数

用这些函数操作与查询映射(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。

阅读顺序

按「先造、再筛、再运算、最后查找」用:

  1. 造数据:collections.Slice → collections.Dictionary → collections.Seq
  2. 筛选与截取:collections.Where → collections.First → collections.Last → collections.After → collections.In
  3. 集合运算:collections.Intersect → collections.Union → collections.Complement → collections.SymDiff → collections.Uniq
  4. 排序与随机:collections.Sort → collections.Reverse → collections.Shuffle → collections.D
  5. 查找、合并与转换: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、运算符和值筛选给定切片,返回满足条件的元素。 (今天)