github.com/hairyhenderson/gomplate/v4@v4.0.0-pre-2.0.20240520121557-362f058f0c93/docs-src/content/functions/time.yml (about) 1 ns: time 2 preamble: | 3 This namespace wraps Go's [`time` package](https://golang.org/pkg/time/), and a 4 few of the functions return a `time.Time` value. All of the 5 [`time.Time` functions](https://golang.org/pkg/time/#Time) can then be used to 6 convert, adjust, or format the time in your template. 7 8 ### Reference time 9 10 An important difference between this and many other time/date utilities is how 11 parsing and formatting is accomplished. Instead of relying solely on pre-defined 12 formats, or having a complex system of variables, formatting is accomplished by 13 declaring an example of the layout you wish to display. 14 15 This uses a _reference time_, which is: 16 17 ``` 18 Mon Jan 2 15:04:05 -0700 MST 2006 19 ``` 20 21 ### Constants 22 23 #### format layouts 24 25 Some pre-defined layouts have been provided for convenience: 26 27 | layout name | value | 28 |-------------|-------| 29 | `time.ANSIC` | `"Mon Jan _2 15:04:05 2006"` | 30 | `time.UnixDate` | `"Mon Jan _2 15:04:05 MST 2006"` | 31 | `time.RubyDate` | `"Mon Jan 02 15:04:05 -0700 2006"` | 32 | `time.RFC822` | `"02 Jan 06 15:04 MST"` | 33 | `time.RFC822Z` | `"02 Jan 06 15:04 -0700"` // RFC822 with numeric zone | 34 | `time.RFC850` | `"Monday, 02-Jan-06 15:04:05 MST"` | 35 | `time.RFC1123` | `"Mon, 02 Jan 2006 15:04:05 MST"` | 36 | `time.RFC1123Z` | `"Mon, 02 Jan 2006 15:04:05 -0700"` // RFC1123 with numeric zone | 37 | `time.RFC3339` | `"2006-01-02T15:04:05Z07:00"` | 38 | `time.RFC3339Nano` | `"2006-01-02T15:04:05.999999999Z07:00"` | 39 | `time.Kitchen` | `"3:04PM"` | 40 | `time.Stamp` | `"Jan _2 15:04:05"` | 41 | `time.StampMilli` | `"Jan _2 15:04:05.000" `| 42 | `time.StampMicro` | `"Jan _2 15:04:05.000000"` | 43 | `time.StampNano` | `"Jan _2 15:04:05.000000000"` | 44 45 See below for examples of how these layouts can be used. 46 47 #### durations 48 49 Some operations (such as [`Time.Add`](https://golang.org/pkg/time/#Time.Add) and 50 [`Time.Round`](https://golang.org/pkg/time/#Time.Round)) require a 51 [`Duration`](https://golang.org/pkg/time/#Duration) value. These can be created 52 conveniently with the following functions: 53 54 - `time.Nanosecond` 55 - `time.Microsecond` 56 - `time.Millisecond` 57 - `time.Second` 58 - `time.Minute` 59 - `time.Hour` 60 61 For example: 62 63 ```console 64 $ gomplate -i '{{ (time.Now).Format time.Kitchen }} 65 {{ ((time.Now).Add (time.Hour 2)).Format time.Kitchen }}' 66 9:05AM 67 11:05AM 68 ``` 69 70 For other durations, such as `2h10m`, [`time.ParseDuration`](#time-parseduration) can be used. 71 funcs: 72 - name: time.Now 73 released: v2.1.0 74 description: | 75 Returns the current local time, as a `time.Time`. This wraps [`time.Now`](https://golang.org/pkg/time/#Now). 76 77 Usually, further functions are called using the value returned by `Now`. 78 pipeline: false 79 rawExamples: 80 - | 81 Usage with [`UTC`](https://golang.org/pkg/time/#Time.UTC) and [`Format`](https://golang.org/pkg/time/#Time.Format): 82 ```console 83 $ gomplate -i '{{ (time.Now).UTC.Format "Day 2 of month 1 in year 2006 (timezone MST)" }}' 84 Day 14 of month 10 in year 2017 (timezone UTC) 85 ``` 86 - | 87 Usage with [`AddDate`](https://golang.org/pkg/time/#Time.AddDate): 88 ```console 89 $ date 90 Sat Oct 14 09:57:02 EDT 2017 91 $ gomplate -i '{{ ((time.Now).AddDate 0 1 0).Format "Mon Jan 2 15:04:05 MST 2006" }}' 92 Tue Nov 14 09:57:02 EST 2017 93 ``` 94 95 _(notice how the TZ adjusted for daylight savings!)_ 96 - | 97 Usage with [`IsDST`](https://golang.org/pkg/time/#Time.IsDST): 98 ```console 99 $ gomplate -i '{{ $t := time.Now }}At the tone, the time will be {{ ($t.Round (time.Minute 1)).Add (time.Minute 1) }}. 100 It is{{ if not $t.IsDST }} not{{ end }} daylight savings time. 101 ... ... BEEP' 102 At the tone, the time will be 2022-02-10 09:01:00 -0500 EST. 103 It is not daylight savings time. 104 ... ... BEEP 105 ``` 106 - name: time.Parse 107 released: v2.1.0 108 description: | 109 Parses a timestamp defined by the given layout. This wraps [`time.Parse`](https://golang.org/pkg/time/#Parse). 110 111 A number of pre-defined layouts are provided as constants, defined 112 [here](https://golang.org/pkg/time/#pkg-constants). 113 114 Just like [`time.Now`](#time-now), this is usually used in conjunction with 115 other functions. 116 117 _Note: In the absence of a time zone indicator, `time.Parse` returns a time in UTC._ 118 pipeline: true 119 arguments: 120 - name: layout 121 required: true 122 description: The layout string to parse with 123 - name: timestamp 124 required: true 125 description: The timestamp to parse 126 rawExamples: 127 - | 128 Usage with [`Format`](https://golang.org/pkg/time/#Time.Format): 129 ```console 130 $ gomplate -i '{{ (time.Parse "2006-01-02" "1993-10-23").Format "Monday January 2, 2006 MST" }}' 131 Saturday October 23, 1993 UTC 132 ``` 133 - name: time.ParseDuration 134 released: v2.1.0 135 description: | 136 Parses a duration string. This wraps [`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration). 137 138 A duration string is a possibly signed sequence of decimal numbers, each with 139 optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid 140 time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. 141 pipeline: true 142 arguments: 143 - name: duration 144 required: true 145 description: The duration string to parse 146 examples: 147 - | 148 $ gomplate -i '{{ (time.Now).Format time.Kitchen }} 149 {{ ((time.Now).Add (time.ParseDuration "2h30m")).Format time.Kitchen }}' 150 12:43AM 151 3:13AM 152 - name: time.ParseLocal 153 released: v2.2.0 154 description: | 155 Same as [`time.Parse`](#time-parse), except that in the absence of a time zone 156 indicator, the timestamp wil be parsed in the local timezone. 157 pipeline: true 158 arguments: 159 - name: layout 160 required: true 161 description: The layout string to parse with 162 - name: timestamp 163 required: true 164 description: The timestamp to parse 165 rawExamples: 166 - | 167 Usage with [`Format`](https://golang.org/pkg/time/#Time.Format): 168 ```console 169 $ bin/gomplate -i '{{ (time.ParseLocal time.Kitchen "6:00AM").Format "15:04 MST" }}' 170 06:00 EST 171 ``` 172 - name: time.ParseInLocation 173 released: v2.2.0 174 description: | 175 Same as [`time.Parse`](#time-parse), except that the time is parsed in the given location's time zone. 176 177 This wraps [`time.ParseInLocation`](https://golang.org/pkg/time/#ParseInLocation). 178 pipeline: true 179 arguments: 180 - name: layout 181 required: true 182 description: The layout string to parse with 183 - name: location 184 required: true 185 description: The location to parse in 186 - name: timestamp 187 required: true 188 description: The timestamp to parse 189 rawExamples: 190 - | 191 Usage with [`Format`](https://golang.org/pkg/time/#Time.Format): 192 ```console 193 $ gomplate -i '{{ (time.ParseInLocation time.Kitchen "Africa/Luanda" "6:00AM").Format "15:04 MST" }}' 194 06:00 LMT 195 ``` 196 - name: time.Since 197 released: v2.5.0 198 description: | 199 Returns the time elapsed since a given time. This wraps [`time.Since`](https://golang.org/pkg/time/#Since). 200 201 It is shorthand for `time.Now.Sub t`. 202 pipeline: true 203 arguments: 204 - name: t 205 required: true 206 description: the `Time` to calculate since 207 examples: 208 - | 209 $ gomplate -i '{{ $t := time.Parse time.RFC3339 "1970-01-01T00:00:00Z" }}time since the epoch:{{ time.Since $t }}' 210 time since the epoch:423365h0m24.353828924s 211 - name: time.Unix 212 released: v2.1.0 213 description: | 214 Returns the local `Time` corresponding to the given Unix time, in seconds since 215 January 1, 1970 UTC. Note that fractional seconds can be used to denote 216 milliseconds, but must be specified as a string, not a floating point number. 217 pipeline: true 218 arguments: 219 - name: time 220 required: true 221 description: the time to parse 222 rawExamples: 223 - | 224 _with whole seconds:_ 225 ```console 226 $ gomplate -i '{{ (time.Unix 42).UTC.Format time.Stamp}}' 227 Jan 1, 00:00:42 228 ``` 229 230 _with fractional seconds:_ 231 ```console 232 $ gomplate -i '{{ (time.Unix "123456.789").UTC.Format time.StampMilli}}' 233 Jan 2 10:17:36.789 234 ``` 235 - name: time.Until 236 released: v2.5.0 237 description: | 238 Returns the duration until a given time. This wraps [`time.Until`](https://golang.org/pkg/time/#Until). 239 240 It is shorthand for `$t.Sub time.Now`. 241 pipeline: true 242 arguments: 243 - name: t 244 required: true 245 description: the `Time` to calculate until 246 rawExamples: 247 - | 248 ```console 249 $ gomplate -i '{{ $t := time.Parse time.RFC3339 "2020-01-01T00:00:00Z" }}only {{ time.Until $t }} to go...' 250 only 14922h56m46.578625891s to go... 251 ``` 252 253 Or, less precise: 254 ```console 255 $ bin/gomplate -i '{{ $t := time.Parse time.RFC3339 "2020-01-01T00:00:00Z" }}only {{ (time.Until $t).Round (time.Hour 1) }} to go...' 256 only 14923h0m0s to go... 257 ``` 258 - name: time.ZoneName 259 released: v2.1.0 260 description: | 261 Return the local system's time zone's name. 262 pipeline: false 263 examples: 264 - | 265 $ gomplate -i '{{time.ZoneName}}' 266 EDT 267 - name: time.ZoneOffset 268 released: v2.2.0 269 description: | 270 Return the local system's time zone offset, in seconds east of UTC. 271 pipeline: false 272 examples: 273 - | 274 $ gomplate -i '{{time.ZoneOffset}}' 275 -14400