---

I.2.3 Time Parsing

These functions convert time values to text in a string, and vice versa. Time values include ‘nil’, numbers, and Lisp timestamps.

date-to-time—Time String to Timestamp

Function: date-to-time STRING ¶

This function parses the time-string string and returns the corresponding Lisp timestamp.

STRING

should represent a ‘date-time’, and should be in one of the forms recognized by parse-time-string. This function assumes Universal Time if string lacks explicit time zone information.

parse-time-string—Time String to Time List

Function: parse-time-string STRING ¶

This function parses the time-string ‘STRING’ into a list of the following form:

(sec min hour day mon year dow dst tz)

The format of this list is the same as what decode-time accepts. Any element that cannot be determined from the input will be set to ‘nil’.

STRING

should resemble an RFC 822 (or later) or ISO 8601 string, like “Fri, 25 Mar 2016 16:24:56 +0100” or “1998-09-12T12:21:54-0200”, but this function will attempt to parse less well-formed time strings as well.

iso8601-parse

Function: iso8601-parse STRING ¶

For a more strict function (that will error out upon invalid input), this function can be used instead. It can parse all variants of the ISO 8601 standard, so in addition to the formats mentioned above, it also parses things like “1998W45-3” (week number) and “1998-245” (ordinal day number). It returns decoded time structures.

iso8601-parse-duration

Parses a duration; returns a time structure.

iso8601-parse-interval

Parse an interval; returns 3 decoded time structures: the start, the end, and the duration.

format-time-string

Function: format-time-string FORMAT-STRING &optional TIME ZONE ¶

This function converts ‘TIME’ (or the current time, if time is omitted or ‘nil’) to a string according to ‘FORMAT-STRING’.

FORMAT-STRING

may contain ‘%’-sequences which say to substitute parts of the time.

One or more flag characters can appear immediately after the ‘%’.

• ‘0’ pads with zeros,
• ‘+’ pads with zeros and also puts ‘+’ before nonnegative year numbers with more than four digits,
• ‘_’ pads with blanks,
• ‘-’ suppresses padding,
• ‘^’ upper-cases letters, and
• ‘#’ reverses the case of letters.

You can also specify the field width and type of padding for any of these ‘%’-sequences.

This function uses the C library function strftime.

format-seconds

Function: format-seconds FORMAT-STRING SECONDS ¶

This function converts its argument SECONDS into a string of years, days, hours, etc., according to ‘FORMAT-STRING’. The argument ‘FORMAT-STRING’ may contain ‘%’-sequences which control the conversion.