---

I.2.2 Time Conversion

Functions that convert time values to Lisp timestamps or to calendrical information. Calendrical conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers count the number of years since the year 1 BC, and do not skip zero as traditional Gregorian years do; for example, the year number -37 represents the Gregorian year 38 BC.

Time Conversion Functions

time-convert—Time Value to Lisp Timestamp

Function: time-convert TIME &optional FORM ¶

This function converts a time value into a Lisp timestamp.

(time-convert nil nil)

is equivalent to

(current-time)

but the latter is a bit faster.

FORM

The optional form argument specifies the timestamp form to be returned.

‘’integer’

this function returns an integer count of seconds.

positive integer

it specifies a clock frequency and this function returns an integer-pair timestamp ‘(ticks . form)’.

‘t’

this function treats it as a positive integer suitable for representing the timestamp; for example, it is treated as 1000000000 if time is ‘nil’ and the platform timestamp has nanosecond resolution.

‘’list’

this function returns an integer list ‘(high low micro pico)’.

‘NIL’

currently acts like ‘’list’⁹

TIME

form is ‘t’

When form is ‘t’, conversion is always exact so no truncation occurs, and the returned clock resolution is no less than that of time.

inexact

if time cannot be represented exactly, conversion truncates it toward minus infinity.

infinite or ‘NaN’

this function signals an error

By way of contrast, float-time can convert any Lisp time value without signaling an error, although the result might not be exact.

decode-time—Time Value to Calendrical Info

Function: decode-time &optional TIME ZONE FORM ¶

This function converts a time value into calendrical information of the form:

(seconds minutes hour day month year dow dst utcoff)

TIME

Defaults to the current time.

ZONE

Defaults to the current time zone rule.

FORM

Controls the form of the returned ‘seconds’ element.

The ‘seconds’ element is a Lisp timestamp that is nonnegative and less than 61; it is less than 60 except during positive leap seconds

If the optional ‘form’ argument is ‘t’, seconds uses the same precision as time;

If ‘form’ is ‘’integer’, ‘seconds’ is truncated to an integer.

If ‘form’ is omitted or ‘nil’, it currently defaults to integer¹⁰

VALUE

The return value is a list of nine elements:

(seconds minutes hour day month year dow dst utcoff)

• seconds: past the minute
• minutes: past the hour— 0 ≤ minutes ≤ 59
• hour: of day— 0 ≤ hour ≤ 23
• day: of month— 1 ≤ day ≤ 31
• month: of year— 1 ≤ month ≤ 12
• year: an integer > 1900
• dow: an integer representing the day of week— 0 ≤ dow ≤ 6 (0 stands for Sunday)
• dst: ‘t’ if daylight savings time is in effect, ‘NIL’ if not, -1 if unavailable
• utcoff: an integer representing the Universal Time offset in seconds, .i,e, number of seconds east of Greenwich

Accessors and Setters

To access (or alter) the elements in the ‘TIME’ value, these accessors can be used.

• decoded-time-second
• decoded-time-minute
• decoded-time-hour
• decoded-time-day
• decoded-time-month
• decoded-time-year
• decoded-time-weekday
• decoded-time-dst
• decoded-time-zone

decoded-time-add

Function: decoded-time-add TIME DELTA ¶

This function takes a decoded time structure and adds ‘DELTA’ (also a decoded time structure) to it.

DELTA

Elements in ‘DELTA’ that are ‘nil’ are ignored. Fields are added in a most to least significant order. The values in ‘DELTA’ can be negative to subtract values instead.

For instance, if you want “same time next month”, you could say:

(let ((time (decode-time nil nil t))
   (delta (make-decoded-time :month 2)))
   (encode-time (decoded-time-add time delta)))

If this date doesn’t exist (if you’re running this on January 31st, for instance), then the date will be shifted back until you get a valid date (which will be February 28th or 29th, depending).

Return Value

The return value is a decoded time structure.

make-decoded-time

Function: make-decoded-time &key SECOND MINUTE HOUR DAY MONTH YEAR DST ZONE ¶

Return a decoded time structure with only the given keywords filled out, leaving the rest ‘nil’. To get a structure that represents “two months”, you could say:

(make-decoded-time :month 2)

encode-time

Function: encode-time &rest obsolescent-arguments ¶

This function converts ‘TIME’ to a Lisp timestamp. It can act as the inverse of decode-time. You can perform simple date arithmetic by using out-of-range values for seconds, minutes, hour, day, and month; for example, day 0 means the day preceding the given month.

TIME

Ordinarily the first argument is a list that specifies a decoded time in the style of decode-time:

(second minute hour day month year ignored dst zone)

Obsolescent Arguments

As an obsolescent calling convention, this function can be given six or more arguments. The first six arguments second, minute, hour, day, month, and year specify most of the components of a decoded time. If there are more than six arguments the last argument is used as ‘ZONE’ and any other extra arguments are ignored.