7.5 Extracting information from dates

A number of functions are available to return discrete pieces of information from a specified <date> object. These are useful to allow you to deconstruct a given date in order to retrieve useful information from it.

The most basic way to extract information from a date is to use the function decode-date.

decode-date

Function

decode-date date => year month day hours minutes seconds 
                    day-of-week time-zone-offset

Decodes a <date> into its constituent parts. This function is the companion of encode-date, in that it takes a <date> object and returns all of its constituent parts. Note, however, that in contrast to encode-date, it does not return any millisecond component to the date, but it does return the day of the week of the specified date.

A number of other functions exist to extract individual components from a <date> object. Each of these functions is listed below. Each function takes a single argument, a <date> object, and returns the component of the date referred to in the function name. For example, date-month takes a <date> object as an argument, and returns the month that the date refers to.

date-year
date-month
date-day
date-day-of-week
date-hours
date-minutes
date-seconds
date-microseconds
date-time-zone-offset

For each function except date-day-of-week, the value returned is an instance of <integer>. The date-day-of-week function returns an object of type <day-of-week>. For more information, please refer to the reference entries of each function. See also the function date-time-zone-offset-setter, which allows you to set the time-zone offset of a <date> explicitly.

To return an ISO 8601 format date from a <date> object, use the function as-iso8601-string.

as-iso8601-string

Function

as-iso8601-string date #key precision => iso8601-string

Returns an instance of <string> representing a date in ISO 8601 format. The precision keyword, if present, is an integer representing the number of decimal places to which the second should be specified in the result.

---

System and I/O Reference - 31 MAR 2000