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