mirror of
https://github.com/gohugoio/hugo.git
synced 2025-04-27 14:10:31 +03:00
Merge commit '35dec7c96f'
This commit is contained in:
Bjørn Erik Pedersen
commit
d19ed4d4e6
810 changed files with 24147 additions and 7766 deletions
|
|
@ -1,64 +1,61 @@
|
|||
---
|
||||
title: time.AsTime
|
||||
linkTitle: time
|
||||
description: Converts a timestamp string into a `time.Time` structure.
|
||||
categories: [functions]
|
||||
description: Returns the given string representation of a date/time value as a time.Time value.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
function:
|
||||
action:
|
||||
aliases: [time]
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/Format
|
||||
- functions/time/Now
|
||||
- functions/time/ParseDuration
|
||||
returnType: time.Time
|
||||
signatures: ['time.AsTime INPUT [TIMEZONE]']
|
||||
relatedFunctions:
|
||||
- time.AsTime
|
||||
- time.Duration
|
||||
- time.Format
|
||||
- time.Now
|
||||
- time.ParseDuration
|
||||
aliases: [/functions/time]
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
`time` converts a timestamp string with an optional default location into a [`time.Time`](https://godoc.org/time#Time) structure so you can access its fields:
|
||||
Hugo provides [functions] and [methods] to format, localize, parse, compare, and manipulate date/time values. Before you can do any of these with string representations of date/time values, you must first convert them to [`time.Time`] values using the `time.AsTime` function.
|
||||
|
||||
```go-html-template
|
||||
{{ time "2016-05-28" }} → "2016-05-28T00:00:00Z"
|
||||
{{ (time "2016-05-28").YearDay }} → 149
|
||||
{{ mul 1000 (time "2016-05-28T10:30:00.00+10:00").Unix }} → 1464395400000, or Unix time in milliseconds
|
||||
{{ $t := "2023-10-15T14:20:28-07:00" }}
|
||||
{{ time.AsTime $t }} → 2023-10-15 14:20:28 -0700 PDT (time.Time)
|
||||
```
|
||||
|
||||
## Using locations
|
||||
## Parsable strings
|
||||
|
||||
The optional `TIMEZONE` argument is a string that sets a default time zone (or more specific, the location, which represents the collection of time offsets in a geographical area) that is associated with the specified time value. If the time value has an explicit timezone or offset specified, it will take precedence over the `TIMEZONE` argument.
|
||||
As shown above, the first argument must be a *parsable* string representation of a date/time value. For example:
|
||||
|
||||
The list of valid locations may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
|
||||
{{% include "functions/time/_common/parsable-date-time-strings.md" %}}
|
||||
|
||||
If no `TIMEZONE` is set, the `timeZone` from site configuration will be used.
|
||||
## Time zones
|
||||
|
||||
```go-html-template
|
||||
{{ time "2020-10-20" }} → 2020-10-20 00:00:00 +0000 UTC
|
||||
{{ time "2020-10-20" "America/Los_Angeles" }} → 2020-10-20 00:00:00 -0700 PDT
|
||||
{{ time "2020-01-20" "America/Los_Angeles" }} → 2020-01-20 00:00:00 -0800 PST
|
||||
```
|
||||
When the parsable string does not contain a time zone offset, you can do either of the following to assign a time zone other than Etc/UTC:
|
||||
|
||||
## Example: Using `time` to get month index
|
||||
- Provide a second argument to the `time.AsTime` function
|
||||
|
||||
The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"` in a content's front matter---converts the timestamp (string) to an integer using the [`int` function][int], and then uses [`printf`] to convert the `Month` property of `time` into an index.
|
||||
```go-html-template
|
||||
{{ time.AsTime "15 Oct 2023" "America/Chicago" }}
|
||||
```
|
||||
|
||||
The following example may be useful when setting up [multilingual sites][multilingual]:
|
||||
- Set the default time zone in your site configuration
|
||||
|
||||
{{< code file="unix-to-month-integer.html" >}}
|
||||
{{ $time := time (int .Params.addDate)}}
|
||||
=> $time = 1489276800
|
||||
{{ $time.Month }}
|
||||
=> "March"
|
||||
{{ $monthindex := printf "%d" $time.Month }}
|
||||
=> $monthindex = 3
|
||||
{{< /code >}}
|
||||
{{< code-toggle file=hugo >}}
|
||||
timeZone = 'America/New_York'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The order of precedence for determining the time zone is:
|
||||
|
||||
[int]: /functions/cast/toint
|
||||
[multilingual]: /content-management/multilingual/
|
||||
[`printf`]: /functions/fmt/printf
|
||||
1. The time zone offset in the date/time string
|
||||
2. The time zone provide as the second argument to the `time.AsTime` function
|
||||
3. The time zone specified in your site configuration
|
||||
|
||||
The list of valid time zones may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database].
|
||||
|
||||
[`time.Time`]: https://pkg.go.dev/time#Time
|
||||
[functions]: /functions/time/
|
||||
[iana time zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
|
||||
[methods]: /methods/time/
|
||||
|
|
|
|||
|
|
@ -1,40 +1,37 @@
|
|||
---
|
||||
title: time.Duration
|
||||
linkTitle: duration
|
||||
description: Returns a `time.Duration` structure, using the given time unit and duration number.
|
||||
categories: [functions]
|
||||
description: Returns a time.Duration value using the given time unit and number.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
function:
|
||||
action:
|
||||
aliases: [duration]
|
||||
related:
|
||||
- functions/time/AsTime
|
||||
- functions/time/Format
|
||||
- functions/time/Now
|
||||
- functions/time/ParseDuration
|
||||
returnType: time.Duration
|
||||
signatures: [time.Duration TIME_UNIT DURATION_NUMBER]
|
||||
relatedFunctions:
|
||||
- time.AsTime
|
||||
- time.Duration
|
||||
- time.Format
|
||||
- time.Now
|
||||
- time.ParseDuration
|
||||
signatures: [time.Duration TIME_UNIT NUMBER]
|
||||
aliases: [/functions/duration]
|
||||
---
|
||||
|
||||
`time.Duration` converts a given number into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields. E.g. you can perform [time operations](https://pkg.go.dev/time#Duration) on the returned `time.Duration` value:
|
||||
The `time.Duration` function returns a [`time.Duration`] value that you can use with any of the `Duration` [methods].
|
||||
|
||||
This template:
|
||||
|
||||
```go-html-template
|
||||
{{ printf "There are %.0f seconds in one day." (duration "hour" 24).Seconds }}
|
||||
<!-- Output: There are 86400 seconds in one day. -->
|
||||
{{ $duration := time.Duration "hour" 24 }}
|
||||
{{ printf "There are %.0f seconds in one day." $duration.Seconds }}
|
||||
```
|
||||
|
||||
Make your code simpler to understand by using a [chained pipeline](https://pkg.go.dev/text/template#hdr-Pipelines):
|
||||
Is rendered to:
|
||||
|
||||
```go-html-template
|
||||
{{ mul 7.75 60 | duration "minute" }} → 7h45m0s
|
||||
{{ mul 120 60 | mul 1000 | duration "millisecond" }} → 2h0m0s
|
||||
```text
|
||||
There are 86400 seconds in one day.
|
||||
```
|
||||
|
||||
You have to specify a time unit for the number given to the function. Valid time units are:
|
||||
The time unit must be one of the following:
|
||||
|
||||
|
||||
Duration|Valid time units
|
||||
:--|:--
|
||||
|
|
@ -44,3 +41,6 @@ seconds|`second`, `s`
|
|||
milliseconds|`millisecond`, `ms`
|
||||
microseconds|`microsecond`, `us`, `µs`
|
||||
nanoseconds|`nanosecond`, `ns`
|
||||
|
||||
[`time.Duration`]: https://pkg.go.dev/time#Duration
|
||||
[methods]: /methods/duration
|
||||
|
|
|
|||
|
|
@ -1,51 +1,52 @@
|
|||
---
|
||||
title: time.Format
|
||||
description: Returns a formatted and localized time.Time value.
|
||||
categories: [functions]
|
||||
description: Returns the given date/time as a formatted and localized string.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
function:
|
||||
action:
|
||||
aliases: [dateFormat]
|
||||
related:
|
||||
- functions/time/AsTime
|
||||
- functions/time/Duration
|
||||
- functions/time/Now
|
||||
- functions/time/ParseDuration
|
||||
returnType: string
|
||||
signatures: [time.Format LAYOUT INPUT]
|
||||
relatedFunctions:
|
||||
- time.AsTime
|
||||
- time.Duration
|
||||
- time.Format
|
||||
- time.Now
|
||||
- time.ParseDuration
|
||||
aliases: [/functions/dateformat]
|
||||
toc: true
|
||||
---
|
||||
|
||||
```go-template
|
||||
{{ $t := "2023-01-27T23:44:58-08:00" }}
|
||||
{{ $format := "2 Jan 2006" }}
|
||||
Use the `time.Format` function with `time.Time` values:
|
||||
|
||||
{{ $t | time.Format $format }} → 27 Jan 2023
|
||||
|
||||
{{ $t = time.AsTime $t }}
|
||||
{{ $t | time.Format $format }} → 27 Jan 2023
|
||||
```go-html-template
|
||||
{{ $t := time.AsTime "2023-02-27T23:44:58-08:00" }}
|
||||
{{ time.Format "2 Jan 2006" $t }} → 27 Feb 2023
|
||||
```
|
||||
|
||||
Or use `time.Format` with a *parsable* string representation of a date/time value:
|
||||
|
||||
```go-html-template
|
||||
{{ $t := "27 Feb 2023" }}
|
||||
{{ time.Format "January 2, 2006" $t }} → February 27, 2023
|
||||
```
|
||||
|
||||
Examples of parsable string representations:
|
||||
|
||||
{{% include "functions/time/_common/parsable-date-time-strings.md" %}}
|
||||
|
||||
## Layout string
|
||||
|
||||
{{% readfile file="/functions/_common/time-layout-string.md" %}}
|
||||
{{% include "functions/_common/time-layout-string.md" %}}
|
||||
|
||||
## Localization
|
||||
|
||||
Use the `time.Format` function to localize `time.Time` values for the current language and region.
|
||||
|
||||
{{% note %}}
|
||||
{{% readfile file="/functions/_common/locales.md" %}}
|
||||
{{% /note %}}
|
||||
|
||||
{{% include "functions/_common/locales.md" %}}
|
||||
|
||||
Use the layout string as described above, or one of the tokens below. For example:
|
||||
|
||||
```go-template
|
||||
```go-html-template
|
||||
{{ .Date | time.Format ":date_medium" }} → Jan 27, 2023
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,51 +1,48 @@
|
|||
---
|
||||
title: time.Now
|
||||
linkTitle: now
|
||||
description: Returns the current local time
|
||||
categories: [functions]
|
||||
description: Returns the current local time.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
function:
|
||||
action:
|
||||
aliases: [now]
|
||||
related:
|
||||
- functions/time/AsTime
|
||||
- functions/time/Duration
|
||||
- functions/time/Format
|
||||
- functions/time/ParseDuration
|
||||
returnType: time.Time
|
||||
signatures: [time.Now]
|
||||
relatedFunctions:
|
||||
- time.AsTime
|
||||
- time.Duration
|
||||
- time.Format
|
||||
- time.Now
|
||||
- time.ParseDuration
|
||||
aliases: [/functions/now]
|
||||
---
|
||||
|
||||
See [`time.Time`](https://godoc.org/time#Time).
|
||||
|
||||
For example, building your site on June 24, 2017, with the following templating:
|
||||
For example, when building a site on October 15, 2023 in the America/Los_Angeles time zone:
|
||||
|
||||
```go-html-template
|
||||
<div>
|
||||
<small>© {{ now.Format "2006" }}</small>
|
||||
</div>
|
||||
{{ time.Now }}
|
||||
```
|
||||
|
||||
would produce the following:
|
||||
This produces a `time.Time` value, with a string representation such as:
|
||||
|
||||
```html
|
||||
<div>
|
||||
<small>© 2017</small>
|
||||
</div>
|
||||
```text
|
||||
2023-10-15 12:59:28.337140706 -0700 PDT m=+0.041752605
|
||||
```
|
||||
|
||||
The above example uses the [`.Format` function](/functions/format), which page includes a full listing of date formatting using Go's layout string.
|
||||
To format and [localize] the value, pass it through the [`time.Format`] function:
|
||||
|
||||
{{% note %}}
|
||||
Older Hugo themes may still be using the obsolete Page’s `.Now` (uppercase with leading dot), which causes build error that looks like the following:
|
||||
```go-html-template
|
||||
{{ time.Now | time.Format "Jan 2006" }} → Oct 2023
|
||||
```
|
||||
|
||||
ERROR ... Error while rendering "..." in "...": ...
|
||||
executing "..." at <.Now.Format>:
|
||||
can't evaluate field Now in type *hugolib.PageOutput
|
||||
The `time.Now` function returns a `time.Time` value, so you can chain any of the [time methods] to the resulting value. For example:
|
||||
|
||||
Be sure to use `now` (lowercase with _**no**_ leading dot) in your templating.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ time.Now.Year }} → 2023 (int)
|
||||
{{ time.Now.Weekday.String }} → Sunday
|
||||
{{ time.Now.Month.String }} → October
|
||||
{{ time.Now.Unix }} → 1697400955 (int64)
|
||||
```
|
||||
|
||||
[`time.Format`]: /functions/time/format
|
||||
[localize]: /getting-started/glossary/#localization
|
||||
[time methods]: /methods/time/
|
||||
|
|
|
|||
|
|
@ -1,30 +1,37 @@
|
|||
---
|
||||
title: time.ParseDuration
|
||||
description: Parses a given duration string into a `time.Duration` structure.
|
||||
categories: [functions]
|
||||
description: Returns a time.Duration value by parsing the given duration string.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
function:
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/time/AsTime
|
||||
- functions/time/Duration
|
||||
- functions/time/Format
|
||||
- functions/time/Now
|
||||
returnType: time.Duration
|
||||
signatures: [time.ParseDuration DURATION]
|
||||
relatedFunctions:
|
||||
- time.AsTime
|
||||
- time.Duration
|
||||
- time.Format
|
||||
- time.Now
|
||||
- time.ParseDuration
|
||||
aliases: [/functions/time.parseduration]
|
||||
---
|
||||
|
||||
`time.ParseDuration` parses a duration string into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields.
|
||||
The `time.ParseDuration` function returns a time.Duration value that you can use with any of the `Duration` [methods].
|
||||
|
||||
|
||||
A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
|
||||
|
||||
You can perform [time operations](https://pkg.go.dev/time#Duration) on the returned `time.Duration` value:
|
||||
This template:
|
||||
|
||||
```go-html-template
|
||||
{{ printf "There are %.0f seconds in one day." (time.ParseDuration "24h").Seconds }}
|
||||
<!-- Output: There are 86400 seconds in one day. -->
|
||||
{{ $duration := time.ParseDuration "24h" }}
|
||||
{{ printf "There are %.0f seconds in one day." $duration.Seconds }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```text
|
||||
There are 86400 seconds in one day.
|
||||
```
|
||||
|
||||
[`time.Duration`]: https://pkg.go.dev/time#Duration
|
||||
[methods]: /methods/duration
|
||||
|
|
|
|||
13
docs/content/en/functions/time/_common/_index.md
Normal file
13
docs/content/en/functions/time/_common/_index.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
cascade:
|
||||
_build:
|
||||
list: never
|
||||
publishResources: false
|
||||
render: never
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
String representation|Time zone
|
||||
:--|:--
|
||||
2023-10-15T14:20:28-07:00|America/Los_Angeles
|
||||
2023-10-15T13:18:50-0700|America/Los_Angeles
|
||||
2023-10-15T13:18:50Z|Etc/UTC
|
||||
2023-10-15T13:18:50|Etc/UTC
|
||||
2023-10-15|Etc/UTC
|
||||
15 Oct 2023|Etc/UTC
|
||||
|
||||
The last four examples are not fully qualified. Without a time zone offset, the time zone is set to Etc/UTC (Coordinated Universal Time).
|
||||
12
docs/content/en/functions/time/_index.md
Normal file
12
docs/content/en/functions/time/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Time functions
|
||||
linkTitle: time
|
||||
description: Template functions to work with time values.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
Use these functions to work with time values.
|
||||
Loading…
Add table
Add a link
Reference in a new issue