mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-29 22:29:56 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/content/en/functions/collections/Where.md
View File

@@ -3,12 +3,11 @@ title: collections.Where
description: Returns the given collection, removing elements that do not satisfy the comparison condition.
categories: []
keywords: []
action:
aliases: [where]
related: []
returnType: any
signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE']
toc: true
params:
functions_and_methods:
aliases: [where]
returnType: any
signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE']
aliases: [/functions/where]
---
@@ -87,12 +86,12 @@ Use any of the following logical operators:
`intersect`
: (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect).
`like` {{< new-in 0.116.0 />}}
: (`bool`) Reports whether the given field value matches the regular expression specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression.
`like`
: {{< new-in 0.116.0 />}}
: (`bool`) Reports whether the given field value matches the [regular expression](g) specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression.
{{% note %}}
The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.
{{% /note %}}
> [!note]
> The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.
## String comparison
@@ -155,7 +154,7 @@ To return a collection of pages where the "color" page parameter is neither "red
## Intersection comparison
Compare a [`slice`] to a [`slice`], returning collection elements with common values. This is frequently used when comparing taxonomy terms.
Compare a `slice` to a `slice`, returning collection elements with common values. This is frequently used when comparing taxonomy terms.
For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance":
@@ -176,11 +175,10 @@ To return a collection of pages where the "author" page parameter begins with ei
{{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }}
```
{{% include "functions/_common/regular-expressions.md" %}}
{{% include "/_common/functions/regular-expressions.md" %}}
{{% note %}}
Use the `like` operator to compare string values. Comparing other data types will result in an empty collection.
{{% /note %}}
> [!note]
> Use the `like` operator to compare string values. Comparing other data types will result in an empty collection.
## Date comparison
@@ -188,12 +186,6 @@ Use the `like` operator to compare string values. Comparing other data types wil
There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons.
[`date`]: /methods/page/date/
[`publishdate`]: /methods/page/publishdate/
[`lastmod`]: /methods/page/lastmod/
[`expirydate`]: /methods/page/expirydate/
[`time.Time`]: https://pkg.go.dev/time#Time
For example, to return a collection of pages that were created before the current year:
```go-html-template
@@ -205,20 +197,19 @@ For example, to return a collection of pages that were created before the curren
With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON).
{{% note %}}
Using TOML for pages with custom front matter dates enables precise date comparisons.
{{% /note %}}
> [!note]
> Using TOML for pages with custom front matter dates enables precise date comparisons.
With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons.
In the TOML example below, note that the event date is not quoted.
{{< code file="content/events/2024-user-conference.md" >}}
```text {file="content/events/2024-user-conference.md"}
+++
title = '2024 User Conference"
eventDate = 2024-04-01
+++
{{< /code >}}
```
To return a collection of future events:
@@ -272,8 +263,6 @@ These are equivalent:
Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object.
[`MainSections`]: /methods/site/mainsections/
```go-html-template
{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
```
@@ -281,11 +270,10 @@ Useful for theme authors, avoid hardcoding section names by using the `where` fu
With this construct, a theme author can instruct users to specify their main sections in the site configuration:
{{< code-toggle file=hugo >}}
[params]
mainSections = ['blog','galleries']
{{< /code-toggle >}}
If `params.mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top level section with the most pages.
If `mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages.
## Boolean/undefined comparison
@@ -387,13 +375,11 @@ To exclude a page with an undefined field from a boolean _inequality_ test:
1. Create a collection using a nil comparison
1. Subtract the second collection from the first collection using the [`collections.Complement`] function.
[`collections.Complement`]: /functions/collections/complement/
This template:
```go-html-template
{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }}
{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
<ul>
{{ range $p1 | complement $p2 }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
@@ -413,7 +399,7 @@ This template:
```go-html-template
{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }}
{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
<ul>
{{ range $p1 | complement $p2 }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
@@ -428,3 +414,9 @@ Is rendered to:
<li><a href="/posts/post-1/">Post 2</a></li>
</ul>
```
[`collections.Complement`]: /functions/collections/complement/
[`date`]: /methods/page/date/
[`lastmod`]: /methods/page/lastmod/
[`MainSections`]: /methods/site/mainsections/
[`time.Time`]: https://pkg.go.dev/time#Time