Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

docs/content/en/methods/time/Add.md

@@ -0,0 +1,23 @@
+---
+title: Add
+description: Returns the given time plus the given duration.
+categories: []
+keywords: []
+action:
+  related:
+    - functions/time/AsTime
+    - functions/time/Duration
+    - functions/time/ParseDuration
+  returnType: time.Time
+  signatures: [TIME.Add DURATION]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+
+{{ $d1 = time.ParseDuration "3h20m10s" }}
+{{ $d2 = time.ParseDuration "-3h20m10s" }}
+
+{{ $t.Add $d1 }} → 2023-01-28 03:05:08 -0800 PST
+{{ $t.Add $d2 }} → 2023-01-27 20:24:48 -0800 PST
+```

docs/content/en/methods/time/AddDate.md

@@ -0,0 +1,39 @@
+---
+title: AddDate
+description: Returns the time corresponding to adding the given number of years, months, and days to the given time.Time value.
+categories: []
+keywords: []
+action:
+  aliases: []
+  related: []
+  returnType: time.Time
+  signatures: [TIME.AddDate YEARS MONTHS DAYS]
+aliases: [/functions/adddate]
+---
+
+```go-html-template
+{{ $d := "2022-01-01" | time.AsTime }}
+
+{{ $d.AddDate 0 0 1 | time.Format "2006-01-02" }} → 2022-01-02
+{{ $d.AddDate 0 1 1 | time.Format "2006-01-02" }} → 2022-02-02
+{{ $d.AddDate 1 1 1 | time.Format "2006-01-02" }} → 2023-02-02
+
+{{ $d.AddDate -1 -1 -1 | time.Format "2006-01-02" }} → 2020-11-30
+```
+
+{{% note %}}
+When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year.
+
+See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team.
+{{% /note %}}
+
+```go-html-template
+{{ $d := "2023-01-31" | time.AsTime }}
+{{ $d.AddDate 0 1 0 | time.Format "2006-01-02" }} → 2023-03-03
+
+{{ $d := "2024-01-31" | time.AsTime }}
+{{ $d.AddDate 0 1 0 | time.Format "2006-01-02" }} → 2024-03-02
+
+{{ $d := "2024-02-29" | time.AsTime }}
+{{ $d.AddDate 1 0 0 | time.Format "2006-01-02" }} → 2025-03-01
+```

docs/content/en/methods/time/After.md

@@ -0,0 +1,20 @@
+---
+title: After
+description: Reports whether TIME1 is after TIME2.
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Before
+    - methods/time/After
+    - functions/time/AsTime
+  returnType: bool
+  signatures: [TIME1.After TIME2]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }}
+{{ $t2 := time.AsTime "2010-01-01T17:00:00-08:00" }}
+
+{{ $t1.After $t2 }} → true
+```

docs/content/en/methods/time/Before.md

@@ -0,0 +1,19 @@
+---
+title: Before
+description: Reports whether TIME1 is before TIME2.
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/After
+    - methods/time/Equal
+    - functions/time/AsTime
+  returnType: bool
+  signatures: [TIME1.Before TIME2]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }}
+{{ $t2 := time.AsTime "2030-01-01T17:00:00-08:00" }}
+
+{{ $t1.Before $t2 }} → true

docs/content/en/methods/time/Day.md

@@ -0,0 +1,21 @@
+---
+title: Day
+description: Returns the day of the month of the given time.Time value.
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Year
+    - methods/time/Month
+    - methods/time/Hour
+    - methods/time/Minute
+    - methods/time/Second
+    - functions/time/AsTime
+  returnType: int
+  signatures: [TIME.Day]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Day }} → 27
+```

docs/content/en/methods/time/Equal.md

@@ -0,0 +1,20 @@
+---
+title: Equal
+description: Reports whether TIME1 is equal to TIME2.
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/After
+    - methods/time/Before
+    - functions/time/AsTime
+  returnType: bool
+  signatures: [TIME1.Equal TIME2]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }}
+{{ $t2 := time.AsTime "2023-01-01T20:00:00-05:00" }}
+
+{{ $t1.Equal $t2 }} → true
+```

