Hugo 模板函数 strings.Count：统计子串出现次数的方法与源码原理-平芜编程栈

Hugo 模板函数 strings.Count：统计子串出现次数的方法与源码原理

【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo

导读

strings.Count是 Hugo 模板中strings命名空间下的字符串处理函数，用于统计一个字符串中某个子串出现的次数。它既可以在页面模板中统计标签、关键词或特殊字符的出现频率，也可以配合if条件实现基于次数的逻辑分支。本文以 Count.md 文档为骨架，结合 Hugo 仓库源码（tpl/strings包）深入讲解该函数的签名、边界行为、管道调用方式、Go 标准库实现原理，以及与strings.CountRunes、strings.CountWords等相邻函数的区别，帮助读者准确使用并理解其底层机制。

函数签名与返回类型

strings.Count的签名与返回类型定义如下：

项目	值
函数签名	`strings.Count SUBSTR STRING`
返回类型	`int`
参数顺序	第一个参数`SUBSTR`（要查找的子串），第二个参数`STRING`（被搜索的字符串）

与 Go 标准库strings.Count(s, substr string)的参数顺序不同，Hugo 模板函数把子串放在前面、被搜索的字符串放在后面。这种参数顺序的设计是为了配合 Hugo 模板的管道（pipeline）语法：管道左侧的值会自动作为最后一个参数传入函数。因此下面的两种写法完全等价：

{{ strings.Count "a" "aaabaab" }} → 3 {{ "aaabaab" | strings.Count "a" }} → 3

其中第二种写法（管道形式）是 Hugo 模板中最常见、最符合阅读习惯的用法，文档示例也采用了这种形式。

行为定义：非重叠子串计数

strings.Count统计的是SUBSTR在STRING中出现的非重叠（non-overlapping）实例个数。所谓非重叠，是指每次匹配完成后，下一次匹配从上次匹配结束的位置之后继续查找，已匹配过的字符不会被重复计入。

这一点在源码注释中有明确说明（tpl/strings/strings.go）：

// Count counts the number of non-overlapping instances of substr in s. // If substr is an empty string, Count returns 1 + the number of Unicode code points in s. func (ns *Namespace) Count(substr, s any) (int, error) { substrs, err := cast.ToStringE(substr) if err != nil { return 0, fmt.Errorf("failed to convert substr to string: %w", err) } ss, err := cast.ToStringE(s) if err != nil { return 0, fmt.Errorf("failed to convert s to string: %w", err) } return strings.Count(ss, substrs), nil }

从源码可以看出，Count方法本身只是薄封装：它先用cast.ToStringE把两个any类型的参数转换为字符串，然后直接调用 Go 标准库的strings.Count完成实际计数。这意味着它的语义与 Go 标准库完全一致。

文档给出的完整示例（Count.md）：

{{ "aaabaab" | strings.Count "a" }} → 5 {{ "aaabaab" | strings.Count "aa" }} → 2 {{ "aaabaab" | strings.Count "aaa" }} → 1 {{ "aaabaab" | strings.Count "" }} → 8

逐行解读：

"aaabaab"中字母a出现在位置 0、1、3、4、6，共5次；
子串"aa"在位置 0-1 和 3-4 各出现一次，共2次（位置 1-2 的aa因与第一次匹配重叠而被跳过，位置 4-5 的aa也因与第二次匹配重叠而跳过）；
子串"aaa"只在位置 0-2 出现一次，共1次；
空子串""的特殊行为见下文。

空子串的特殊行为：1 + Unicode 码点数

当SUBSTR为空字符串""时，strings.Count返回1 加上STRING中 Unicode 码点（code point）的个数。

上例中"aaabaab"共 7 个字符（均为单码点 ASCII 字符），因此{{ "aaabaab" | strings.Count "" }}返回1 + 7 = 8。

这一行为继承自 Go 标准库strings.Count的约定（在bytes.Count中同样成立）：空子串在任意位置都可以匹配，Go 的实现约定为返回len(s) + 1（按字节）或码点意义下的等价结果，即"字符串的每个字符间隙加首尾两端"都可容纳一次空匹配。在 Hugo 封装中，计数按 Unicode 码点进行，因此对于包含多字节字符（如中文、emoji）的字符串，返回值是1 + 码点数，而不是1 + 字节数。例如：

{{ "你好" | strings.Count "" }} → 3 <!-- 2 个码点 + 1 -->

