diff options
Diffstat (limited to 'content/en/methods/time')
25 files changed, 595 insertions, 0 deletions
diff --git a/content/en/methods/time/Add.md b/content/en/methods/time/Add.md new file mode 100644 index 000000000..8fd755244 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/AddDate.md b/content/en/methods/time/AddDate.md new file mode 100644 index 000000000..8537d6e25 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/After.md b/content/en/methods/time/After.md new file mode 100644 index 000000000..0aeeb38d8 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Before.md b/content/en/methods/time/Before.md new file mode 100644 index 000000000..c3d582860 --- /dev/null +++ b/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 diff --git a/content/en/methods/time/Day.md b/content/en/methods/time/Day.md new file mode 100644 index 000000000..1173b8489 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Equal.md b/content/en/methods/time/Equal.md new file mode 100644 index 000000000..4d45a3ada --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Format.md b/content/en/methods/time/Format.md new file mode 100644 index 000000000..fc3e2635c --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Hour.md b/content/en/methods/time/Hour.md new file mode 100644 index 000000000..58ed00260 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/IsDST.md b/content/en/methods/time/IsDST.md new file mode 100644 index 000000000..df2b84cae --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/IsZero.md b/content/en/methods/time/IsZero.md new file mode 100644 index 000000000..2026f3b2e --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Local.md b/content/en/methods/time/Local.md new file mode 100644 index 000000000..bd40e3a44 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Minute.md b/content/en/methods/time/Minute.md new file mode 100644 index 000000000..d482fab5d --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Month.md b/content/en/methods/time/Month.md new file mode 100644 index 000000000..0a01d1a70 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Nanosecond.md b/content/en/methods/time/Nanosecond.md new file mode 100644 index 000000000..606143139 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Second.md b/content/en/methods/time/Second.md new file mode 100644 index 000000000..e326c64bc --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Sub.md b/content/en/methods/time/Sub.md new file mode 100644 index 000000000..9678365eb --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/UTC.md b/content/en/methods/time/UTC.md new file mode 100644 index 000000000..6fd7b526d --- /dev/null +++ b/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 diff --git a/content/en/methods/time/Unix.md b/content/en/methods/time/Unix.md new file mode 100644 index 000000000..fcfc661fe --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/UnixMicro.md b/content/en/methods/time/UnixMicro.md new file mode 100644 index 000000000..150497cd3 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/UnixMilli.md b/content/en/methods/time/UnixMilli.md new file mode 100644 index 000000000..e5e90ba25 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/UnixNano.md b/content/en/methods/time/UnixNano.md new file mode 100644 index 000000000..63db320a3 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/Weekday.md b/content/en/methods/time/Weekday.md new file mode 100644 index 000000000..b2a95fe9c --- /dev/null +++ b/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 diff --git a/content/en/methods/time/Year.md b/content/en/methods/time/Year.md new file mode 100644 index 000000000..b046896f4 --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/YearDay.md b/content/en/methods/time/YearDay.md new file mode 100644 index 000000000..40d7d6aab --- /dev/null +++ b/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 +``` diff --git a/content/en/methods/time/_index.md b/content/en/methods/time/_index.md new file mode 100644 index 000000000..81d4690e0 --- /dev/null +++ b/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. |