Next: , Previous: Querying timestamp Objects, Up: Public API


2.5 Manipulating Date and Time Values

— Function: timestamp+ time amount unit
— Function: timestamp- time amount unit

Add or subtract the amount to the time using the specified unit. unit may be one of ( :nsec :sec :minute :hour :day :month :year). The value of the parts of the timestamp of higher resolution than the UNIT will never be touched. If you want a precise number of seconds from a time, you should specify the offset in seconds.

— Function: timestamp-maximize-part timestamp part &key offset timezone into

Returns a timestamp with its parts maximized up to part. part can be any of (:nsec :sec :min :hour :day :month). If into is specified, it will be modified and returned, otherwise a new timestamp will be created.

— Function: timestamp-minimize-part timestamp part &key offset timezone into

Returns a timestamp with its parts minimized up to part. part can be any of (:nsec :sec :min :hour :day :month). If into is specified, it will be modified and returned, otherwise a new timestamp will be created.

— Macro: adjust-timestamp timestamp &body changes

Alters various parts of timestamp, given a list of changes. The changes are in the format (offset part value) and (set part value).

       ;; Return a new timestamp value that points to the previous Monday
       (adjust-timestamp (today) (offset :day-of-week :monday))
       
       ;; Return a new timestamp value that points three days ahead from now
       (adjust-timestamp (today) (offset :day 3))

Keep in mind that adjust-timestamp is not a mere setter for fields but instead it handles overflows and timezone conversions as expected. Also note that it's possible to specify multiple commands.

The list of possible places to manipulate are: :nsec :sec :sec-of-day :minute :hour :day :day-of-month :month :year.

— Macro: adjust-timestamp! timestamp &body changes

Just like adjust-timestamp, but instead of returning a freshly constructed value, it alters the provided timestamp value (and returns it).

— Function: timestamp-whole-year-difference time-a time-b

Returns the number of whole years elapsed between time-a and time-b.

Note: This is useful for calculating anniversaries and birthdays.

— Function: days-in-month month year

Returns the number of days in a given month of the specified year.