github.com/wynshop-open-source/gomplate@v3.5.0+incompatible/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      description: |
    74        Returns the current local time, as a `time.Time`. This wraps [`time.Now`](https://golang.org/pkg/time/#Now).
    75  
    76        Usually, further functions are called using the value returned by `Now`.
    77      pipeline: false
    78      rawExamples:
    79        - |
    80          Usage with [`UTC`](https://golang.org/pkg/time/#Time.UTC) and [`Format`](https://golang.org/pkg/time/#Time.Format):
    81          ```console
    82          $ gomplate -i '{{ (time.Now).UTC.Format "Day 2 of month 1 in year 2006 (timezone MST)" }}'
    83          Day 14 of month 10 in year 2017 (timezone UTC)
    84          ```
    85        - |
    86          Usage with [`AddDate`](https://golang.org/pkg/time/#Time.AddDate):
    87          ```console
    88          $ date
    89          Sat Oct 14 09:57:02 EDT 2017
    90          $ gomplate -i '{{ ((time.Now).AddDate 0 1 0).Format "Mon Jan 2 15:04:05 MST 2006" }}'
    91          Tue Nov 14 09:57:02 EST 2017
    92          ```
    93  
    94          _(notice how the TZ adjusted for daylight savings!)_
    95    - name: time.Parse
    96      description: |
    97        Parses a timestamp defined by the given layout. This wraps [`time.Parse`](https://golang.org/pkg/time/#Parse).
    98  
    99        A number of pre-defined layouts are provided as constants, defined
   100        [here](https://golang.org/pkg/time/#pkg-constants).
   101  
   102        Just like [`time.Now`](#time-now), this is usually used in conjunction with
   103        other functions.
   104  
   105        _Note: In the absence of a time zone indicator, `time.Parse` returns a time in UTC._
   106      pipeline: true
   107      arguments:
   108        - name: layout
   109          required: true
   110          description: The layout string to parse with
   111        - name: timestamp
   112          required: true
   113          description: The timestamp to parse
   114      rawExamples:
   115        - |
   116          Usage with [`Format`](https://golang.org/pkg/time/#Time.Format):
   117          ```console
   118          $ gomplate -i '{{ (time.Parse "2006-01-02" "1993-10-23").Format "Monday January 2, 2006 MST" }}'
   119          Saturday October 23, 1993 UTC
   120          ```
   121    - name: time.ParseDuration
   122      description: |
   123        Parses a duration string. This wraps [`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration).
   124  
   125        A duration string is a possibly signed sequence of decimal numbers, each with
   126        optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid
   127        time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
   128      pipeline: true
   129      arguments:
   130        - name: duration
   131          required: true
   132          description: The duration string to parse
   133      examples:
   134        - |
   135          $ gomplate -i '{{ (time.Now).Format time.Kitchen }}
   136          {{ ((time.Now).Add (time.ParseDuration "2h30m")).Format time.Kitchen }}'
   137          12:43AM
   138          3:13AM
   139    - name: time.ParseLocal
   140      description: |
   141        Same as [`time.Parse`](#time-parse), except that in the absence of a time zone
   142        indicator, the timestamp wil be parsed in the local timezone.
   143      pipeline: true
   144      arguments:
   145        - name: layout
   146          required: true
   147          description: The layout string to parse with
   148        - name: timestamp
   149          required: true
   150          description: The timestamp to parse
   151      rawExamples:
   152        - |
   153          Usage with [`Format`](https://golang.org/pkg/time/#Time.Format):
   154          ```console
   155          $ bin/gomplate -i '{{ (time.ParseLocal time.Kitchen "6:00AM").Format "15:04 MST" }}'
   156          06:00 EST
   157          ```
   158    - name: time.ParseInLocation
   159      description: |
   160        Same as [`time.Parse`](#time-parse), except that the time is parsed in the given location's time zone.
   161  
   162        This wraps [`time.ParseInLocation`](https://golang.org/pkg/time/#ParseInLocation).
   163      pipeline: true
   164      arguments:
   165        - name: layout
   166          required: true
   167          description: The layout string to parse with
   168        - name: location
   169          required: true
   170          description: The location to parse in
   171        - name: timestamp
   172          required: true
   173          description: The timestamp to parse
   174      rawExamples:
   175        - |
   176          Usage with [`Format`](https://golang.org/pkg/time/#Time.Format):
   177          ```console
   178          $ gomplate -i '{{ (time.ParseInLocation time.Kitchen "Africa/Luanda" "6:00AM").Format "15:04 MST" }}'
   179          06:00 LMT
   180          ```
   181    - name: time.Since
   182      description: |
   183        Returns the time elapsed since a given time. This wraps [`time.Since`](https://golang.org/pkg/time/#Since).
   184  
   185        It is shorthand for `time.Now.Sub t`.
   186      pipeline: true
   187      arguments:
   188        - name: t
   189          required: true
   190          description: the `Time` to calculate since
   191      examples:
   192        - |
   193          $ gomplate -i '{{ $t := time.Parse time.RFC3339 "1970-01-01T00:00:00Z" }}time since the epoch:{{ time.Since $t }}'
   194          time since the epoch:423365h0m24.353828924s
   195    - name: time.Unix
   196      description: |
   197        Returns the local `Time` corresponding to the given Unix time, in seconds since
   198        January 1, 1970 UTC. Note that fractional seconds can be used to denote
   199        milliseconds, but must be specified as a string, not a floating point number.
   200      pipeline: true
   201      arguments:
   202        - name: time
   203          required: true
   204          description: the time to parse
   205      rawExamples:
   206        - |
   207          _with whole seconds:_
   208          ```console
   209          $ gomplate -i '{{ (time.Unix 42).UTC.Format time.Stamp}}'
   210          Jan  1, 00:00:42
   211          ```
   212  
   213          _with fractional seconds:_
   214          ```console
   215          $ gomplate -i '{{ (time.Unix "123456.789").UTC.Format time.StampMilli}}'
   216          Jan  2 10:17:36.789
   217          ```
   218    - name: time.Until
   219      description: |
   220        Returns the duration until a given time. This wraps [`time.Until`](https://golang.org/pkg/time/#Until).
   221  
   222        It is shorthand for `$t.Sub time.Now`.
   223      pipeline: true
   224      arguments:
   225        - name: t
   226          required: true
   227          description: the `Time` to calculate until
   228      rawExamples:
   229        - |
   230          ```console
   231          $ gomplate -i '{{ $t := time.Parse time.RFC3339 "2020-01-01T00:00:00Z" }}only {{ time.Until $t }} to go...'
   232          only 14922h56m46.578625891s to go...
   233          ```
   234  
   235          Or, less precise:
   236          ```console
   237          $ bin/gomplate -i '{{ $t := time.Parse time.RFC3339 "2020-01-01T00:00:00Z" }}only {{ (time.Until $t).Round (time.Hour 1) }} to go...'
   238          only 14923h0m0s to go...
   239          ```
   240    - name: time.ZoneName
   241      description: |
   242        Return the local system's time zone's name.
   243      pipeline: false
   244      examples:
   245        - |
   246          $ gomplate -i '{{time.ZoneName}}'
   247          EDT
   248    - name: time.ZoneOffset
   249      description: |
   250        Return the local system's time zone offset, in seconds east of UTC.
   251      pipeline: false
   252      examples:
   253        - |
   254          $ gomplate -i '{{time.ZoneOffset}}'
   255          -14400