diff options
Diffstat (limited to 'docs/content/en/functions/time/AsTime.md')
| -rw-r--r-- | docs/content/en/functions/time/AsTime.md | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/docs/content/en/functions/time/AsTime.md b/docs/content/en/functions/time/AsTime.md new file mode 100644 index 000000000..1244eeb5c --- /dev/null +++ b/docs/content/en/functions/time/AsTime.md @@ -0,0 +1,64 @@ +--- +title: time.AsTime +linkTitle: time +description: Converts a timestamp string into a `time.Time` structure. +categories: [functions] +keywords: [] +menu: + docs: + parent: functions +function: + aliases: [time] + returnType: time.Time + signatures: ['time.AsTime INPUT [TIMEZONE]'] +relatedFunctions: + - time.AsTime + - time.Duration + - time.Format + - time.Now + - time.ParseDuration +aliases: [/functions/time] +--- + + +`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: + +```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 +``` + +## Using locations + +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. + +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). + +If no `TIMEZONE` is set, the `timeZone` from site configuration will be used. + +```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 +``` + +## Example: Using `time` to get month index + +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. + +The following example may be useful when setting up [multilingual sites][multilingual]: + +{{< 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 >}} + + +[int]: /functions/cast/toint +[multilingual]: /content-management/multilingual/ +[`printf`]: /functions/fmt/printf |