Usage of local-time's make-timestamp macro

Question

I'm a beginner with Common Lisp and I'm currently trying out the package local-time.

I'm trying to create a date with the make-timestamp macro which creates an instance of timestamp. I consulted the local-time manual, but I do not understand which arguments I have to supply.

The description of the macro is as follows:

— Macro: make-timestamp &key :day :sec :nsec

Expands to an expression that creates an instance of a timestamp exactly as specified.

Simply using the macro without any arguments makes this happen:

LOCAL-TIME> (make-timestamp)
@2000-03-01T01:00:00.000000+01:00

2000-03-01 is the standard epoch here, so this seems okay so far.

Passing :day 3 as an argument gives me this:

LOCAL-TIME> (make-timestamp :day 3)
@2000-03-04T01:00:00.000000+01:00

Okay. But how can I construct a date from this without having to count days and days into the future from 2000-03-01?

There is also a function called encode-timestamp which appears to do exactly what I want (namely: creating a date by supplying information like the day of the month, month, year, hour, minutes and so on):

LOCAL-TIME> (encode-timestamp 0 0 30 10 13 5 2009)
@2009-05-13T10:30:00.000000+02:00

But then, what is the make-timestamp macro supposed to do?

Answer 1

Make-timestamp is used by several of the encoding functions, including encode-timestamp. I would regard it as rather lowlevel, but it might be of interest to a user of the library.

Encode-timestamp seems to be just the function you want.