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  ```