1#+TITLE: Simple-Date
2#+OPTIONS: num:nil
3#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css" />
4#+HTML_HEAD: <style>pre.src{background:#343131;color:white;} </style>
5#+OPTIONS: ^:nil
6
7Simple-date provides types (CLOS classes) for dates, timestamps, and intervals
8similar to the ones SQL databases use, in order to be able to store and read
9these to and from a database in a straighforward way. A few obvious operations
10are defined on these types.
11
12To use this library with cl-postgres or postmodern and get the simple-date reader
13to be loaded, you need to load simple-date/postgres-glue
14and then set the readtable. This will register suitable SQL
15readers and writers for the associated database types.
16
17#+BEGIN_SRC lisp
18(ql:quickload :simple-date/postgres-glue)
19
20(setf cl-postgres:*sql-readtable*
21        (cl-postgres:copy-sql-readtable
22         simple-date-cl-postgres-glue:*simple-date-sql-readtable*))
23#+END_SRC
24
25The most glaring defect of this library is its ignorance of time zones. It
26pretends the whole world lives in UTC. Use with care.
27
28To get back to the default cl-postgres reader:
29#+BEGIN_SRC lisp
30(setf cl-postgres:*sql-readtable*
31        (cl-postgres:copy-sql-readtable
32         cl-postgres::*default-sql-readtable*))
33#+END_SRC
34
35To use the simple-date reader when cl-postgres is using the default:
36#+BEGIN_SRC lisp
37(setf cl-postgres:*sql-readtable*
38        (cl-postgres:copy-sql-readtable
39         simple-date-cl-postgres-glue:*simple-date-sql-readtable*))
40#+END_SRC
41
42As a reminder for those who want to use local-time, to enable the local-time
43reader:
44#+BEGIN_SRC lisp
45(local-time:set-local-time-cl-postgres-readers)
46#+END_SRC
47
48
49* Date type
50  :PROPERTIES:
51  :ID:       6cefa703-d55b-464d-bad9-7c7ceae0c90d
52  :END:
53** class date
54   :PROPERTIES:
55   :ID:       203d5d98-5ce7-4bcb-81d9-1aeb4fe2796d
56   :END:
57
58Represents a date, with no time-of-day information.
59
60** function encode-date (year month day)
61   :PROPERTIES:
62   :ID:       dbf2a874-80e1-4a43-86be-7febb1573b8d
63   :END:
64→ date
65
66Creates a date object.
67
68** function decode-date (date)
69   :PROPERTIES:
70   :ID:       35da4a62-ea64-4053-aa30-4496d56a0f95
71   :END:
72→ (values year month day)
73
74Extract the elements from a date object.
75
76** function day-of-week (date)
77   :PROPERTIES:
78   :ID:       b1590639-fd02-458d-86e4-6e1bd3c1c003
79   :END:
80→ integer
81
82Determine the day of the week that the given date falls on. Value ranges from
830 to 6, with 0 being Sunday and 6 being Saturday.
84
85** Timestamp type
86   :PROPERTIES:
87   :ID:       6efdaace-0c1c-45ba-8376-9b91e18a0b38
88   :END:
89class timestamp
90
91Represents an absolute timestamp, with a millisecond precision.
92
93** function encode-timestamp (year month day &optional (hour 0) (minute 0) (second 0) (millisecond 0))
94   :PROPERTIES:
95   :ID:       f6817a2a-92e2-44aa-9060-d9ab459f6207
96   :END:
97→ timestamp
98
99Create a timestamp. No negative values or values outside of an arguments normal
100range (i.e. 60 for minutes, 1000 for milliseconds) should be passed.
101
102** function decode-timestamp (timestamp)
103   :PROPERTIES:
104   :ID:       5cb5f677-4fc4-4ab3-b2af-65579e660baf
105   :END:
106→ (values year month day hour minute second millisecond)
107
108Decode a timestamp into its components.
109
110** function timestamp-to-universal-time (timestamp)
111   :PROPERTIES:
112   :ID:       477dd9e6-3e72-4eaa-b1fd-cf5d06bdfd1b
113   :END:
114→ universal-time
115
116Convert a timestamp to the corresponding universal-time, rounding to seconds.
117Note that this will treat the timestamp as if it were in UTC.
118
119** function universal-time-to-timestamp (universal-time)
120   :PROPERTIES:
121   :ID:       ba44156f-a860-4601-a5fe-6465d6ad8353
122   :END:
123→ timestamp
124
125Create a timestamp from a universal time. Again, the resulting timestamp should
126be treated as if it were in UTC.
127
128** Interval type
129   :PROPERTIES:
130   :ID:       316f3287-fd76-46ce-8c2b-c07ad381fc38
131   :END:
132class interval
133
134An interval represents a period of time. It contains both an absolute part in
135milliseconds (days, weeks, minutes, etc are always the same length), and a
136relative part for months and years ― the amount of time that a month or year
137represents is not always the same.
138
139** function encode-interval (&key (year 0) (month 0) (week 0) (day 0) (hour 0) (minute 0) (second 0) (millisecond 0))
140   :PROPERTIES:
141   :ID:       77212a01-b23f-40c7-aeec-fc93d4834f53
142   :END:
143→ interval
144
145Create an interval. Arguments may be negative and of any size.
146
147** function decode-interval (interval)
148   :PROPERTIES:
149   :ID:       cfd906be-cc00-437e-b250-b7d294131aa0
150   :END:
151→ (values year month day hour minute second millisecond)
152
153Decompose an interval into parts. Note that these may be different from the
154parameters that created it ― an interval of 3600 seconds is the same as one
155of 1 hour.
156
157* Operations
158  :PROPERTIES:
159  :ID:       d2616cd8-622b-464f-994e-e1f9d6309706
160  :END:
161To prevent a proliferation of different function names, generic functions
162are used for operations on time values. The semantics of these differ for
163the type of the operands.
164
165** method time-add (a b)
166   :PROPERTIES:
167   :ID:       6846ba8b-a59f-475e-bc25-0c18e4fa5548
168   :END:
169→ value
170
171Adds two time-related objects. Adding an interval to a date or timestamp
172will return a new date or timestamp, increased by the value of the interval.
173Adding two intervals returns a new interval with the sum of the two
174arguments. Integers can be used in place of intervals, and will be
175interpreted as an amount of milliseconds.
176
177** method time-subtract (a b)
178   :PROPERTIES:
179   :ID:       98dee89f-7178-4487-8d85-3036149f2def
180   :END:
181→ value
182
183Subtracts time-related objects from each other. Subtracting two dates or
184timestamps results in an interval that represents the difference between
185them. Similarly, subtracting two intervals also gives their difference.
186
187** method time= (a b)
188   :PROPERTIES:
189   :ID:       74acb8a0-5438-4a56-8d08-3316a7792108
190   :END:
191→ boolean
192
193Compare two time-related values, returns a boolean indicating whether
194they denote the same time or period.
195
196** method time< (a b)
197   :PROPERTIES:
198   :ID:       02b06b96-bbd7-482a-aa3c-f9080f97c3fa
199   :END:
200→ boolean
201
202Compare two time-related values, returns a boolean indicating whether the
203first is less than the second.
204
205** method time> (a b)
206   :PROPERTIES:
207   :ID:       6901c062-4b1c-4cb1-a9f6-6935141d5fdd
208   :END:
209→ boolean
210
211Compare two time-related values, returns a boolean indicating whether the
212first is greater than the second.
213
214** function time<= (a b)
215   :PROPERTIES:
216   :ID:       450e4d9e-2f31-4278-817a-bb42eaf0ea04
217   :END:
218→ boolean
219
220The inverse of time>.
221
222** function time>= (a b)
223   :PROPERTIES:
224   :ID:       d77174da-9511-41c6-bc46-95d62842435c
225   :END:
226→ boolean
227
228The inverse of time<.
229