github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/docs/job-specification/hcl2/functions/datetime/formatdate.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: formatdate - Functions - Configuration Language
     4  sidebar_title: formatdate
     5  description: The formatdate function converts a timestamp into a different time format.
     6  ---
     7  
     8  # `formatdate` Function
     9  
    10  `formatdate` converts a timestamp into a different time format.
    11  
    12  ```hcl
    13  formatdate(spec, timestamp)
    14  ```
    15  
    16  In Nomad, timestamps are conventionally represented as strings using [RFC
    17  3339](https://tools.ietf.org/html/rfc3339) "Date and Time format" syntax.
    18  `formatdate` requires the `timestamp` argument to be a string conforming to
    19  this syntax.
    20  
    21  ## Examples
    22  
    23  ```shell-session
    24  > formatdate("DD MMM YYYY hh:mm ZZZ", "2018-01-02T23:12:01Z")
    25  02 Jan 2018 23:12 UTC
    26  > formatdate("EEEE, DD-MMM-YY hh:mm:ss ZZZ", "2018-01-02T23:12:01Z")
    27  Tuesday, 02-Jan-18 23:12:01 UTC
    28  > formatdate("EEE, DD MMM YYYY hh:mm:ss ZZZ", "2018-01-02T23:12:01-08:00")
    29  Tue, 02 Jan 2018 23:12:01 -0800
    30  > formatdate("MMM DD, YYYY", "2018-01-02T23:12:01Z")
    31  Jan 02, 2018
    32  > formatdate("HH:mmaa", "2018-01-02T23:12:01Z")
    33  11:12pm
    34  ```
    35  
    36  ## Specification Syntax
    37  
    38  The format specification is a string that includes formatting sequences from
    39  the following table. This function is intended for producing common
    40  _machine-oriented_ timestamp formats such as those defined in RFC822, RFC850,
    41  and RFC1123. It is not suitable for truly human-oriented date formatting
    42  because it is not locale-aware. In particular, it can produce month and day
    43  names only in English.
    44  
    45  The specification may contain the following sequences:
    46  
    47  | Sequence | Result                                                                  |
    48  | -------- | ----------------------------------------------------------------------- |
    49  | `YYYY`   | Four (or more) digit year, like "2006".                                 |
    50  | `YY`     | The year modulo 100, zero padded to at least two digits, like "06".     |
    51  | `MMMM`   | English month name unabbreviated, like "January".                       |
    52  | `MMM`    | English month name abbreviated to three letters, like "Jan".            |
    53  | `MM`     | Month number zero-padded to two digits, like "01" for January.          |
    54  | `M`      | Month number with no padding, like "1" for January.                     |
    55  | `DD`     | Day of month number zero-padded to two digits, like "02".               |
    56  | `D`      | Day of month number with no padding, like "2".                          |
    57  | `EEEE`   | English day of week name unabbreviated, like "Monday".                  |
    58  | `EEE`    | English day of week name abbreviated to three letters, like "Mon".      |
    59  | `hh`     | 24-hour number zero-padded to two digits, like "02".                    |
    60  | `h`      | 24-hour number unpadded, like "2".                                      |
    61  | `HH`     | 12-hour number zero-padded to two digits, like "02".                    |
    62  | `H`      | 12-hour number unpadded, like "2".                                      |
    63  | `AA`     | Hour AM/PM marker in uppercase, like "AM".                              |
    64  | `aa`     | Hour AM/PM marker in lowercase, like "am".                              |
    65  | `mm`     | Minute within hour zero-padded to two digits, like "05".                |
    66  | `m`      | Minute within hour unpadded, like "5".                                  |
    67  | `ss`     | Second within minute zero-padded to two digits, like "09".              |
    68  | `s`      | Second within minute, like "9".                                         |
    69  | `ZZZZZ`  | Timezone offset with colon separating hours and minutes, like "-08:00". |
    70  | `ZZZZ`   | Timezone offset with just sign and digit, like "-0800".                 |
    71  | `ZZZ`    | Like `ZZZZ` but with a special case "UTC" for UTC.                      |
    72  | `Z`      | Like `ZZZZZ` but with a special case "Z" for UTC.                       |
    73  
    74  Any non-letter characters, such as punctuation, are reproduced verbatim in the
    75  output. To include literal letters in the format string, enclose them in single
    76  quotes `'`. To include a literal quote, escape it by doubling the quotes.
    77  
    78  ```shell-session
    79  > formatdate("h'h'mm", "2018-01-02T23:12:01-08:00")
    80  23h12
    81  > formatdate("H 'o''clock'", "2018-01-02T23:12:01-08:00")
    82  11 o'clock
    83  ```
    84  
    85  This format specification syntax is intended to make it easy for a reader
    86  to guess which format will result even if they are not experts on the syntax.
    87  Therefore there are no predefined shorthands for common formats, but format
    88  strings for various RFC-specified formats are given below to be copied into your
    89  configuration as needed:
    90  
    91  - [RFC 822](https://tools.ietf.org/html/rfc822#section-5) and
    92    [RFC RFC 2822](https://tools.ietf.org/html/rfc2822#section-3.3):
    93    `"DD MMM YYYY hh:mm ZZZ"`
    94  - [RFC 850](https://tools.ietf.org/html/rfc850#section-2.1.4):
    95    `"EEEE, DD-MMM-YY hh:mm:ss ZZZ"`
    96  - [RFC 1123](https://tools.ietf.org/html/rfc1123#section-5.2.14):
    97    `"EEE, DD MMM YYYY hh:mm:ss ZZZ"`
    98  - [RFC 3339](https://tools.ietf.org/html/rfc3339):
    99    `"YYYY-MM-DD'T'hh:mm:ssZ"` (but this is also the input format, so such a
   100    conversion is redundant.)
   101  
   102  ## Related Functions
   103  
   104  - [`format`](/docs/job-specification/hcl2/functions/string/format) is a more general formatting function for arbitrary
   105    data.
   106  - [`timestamp`](/docs/job-specification/hcl2/functions/datetime/timestamp) returns the current date and time in a format
   107    suitable for input to `formatdate`.