docs/content/en/methods/time/Format.md

@@ -0,0 +1,98 @@
+---
+title: Format
+description: Returns a textual representation of the time.Time value formatted according to the layout string.
+categories: []
+keywords: []
+action:
+  aliases: []
+  related:
+    - functions/time/AsTime
+    - methods/time/UTC
+    - methods/time/Local
+  returnType: string
+  signatures: [TIME.Format LAYOUT]
+toc: true
+aliases: [/methods/time/format]
+---
+
+```go-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+{{ $format := "2 Jan 2006" }}
+
+{{ $t.Format $format }} → 27 Jan 2023
+```
+
+{{% note %}}
+To [localize] the return value, use the [`time.Format`] function instead.
+
+[localize]: /getting-started/glossary/#localization
+[`time.Format`]: /functions/time/format
+{{% /note %}}
+
+Use the `Format` method with any `time.Time` value, including the four predefined front matter dates:
+
+```go-html-template
+{{ $format := "2 Jan 2006" }}
+
+{{ .Date.Format $format }}
+{{ .PublishDate.Format $format }}
+{{ .ExpiryDate.Format $format }}
+{{ .Lastmod.Format $format }}
+```
+
+{{% note %}}
+Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset.
+
+[`time.Format`]: /functions/time/format
+{{% /note %}}
+
+## Layout string
+
+{{% include "functions/_common/time-layout-string.md" %}}
+
+## Examples
+
+Given this front matter:
+
+{{< code-toggle fm=true >}}
+title = "About time"
+date = 2023-01-27T23:44:58-08:00
+{{< /code-toggle >}}
+
+The examples below were rendered in the `America/Los_Angeles` time zone:
+
+Format string|Result
+:--|:--
+`Monday, January 2, 2006`|`Friday, January 27, 2023`
+`Mon Jan 2 2006`|`Fri Jan 27 2023`
+`January 2006`|`January 2023`
+`2006-01-02`|`2023-01-27`
+`Monday`|`Friday`
+`02 Jan 06 15:04 MST`|`27 Jan 23 23:44 PST`
+`Mon, 02 Jan 2006 15:04:05 MST`|`Fri, 27 Jan 2023 23:44:58 PST`
+`Mon, 02 Jan 2006 15:04:05 -0700`|`Fri, 27 Jan 2023 23:44:58 -0800`
+
+## UTC and local time
+
+Convert and format any `time.Time` value to either Coordinated Universal Time (UTC) or local time.
+
+```go-html-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+{{ $format := "2 Jan 2006 3:04:05 PM MST" }}
+
+{{ $t.UTC.Format $format }} → 28 Jan 2023 7:44:58 AM UTC
+{{ $t.Local.Format $format }} → 27 Jan 2023 11:44:58 PM PST
+```
+
+## Ordinal representation
+
+Use the [`humanize`](/functions/inflect/humanize) function to render the day of the month as an ordinal number:
+
+```go-html-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+
+{{ humanize $t.Day }} of {{ $t.Format "January 2006" }} → 27th of January 2023
+```

docs/content/en/methods/time/Hour.md

@@ -0,0 +1,21 @@
+---
+title: Hour
+description: Returns the hour within the day of the given time.Time value, in the range [0, 23].
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Year
+    - methods/time/Month
+    - methods/time/Day
+    - methods/time/Minute
+    - methods/time/Second
+    - functions/time/AsTime
+  returnType: int
+  signatures: [TIME.Hour]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Hour }} → 23
+```

docs/content/en/methods/time/IsDST.md

@@ -0,0 +1,19 @@
+---
+title: IsDST
+description: Reports whether the given time.Time value is in Daylight Savings Time.
+categories: []
+keywords: []
+action:
+  related:
+    - functions/time/AsTime
+  returnType: bool
+  signatures: [TIME.IsDST]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-01T00:00:00-08:00" }}
+{{ $t2 := time.AsTime "2023-07-01T00:00:00-07:00" }}
+
+{{ $t1.IsDST }} → false
+{{ $t2.IsDST }} → true
+```

