»formatdate Function

formatdate converts a timestamp into a different time format.

formatdate(spec, timestamp)

In Packer, timestamps are conventionally represented as strings using RFC 3339 "Date and Time format" syntax. formatdate requires the timestamp argument to be a string conforming to this syntax.

»Examples

> formatdate("DD MMM YYYY hh:mm ZZZ", "2018-01-02T23:12:01Z")
02 Jan 2018 23:12 UTC
> formatdate("EEEE, DD-MMM-YY hh:mm:ss ZZZ", "2018-01-02T23:12:01Z")
Tuesday, 02-Jan-18 23:12:01 UTC
> formatdate("EEE, DD MMM YYYY hh:mm:ss ZZZ", "2018-01-02T23:12:01-08:00")
Tue, 02 Jan 2018 23:12:01 -0800
> formatdate("MMM DD, YYYY", "2018-01-02T23:12:01Z")
Jan 02, 2018
> formatdate("HH:mmaa", "2018-01-02T23:12:01Z")
11:12pm

»Specification Syntax

The format specification is a string that includes formatting sequences from the following table. This function is intended for producing common machine-oriented timestamp formats such as those defined in RFC822, RFC850, and RFC1123. It is not suitable for truly human-oriented date formatting because it is not locale-aware. In particular, it can produce month and day names only in English.

The specification may contain the following sequences:

SequenceResult
YYYYFour (or more) digit year, like "2006".
YYThe year modulo 100, zero padded to at least two digits, like "06".
MMMMEnglish month name unabbreviated, like "January".
MMMEnglish month name abbreviated to three letters, like "Jan".
MMMonth number zero-padded to two digits, like "01" for January.
MMonth number with no padding, like "1" for January.
DDDay of month number zero-padded to two digits, like "02".
DDay of month number with no padding, like "2".
EEEEEnglish day of week name unabbreviated, like "Monday".
EEEEnglish day of week name abbreviated to three letters, like "Mon".
hh24-hour number zero-padded to two digits, like "02".
h24-hour number unpadded, like "2".
HH12-hour number zero-padded to two digits, like "02".
H12-hour number unpadded, like "2".
AAHour AM/PM marker in uppercase, like "AM".
aaHour AM/PM marker in lowercase, like "am".
mmMinute within hour zero-padded to two digits, like "05".
mMinute within hour unpadded, like "5".
ssSecond within minute zero-padded to two digits, like "09".
sSecond within minute, like "9".
ZZZZZTimezone offset with colon separating hours and minutes, like "-08:00".
ZZZZTimezone offset with just sign and digit, like "-0800".
ZZZLike ZZZZ but with a special case "UTC" for UTC.
ZLike ZZZZZ but with a special case "Z" for UTC.

Any non-letter characters, such as punctuation, are reproduced verbatim in the output. To include literal letters in the format string, enclose them in single quotes '. To include a literal quote, escape it by doubling the quotes.

> formatdate("h'h'mm", "2018-01-02T23:12:01-08:00")
23h12
> formatdate("H 'o''clock'", "2018-01-02T23:12:01-08:00")
11 o'clock

This format specification syntax is intended to make it easy for a reader to guess which format will result even if they are not experts on the syntax. Therefore there are no predefined shorthands for common formats, but format strings for various RFC-specified formats are given below to be copied into your configuration as needed:

  • RFC 822 and RFC RFC 2822: "DD MMM YYYY hh:mm ZZZ"
  • RFC 850: "EEEE, DD-MMM-YY hh:mm:ss ZZZ"
  • RFC 1123: "EEE, DD MMM YYYY hh:mm:ss ZZZ"
  • RFC 3339: "YYYY-MM-DD'T'hh:mm:ssZ" (but this is also the input format, so such a conversion is redundant.)

»Related Functions

  • format is a more general formatting function for arbitrary data.
  • timestamp returns the current date and time in a format suitable for input to formatdate.