Previous: Manipulating Date and Time Values, Up: Public API


2.6 Parsing and Formatting

— Constant: +iso-8601-format+

The constant +iso-8601-format+ is bound to a description of the ISO 8601 format. An output with this format will look like this: ‘2008-03-01T19:42:34.608506+01:00’. This is the default format for the format-timestring function.

— Constant: +asctime-format+

The constant +asctime-format+ is bound to a format mirroring the output of the POSIX asctime() function. An output with this format will look like this: ‘Sat Mar 1 19:42:34 2008’.

— Constant: +rfc-1123-format+

The constant +rfc-1123-format+ is bound to a description of the format defined in RFC 1123 for Internet timestamps. An output with this format will look like this: ‘Sat, 01 Mar 2008 19:42:34 EDT’.

— Constant: +iso-week-date-format+

The constant +iso-week-date-format+ is bound to a description of the ISO 8601 Week Date format. An output with this format will look like this: ‘2009-W53-5’.

— Function: parse-timestring timestring &key (start 0) end (fail-on-error t) (offset 0)

Parses a timestring and returns the corresponding timestamp. Parsing begins at start and stops at the end position. If there are invalid characters within timestring and fail-on-error is T, then an invalid-timestring error is signaled, otherwise NIL is returned.

If there is no timezone specified in timestring then offset is used as the default timezone offset (in seconds).

— Function: format-timestring (destination timestamp &key (format +iso-8601-format+) (timezone *default-timezone*))

Constructs a string representation of TIMESTAMP according to FORMAT and returns it. If destination is T, the string is written to *standard-output*. If destination is a stream, the string is written to the stream.

FORMAT is a list containing one or more of strings, characters, and keywords. Strings and characters are output literally, while keywords are replaced by the values here:

:year
*year
:month
*numeric month
:day
*day of month
:weekday
*numeric day of week, starting from 0 which means Sunday
:hour
*hour
:min
*minutes
:sec
*seconds
:msec
*milliseconds
:usec
*microseconds
:nsec
*nanoseconds
:iso-week-year
*year for ISO week date (can be different from regular calendar year)
:iso-week-number
*ISO week number (i.e. 1 through 53)
:iso-week-day
*ISO compatible weekday number (i.e. monday=1, sunday=7)
:ordinal-day
day of month as an ordinal (e.g. 1st, 23rd)
:long-weekday
long form of weekday (e.g. Sunday, Monday)
:short-weekday
short form of weekday (e.g. Sun, Mon)
:long-month
long form of month (e.g. January, February)
:short-month
short form of month (e.g. Jan, Feb)
:hour12
hour on a 12-hour clock
:ampm
am/pm marker in lowercase
:gmt-offset
the gmt-offset of the time, in +00:00 form
:gmt-offset-or-z
like :gmt-offset, but is Z when UTC
:timezone
timezone abbrevation for the time

Elements marked by * can be placed in a list in the form:

       (:keyword padding &optional (padchar #\0))

The string representation of the value will be padded with the padchar.

You can see examples by examining the values in +iso-8601-format+, +asctime-format+, and +rfc-1123-format+.

Produces on stream the timestring corresponding to the timestamp with the given options. If stream is nil, only returns a string containing what would have been the output. If stream is t, prints the string to *standard-output*.

Example output:

       LOCAL-TIME> (format-timestring nil (now))
       "2008-03-01T19:42:34.608506+01:00"

— Function: format-rfc3339-timestring (destination timestamp &key omit-date-part omit-time-part omit-timezone-part (use-zulu t))

Formats the time like format-timestring, but in RFC 3339 format. The options control valid options in the RFC.