Simple-Date
Simple-date provides types (CLOS classes) for dates, timestamps, and intervals similar to the ones SQL databases use, in order to be able to store and read these to and from a database in a straighforward way. A few obvious operations are defined on these types.
To use this library with cl-postgres or postmodern and get the simple-date reader to be loaded, you need to load simple-date/postgres-glue and then set the readtable. This will register suitable SQL readers and writers for the associated database types.
(ql:quickload :simple-date/postgres-glue)
(setf cl-postgres:*sql-readtable*
(cl-postgres:copy-sql-readtable
simple-date-cl-postgres-glue:*simple-date-sql-readtable*))
The most glaring defect of this library is its ignorance of time zones. It pretends the whole world lives in UTC. Use with care.
To get back to the default cl-postgres reader:
(setf cl-postgres:*sql-readtable*
(cl-postgres:copy-sql-readtable
cl-postgres::*default-sql-readtable*))
To use the simple-date reader when cl-postgres is using the default:
(setf cl-postgres:*sql-readtable*
(cl-postgres:copy-sql-readtable
simple-date-cl-postgres-glue:*simple-date-sql-readtable*))
As a reminder for those who want to use local-time, to enable the local-time reader:
(local-time:set-local-time-cl-postgres-readers)
Date type
function day-of-week (date)
→ integer
Determine the day of the week that the given date falls on. Value ranges from 0 to 6, with 0 being Sunday and 6 being Saturday.
function encode-timestamp (year month day &optional (hour 0) (minute 0) (second 0) (millisecond 0))
→ timestamp
Create a timestamp. No negative values or values outside of an arguments normal range (i.e. 60 for minutes, 1000 for milliseconds) should be passed.
function decode-timestamp (timestamp)
→ (values year month day hour minute second millisecond)
Decode a timestamp into its components.
function timestamp-to-universal-time (timestamp)
→ universal-time
Convert a timestamp to the corresponding universal-time, rounding to seconds. Note that this will treat the timestamp as if it were in UTC.
function universal-time-to-timestamp (universal-time)
→ timestamp
Create a timestamp from a universal time. Again, the resulting timestamp should be treated as if it were in UTC.
Interval type
class interval
An interval represents a period of time. It contains both an absolute part in milliseconds (days, weeks, minutes, etc are always the same length), and a relative part for months and years ― the amount of time that a month or year represents is not always the same.
Operations
To prevent a proliferation of different function names, generic functions are used for operations on time values. The semantics of these differ for the type of the operands.
method time-add (a b)
→ value
Adds two time-related objects. Adding an interval to a date or timestamp will return a new date or timestamp, increased by the value of the interval. Adding two intervals returns a new interval with the sum of the two arguments. Integers can be used in place of intervals, and will be interpreted as an amount of milliseconds.
method time-subtract (a b)
→ value
Subtracts time-related objects from each other. Subtracting two dates or timestamps results in an interval that represents the difference between them. Similarly, subtracting two intervals also gives their difference.
method time= (a b)
→ boolean
Compare two time-related values, returns a boolean indicating whether they denote the same time or period.
method time< (a b)
→ boolean
Compare two time-related values, returns a boolean indicating whether the first is less than the second.