docs/content/en/methods/time/IsZero.md

@@ -0,0 +1,19 @@
+---
+title: IsZero
+description: Reports whether the given time.Time value represents the zero time instant, January 1, year 1, 00:00:00 UTC.
+categories: []
+keywords: []
+action:
+  related:
+    - functions/time/AsTime
+  returnType: bool
+  signatures: [TIME.IsZero]
+---
+
+````go-html-template
+{{ $t1 := time.AsTime "2023-01-01T00:00:00-08:00" }}
+{{ $t2 := time.AsTime "0001-01-01T00:00:00-00:00" }}
+
+{{ $t1.IsZero }} → false
+{{ $t2.IsZero }} → true
+```

docs/content/en/methods/time/Local.md

@@ -0,0 +1,17 @@
+---
+title: Local
+description: Returns the given time.Time value with the location set to local time.
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/UTC
+    - functions/time/AsTime
+  returnType: time.Time
+  signatures: [TIME.Local]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-28T07:44:58+00:00" }}
+{{ $t.Local }} → 2023-01-27 23:44:58 -0800 PST
+```

docs/content/en/methods/time/Minute.md

@@ -0,0 +1,21 @@
+---
+title: Minute
+description: Returns the minute offset within the hour of the given time.Time value, in the range [0, 59].
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Year
+    - methods/time/Month
+    - methods/time/Day
+    - methods/time/Hour
+    - methods/time/Second
+    - functions/time/AsTime
+  returnType: int
+  signatures: [TIME.Minute]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Minute }} → 44
+```

docs/content/en/methods/time/Month.md

@@ -0,0 +1,30 @@
+---
+title: Month
+description: Returns the month of the year of the given time.Time value.
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Year
+    - methods/time/Day
+    - methods/time/Hour
+    - methods/time/Minute
+    - methods/time/Second
+    - functions/time/AsTime
+  returnType: time.Month
+  signatures: [TIME.Month]
+---
+
+To convert the `time.Month` value to a string:
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Month.String }} → January
+```
+
+To convert the `time.Month` value to an integer.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Month | int }} → 1
+```

docs/content/en/methods/time/Nanosecond.md

@@ -0,0 +1,16 @@
+---
+title: Nanosecond
+description: Returns the nanosecond offset within the second of the given time.Time value, in the range [0, 999999999].
+categories: []
+keywords: []
+action:
+  related:
+    - functions/time/AsTime
+  returnType: int
+  signatures: [TIME.Nanosecond]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Nanosecond }} → 0
+```

docs/content/en/methods/time/Second.md

@@ -0,0 +1,21 @@
+---
+title: Second
+description: Returns the second offset within the minute of the given time.Time value, in the range [0, 59].
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Year
+    - methods/time/Month
+    - methods/time/Day
+    - methods/time/Hour
+    - methods/time/Minute
+    - functions/time/AsTime
+  returnType: int
+  signatures: [TIME.Second]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Second }} → 58
+```

docs/content/en/methods/time/Sub.md

@@ -0,0 +1,18 @@
+---
+title: Sub
+description: Returns the duration computed by subtracting TIME2 from TIME1.
+categories: []
+keywords: []
+action:
+  related:
+    - functions/time/AsTime
+  returnType: time.Duration
+  signatures: [TIME1.Sub TIME2]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t2 := time.AsTime "2023-01-26T22:34:38-08:00" }}
+
+{{ $t1.Sub $t2 }} → 25h10m20s
+```

docs/content/en/methods/time/UTC.md