利用这一特性，可以用{{ strings.Count "" STRING }}变通地获取字符串的码点数量，不过 Hugo 也提供了更直接的strings.RuneCount函数（见下文对比）。

模板注册与管道调用方式

strings.Count通过AddMethodMapping注册到strings命名空间，并在注册时提供了一组示例输出用于文档与测试验证（tpl/strings/init.go）：

ns.AddMethodMapping(ctx.Count, nil, [][2]string{ {`{{ "aabab" | strings.Count "a" }}`, `3`}, }, )

这段注册代码同时给出了模板示例及其期望输出：{{ "aabab" | strings.Count "a" }}应渲染为3（aabab中a出现 3 次）。这既是 Hugo 内部对函数示例的自动化验证，也直接印证了管道调用的写法。

在模板中，strings.Count主要有两类应用场景：

1. 条件判断——统计某个字符或子串的出现次数并据此分支：

{{ if gt (strings.Count "," .Params.tags) 2 }} <p>标签较多，此处展示紧凑列表</p> {{ else }} <ul>{{ range .Params.tags }}<li>{{ . }}</li>{{ end }}</ul> {{ end }}

2. 渲染输出——直接输出统计结果：

{{ $content := .Content }} {{ $codeFences := strings.Count "```" $content }} <p>本文共包含 {{ div $codeFences 2 }} 个代码块。</p>

参数转换与错误处理

从 tpl/strings/strings.go 的实现可见，Count的两个参数类型均为any，内部通过cast.ToStringE做类型转换。这意味着：

传入的值可以是字符串、template.HTML、[]byte，甚至数字等可转换为字符串的类型；
转换失败时（例如传入无法转为字符串的自定义类型）会返回错误，错误信息为failed to convert substr to string或failed to convert s to string，并返回0。

与其他strings命名空间函数（如HasPrefix，见 tpl/strings/strings_test.go）一样，Count也遵循"转换失败即报错"的统一错误处理模式，便于在构建期暴露类型问题。

与相关计数函数的对比

strings命名空间中还提供了几个容易混淆的计数函数，它们都定义在 tpl/strings/strings.go 中，作用各不相同：

函数	统计内容	备注
`strings.Count`	指定子串在字符串中出现的非重叠次数	本文主题，等价于 Go 标准库`strings.Count`
`strings.RuneCount`	字符串的码点（rune）总数	调用`utf8.RuneCountInString`（strings.go），与`{{ strings.Count "" STRING }} - 1`结果一致
`strings.CountRunes`	去除 HTML 标签与空白后的码点数	先`StripHTML`再去空白（strings.go）
`strings.CountWords`	近似单词数	对 CJK 语言按字符计数，对西文按空白分词（strings.go）

典型选择建议：

统计某个字符或关键词出现次数 →strings.Count；
统计文章总字数（含标点/空白）→strings.RuneCount；
统计"有效字数"（剔除 HTML 标签与空白）→strings.CountRunes；
统计西文单词数或中日韩文字符数 →strings.CountWords。

例如，中文场景下常使用CountWords近似统计字数，因为它对\p{Han}等 CJK 字符集做了专门的按码点计数处理。

实战示例：统计文章中的关键词频率

下面是一个完整的页面模板示例，综合展示strings.Count在条件判断与输出两种场景中的用法：

{{ $title := .Title }} {{ $questionCount := strings.Count "?" $title }} <article> <h1>{{ $title }}</h1> <p>标题中的问号数量：{{ $questionCount }}</p> {{ if gt $questionCount 0 }} <p class="hint">这是一个以提问为主题的标题。</p> {{ end }} </article>

由于Count的返回值类型是int，可以直接与gt、eq、mod等比较/数学函数组合使用，也可以配合printf输出：

{{ printf "标题中出现 %d 次问号" $questionCount }}

小结

strings.Count SUBSTR STRING返回STRING中SUBSTR的非重叠出现次数，返回类型int；
子串为空时返回1 + Unicode 码点数，可用于变通计算字符串码点长度；
推荐使用管道写法{{ "str" | strings.Count "sub" }}，与文档及 init.go 中的注册示例一致；
底层是 Go 标准库strings.Count的薄封装，参数先经cast.ToStringE转换为字符串（strings.go），行为与 Go 标准库完全一致；
需要统计码点、去标签有效字数或单词数时，请分别选用strings.RuneCount、strings.CountRunes、strings.CountWords。