github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs/content/functions/time.md (about) 1 --- 2 title: time functions 3 menu: 4 main: 5 parent: functions 6 --- 7 8 This namespace wraps Go's [`time` package](https://golang.org/pkg/time/), and a 9 few of the functions return a `time.Time` value. All of the 10 [`time.Time` functions](https://golang.org/pkg/time/#Time) can then be used to 11 convert, adjust, or format the time in your template. 12 13 ### Reference time 14 15 An important difference between this and many other time/date utilities is how 16 parsing and formatting is accomplished. Instead of relying solely on pre-defined 17 formats, or having a complex system of variables, formatting is accomplished by 18 declaring an example of the layout you wish to display. 19 20 This uses a _reference time_, which is: 21 22 ``` 23 Mon Jan 2 15:04:05 -0700 MST 2006 24 ``` 25 26 ### Constants 27 28 #### format layouts 29 30 Some pre-defined layouts have been provided for convenience: 31 32 | layout name | value | 33 |-------------|-------| 34 | `time.ANSIC` | `"Mon Jan _2 15:04:05 2006"` | 35 | `time.UnixDate` | `"Mon Jan _2 15:04:05 MST 2006"` | 36 | `time.RubyDate` | `"Mon Jan 02 15:04:05 -0700 2006"` | 37 | `time.RFC822` | `"02 Jan 06 15:04 MST"` | 38 | `time.RFC822Z` | `"02 Jan 06 15:04 -0700"` // RFC822 with numeric zone | 39 | `time.RFC850` | `"Monday, 02-Jan-06 15:04:05 MST"` | 40 | `time.RFC1123` | `"Mon, 02 Jan 2006 15:04:05 MST"` | 41 | `time.RFC1123Z` | `"Mon, 02 Jan 2006 15:04:05 -0700"` // RFC1123 with numeric zone | 42 | `time.RFC3339` | `"2006-01-02T15:04:05Z07:00"` | 43 | `time.RFC3339Nano` | `"2006-01-02T15:04:05.999999999Z07:00"` | 44 | `time.Kitchen` | `"3:04PM"` | 45 | `time.Stamp` | `"Jan _2 15:04:05"` | 46 | `time.StampMilli` | `"Jan _2 15:04:05.000" `| 47 | `time.StampMicro` | `"Jan _2 15:04:05.000000"` | 48 | `time.StampNano` | `"Jan _2 15:04:05.000000000"` | 49 50 See below for examples of how these layouts can be used. 51 52 #### durations 53 54 Some operations (such as [`Time.Add`](https://golang.org/pkg/time/#Time.Add) and 55 [`Time.Round`](https://golang.org/pkg/time/#Time.Round)) require a 56 [`Duration`](https://golang.org/pkg/time/#Duration) value. These can be created 57 conveniently with the following functions: 58 59 - `time.Nanosecond` 60 - `time.Microsecond` 61 - `time.Millisecond` 62 - `time.Second` 63 - `time.Minute` 64 - `time.Hour` 65 66 For example: 67 68 ```console 69 $ gomplate -i '{{ (time.Now).Format time.Kitchen }} 70 {{ ((time.Now).Add (time.Hour 2)).Format time.Kitchen }}' 71 9:05AM 72 11:05AM 73 ``` 74 75 For other durations, such as `2h10m`, [`time.ParseDuration`](#time-parseduration) can be used. 76 77 ## `time.Now` 78 79 Returns the current local time, as a `time.Time`. This wraps [`time.Now`](https://golang.org/pkg/time/#Now). 80 81 Usually, further functions are called using the value returned by `Now`. 82 83 ### Usage 84 85 ```go 86 time.Now 87 ``` 88 89 90 ### Examples 91 92 Usage with [`UTC`](https://golang.org/pkg/time/#Time.UTC) and [`Format`](https://golang.org/pkg/time/#Time.Format): 93 ```console 94 $ gomplate -i '{{ (time.Now).UTC.Format "Day 2 of month 1 in year 2006 (timezone MST)" }}' 95 Day 14 of month 10 in year 2017 (timezone UTC) 96 ``` 97 Usage with [`AddDate`](https://golang.org/pkg/time/#Time.AddDate): 98 ```console 99 $ date 100 Sat Oct 14 09:57:02 EDT 2017 101 $ gomplate -i '{{ ((time.Now).AddDate 0 1 0).Format "Mon Jan 2 15:04:05 MST 2006" }}' 102 Tue Nov 14 09:57:02 EST 2017 103 ``` 104 105 _(notice how the TZ adjusted for daylight savings!)_ 106 107 ## `time.Parse` 108 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 119 ### Usage 120 121 ```go 122 time.Parse layout timestamp 123 ``` 124 ```go 125 timestamp | time.Parse layout 126 ``` 127 128 ### Arguments 129 130 | name | description | 131 |------|-------------| 132 | `layout` | _(required)_ The layout string to parse with | 133 | `timestamp` | _(required)_ The timestamp to parse | 134 135 ### Examples 136 137 Usage with [`Format`](https://golang.org/pkg/time/#Time.Format): 138 ```console 139 $ gomplate -i '{{ (time.Parse "2006-01-02" "1993-10-23").Format "Monday January 2, 2006 MST" }}' 140 Saturday October 23, 1993 UTC 141 ``` 142 143 ## `time.ParseDuration` 144 145 Parses a duration string. This wraps [`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration). 146 147 A duration string is a possibly signed sequence of decimal numbers, each with 148 optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid 149 time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. 150 151 ### Usage 152 153 ```go 154 time.ParseDuration duration 155 ``` 156 ```go 157 duration | time.ParseDuration 158 ``` 159 160 ### Arguments 161 162 | name | description | 163 |------|-------------| 164 | `duration` | _(required)_ The duration string to parse | 165 166 ### Examples 167 168 ```console 169 $ gomplate -i '{{ (time.Now).Format time.Kitchen }} 170 {{ ((time.Now).Add (time.ParseDuration "2h30m")).Format time.Kitchen }}' 171 12:43AM 172 3:13AM 173 ``` 174 175 ## `time.ParseLocal` 176 177 Same as [`time.Parse`](#time-parse), except that in the absence of a time zone 178 indicator, the timestamp wil be parsed in the local timezone. 179 180 ### Usage 181 182 ```go 183 time.ParseLocal layout timestamp 184 ``` 185 ```go 186 timestamp | time.ParseLocal layout 187 ``` 188 189 ### Arguments 190 191 | name | description | 192 |------|-------------| 193 | `layout` | _(required)_ The layout string to parse with | 194 | `timestamp` | _(required)_ The timestamp to parse | 195 196 ### Examples 197 198 Usage with [`Format`](https://golang.org/pkg/time/#Time.Format): 199 ```console 200 $ bin/gomplate -i '{{ (time.ParseLocal time.Kitchen "6:00AM").Format "15:04 MST" }}' 201 06:00 EST 202 ``` 203 204 ## `time.ParseInLocation` 205 206 Same as [`time.Parse`](#time-parse), except that the time is parsed in the given location's time zone. 207 208 This wraps [`time.ParseInLocation`](https://golang.org/pkg/time/#ParseInLocation). 209 210 ### Usage 211 212 ```go 213 time.ParseInLocation layout location timestamp 214 ``` 215 ```go 216 timestamp | time.ParseInLocation layout location 217 ``` 218 219 ### Arguments 220 221 | name | description | 222 |------|-------------| 223 | `layout` | _(required)_ The layout string to parse with | 224 | `location` | _(required)_ The location to parse in | 225 | `timestamp` | _(required)_ The timestamp to parse | 226 227 ### Examples 228 229 Usage with [`Format`](https://golang.org/pkg/time/#Time.Format): 230 ```console 231 $ gomplate -i '{{ (time.ParseInLocation time.Kitchen "Africa/Luanda" "6:00AM").Format "15:04 MST" }}' 232 06:00 LMT 233 ``` 234 235 ## `time.Since` 236 237 Returns the time elapsed since a given time. This wraps [`time.Since`](https://golang.org/pkg/time/#Since). 238 239 It is shorthand for `time.Now.Sub t`. 240 241 ### Usage 242 243 ```go 244 time.Since t 245 ``` 246 ```go 247 t | time.Since 248 ``` 249 250 ### Arguments 251 252 | name | description | 253 |------|-------------| 254 | `t` | _(required)_ the `Time` to calculate since | 255 256 ### Examples 257 258 ```console 259 $ gomplate -i '{{ $t := time.Parse time.RFC3339 "1970-01-01T00:00:00Z" }}time since the epoch:{{ time.Since $t }}' 260 time since the epoch:423365h0m24.353828924s 261 ``` 262 263 ## `time.Unix` 264 265 Returns the local `Time` corresponding to the given Unix time, in seconds since 266 January 1, 1970 UTC. Note that fractional seconds can be used to denote 267 milliseconds, but must be specified as a string, not a floating point number. 268 269 ### Usage 270 271 ```go 272 time.Unix time 273 ``` 274 ```go 275 time | time.Unix 276 ``` 277 278 ### Arguments 279 280 | name | description | 281 |------|-------------| 282 | `time` | _(required)_ the time to parse | 283 284 ### Examples 285 286 _with whole seconds:_ 287 ```console 288 $ gomplate -i '{{ (time.Unix 42).UTC.Format time.Stamp}}' 289 Jan 1, 00:00:42 290 ``` 291 292 _with fractional seconds:_ 293 ```console 294 $ gomplate -i '{{ (time.Unix "123456.789").UTC.Format time.StampMilli}}' 295 Jan 2 10:17:36.789 296 ``` 297 298 ## `time.Until` 299 300 Returns the duration until a given time. This wraps [`time.Until`](https://golang.org/pkg/time/#Until). 301 302 It is shorthand for `$t.Sub time.Now`. 303 304 ### Usage 305 306 ```go 307 time.Until t 308 ``` 309 ```go 310 t | time.Until 311 ``` 312 313 ### Arguments 314 315 | name | description | 316 |------|-------------| 317 | `t` | _(required)_ the `Time` to calculate until | 318 319 ### Examples 320 321 ```console 322 $ gomplate -i '{{ $t := time.Parse time.RFC3339 "2020-01-01T00:00:00Z" }}only {{ time.Until $t }} to go...' 323 only 14922h56m46.578625891s to go... 324 ``` 325 326 Or, less precise: 327 ```console 328 $ bin/gomplate -i '{{ $t := time.Parse time.RFC3339 "2020-01-01T00:00:00Z" }}only {{ (time.Until $t).Round (time.Hour 1) }} to go...' 329 only 14923h0m0s to go... 330 ``` 331 332 ## `time.ZoneName` 333 334 Return the local system's time zone's name. 335 336 ### Usage 337 338 ```go 339 time.ZoneName 340 ``` 341 342 343 ### Examples 344 345 ```console 346 $ gomplate -i '{{time.ZoneName}}' 347 EDT 348 ``` 349 350 ## `time.ZoneOffset` 351 352 Return the local system's time zone offset, in seconds east of UTC. 353 354 ### Usage 355 356 ```go 357 time.ZoneOffset 358 ``` 359 360 361 ### Examples 362 363 ```console 364 $ gomplate -i '{{time.ZoneOffset}}' 365 -14400 366 ```