@@ -0,0 +1,16 @@
+---
+title: UTC
+description: Returns the given time.Time value with the location set to UTC.
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Local
+    - functions/time/AsTime
+  returnType: time.Time
+  signatures: [TIME.UTC]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.UTC }} → 2023-01-28 07:44:58 +0000 UTC

docs/content/en/methods/time/Unix.md

@@ -0,0 +1,21 @@
+---
+title: Unix
+description: Returns the given time.Time value expressed as the number of seconds elapsed since January 1, 1970 UTC. 
+categories: []
+action:
+  related:
+    - methods/time/UnixMilli
+    - methods/time/UnixMicro
+    - methods/time/UnixNano
+    - functions/time/AsTime
+  returnType: int64
+  signatures: [TIME.Unix]
+aliases: [/functions/unix]
+---
+
+See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Unix }} → 1674891898
+```

docs/content/en/methods/time/UnixMicro.md

@@ -0,0 +1,21 @@
+---
+title: UnixMicro
+description: Returns the given time.Time value expressed as the number of microseconds elapsed since January 1, 1970 UTC. 
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Unix
+    - methods/time/UnixMilli
+    - methods/time/UnixNano
+    - functions/time/AsTime
+  returnType: int64
+  signatures: [TIME.UnixMicro]
+---
+
+See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.UnixMicro }} → 1674891898000000
+```

docs/content/en/methods/time/UnixMilli.md

@@ -0,0 +1,21 @@
+---
+title: UnixMilli
+description: Returns the given time.Time value expressed as the number of milliseconds elapsed since January 1, 1970 UTC. 
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Unix
+    - methods/time/UnixMicro
+    - methods/time/UnixNano
+    - functions/time/AsTime
+  returnType: int64
+  signatures: [TIME.UnixMilli]
+---
+
+See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.UnixMilli }} → 1674891898000
+```

docs/content/en/methods/time/UnixNano.md

@@ -0,0 +1,21 @@
+---
+title: UnixNano
+description: Returns the given time.Time value expressed as the number of nanoseconds elapsed since January 1, 1970 UTC. 
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Unix
+    - methods/time/UnixMilli
+    - methods/time/UnixMicro
+    - functions/time/AsTime
+  returnType: int64
+  signatures: [TIME.UnixNano]
+---
+
+See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.UnixNano }} → 1674891898000000000
+```

docs/content/en/methods/time/Weekday.md

@@ -0,0 +1,24 @@
+---
+title: Weekday
+description:  Returns the day of the week of the given time.Time value.
+categories: []
+keywords: []
+action:
+  related:
+    - functions/time/AsTime
+  returnType: time.Weekday
+  signatures: [TIME.Weekday]
+---
+
+To convert the `time.Weekday` value to a string:
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Weekday.String }} → Friday
+```
+
+To convert the `time.Weekday` value to an integer.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Weekday | int }} → 5

docs/content/en/methods/time/Year.md

@@ -0,0 +1,21 @@
+---
+title: Year
+description: Returns the year of the given time.Time value.
+categories: []
+keywords: []
+action:
+  related:
+    - methods/time/Month
+    - methods/time/Day
+    - methods/time/Hour
+    - methods/time/Minute
+    - methods/time/Second
+    - functions/time/AsTime
+  returnType: int
+  signatures: [TIME.Year]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Year }} → 2023
+```

docs/content/en/methods/time/YearDay.md

@@ -0,0 +1,15 @@
+---
+title: YearDay
+description: Returns the day of the year of the given time.Time value, in the range [1, 365] for non-leap years, and [1,366] in leap years.
+categories: []
+keywords: []
+action:
+  related: []
+  returnType: int
+  signatures: [TIME.YearDay]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.YearDay }} → 27
+```

docs/content/en/methods/time/_index.md

@@ -0,0 +1,13 @@
+---
+title: Time methods
+linkTitle: Time
+description: Use these methods with time.Time values.
+categories: []
+keywords: []
+menu:
+  docs:
+    identifier: time-methods
+    parent: methods
+---
+
+Use these methods with time.Time values.