Merge pull request #339 from sabracrolleton/master
[postmodern.git] / doc / simple-date.html
blobbf847040743e73d57285915b1cba19cc15930142
1 <!DOCTYPE html>
2 <html lang="en">
3 <head>
4 <!-- 2020-05-23 Sat 07:23 -->
5 <meta charset="utf-8">
6 <meta name="viewport" content="width=device-width, initial-scale=1">
7 <title>Simple-Date</title>
8 <meta name="generator" content="Org mode">
9 <style type="text/css">
10 <!--/*--><![CDATA[/*><!--*/
11 .title { text-align: center;
12 margin-bottom: .2em; }
13 .subtitle { text-align: center;
14 font-size: medium;
15 font-weight: bold;
16 margin-top:0; }
17 .todo { font-family: monospace; color: red; }
18 .done { font-family: monospace; color: green; }
19 .priority { font-family: monospace; color: orange; }
20 .tag { background-color: #eee; font-family: monospace;
21 padding: 2px; font-size: 80%; font-weight: normal; }
22 .timestamp { color: #bebebe; }
23 .timestamp-kwd { color: #5f9ea0; }
24 .org-right { margin-left: auto; margin-right: 0px; text-align: right; }
25 .org-left { margin-left: 0px; margin-right: auto; text-align: left; }
26 .org-center { margin-left: auto; margin-right: auto; text-align: center; }
27 .underline { text-decoration: underline; }
28 #postamble p, #preamble p { font-size: 90%; margin: .2em; }
29 p.verse { margin-left: 3%; }
30 pre {
31 border: 1px solid #ccc;
32 box-shadow: 3px 3px 3px #eee;
33 padding: 8pt;
34 font-family: monospace;
35 overflow: auto;
36 margin: 1.2em;
38 pre.src {
39 position: relative;
40 overflow: visible;
41 padding-top: 1.2em;
43 pre.src:before {
44 display: none;
45 position: absolute;
46 background-color: white;
47 top: -10px;
48 right: 10px;
49 padding: 3px;
50 border: 1px solid black;
52 pre.src:hover:before { display: inline;}
53 /* Languages per Org manual */
54 pre.src-asymptote:before { content: 'Asymptote'; }
55 pre.src-awk:before { content: 'Awk'; }
56 pre.src-C:before { content: 'C'; }
57 /* pre.src-C++ doesn't work in CSS */
58 pre.src-clojure:before { content: 'Clojure'; }
59 pre.src-css:before { content: 'CSS'; }
60 pre.src-D:before { content: 'D'; }
61 pre.src-ditaa:before { content: 'ditaa'; }
62 pre.src-dot:before { content: 'Graphviz'; }
63 pre.src-calc:before { content: 'Emacs Calc'; }
64 pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
65 pre.src-fortran:before { content: 'Fortran'; }
66 pre.src-gnuplot:before { content: 'gnuplot'; }
67 pre.src-haskell:before { content: 'Haskell'; }
68 pre.src-hledger:before { content: 'hledger'; }
69 pre.src-java:before { content: 'Java'; }
70 pre.src-js:before { content: 'Javascript'; }
71 pre.src-latex:before { content: 'LaTeX'; }
72 pre.src-ledger:before { content: 'Ledger'; }
73 pre.src-lisp:before { content: 'Lisp'; }
74 pre.src-lilypond:before { content: 'Lilypond'; }
75 pre.src-lua:before { content: 'Lua'; }
76 pre.src-matlab:before { content: 'MATLAB'; }
77 pre.src-mscgen:before { content: 'Mscgen'; }
78 pre.src-ocaml:before { content: 'Objective Caml'; }
79 pre.src-octave:before { content: 'Octave'; }
80 pre.src-org:before { content: 'Org mode'; }
81 pre.src-oz:before { content: 'OZ'; }
82 pre.src-plantuml:before { content: 'Plantuml'; }
83 pre.src-processing:before { content: 'Processing.js'; }
84 pre.src-python:before { content: 'Python'; }
85 pre.src-R:before { content: 'R'; }
86 pre.src-ruby:before { content: 'Ruby'; }
87 pre.src-sass:before { content: 'Sass'; }
88 pre.src-scheme:before { content: 'Scheme'; }
89 pre.src-screen:before { content: 'Gnu Screen'; }
90 pre.src-sed:before { content: 'Sed'; }
91 pre.src-sh:before { content: 'shell'; }
92 pre.src-sql:before { content: 'SQL'; }
93 pre.src-sqlite:before { content: 'SQLite'; }
94 /* additional languages in org.el's org-babel-load-languages alist */
95 pre.src-forth:before { content: 'Forth'; }
96 pre.src-io:before { content: 'IO'; }
97 pre.src-J:before { content: 'J'; }
98 pre.src-makefile:before { content: 'Makefile'; }
99 pre.src-maxima:before { content: 'Maxima'; }
100 pre.src-perl:before { content: 'Perl'; }
101 pre.src-picolisp:before { content: 'Pico Lisp'; }
102 pre.src-scala:before { content: 'Scala'; }
103 pre.src-shell:before { content: 'Shell Script'; }
104 pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
105 /* additional language identifiers per "defun org-babel-execute"
106 in ob-*.el */
107 pre.src-cpp:before { content: 'C++'; }
108 pre.src-abc:before { content: 'ABC'; }
109 pre.src-coq:before { content: 'Coq'; }
110 pre.src-groovy:before { content: 'Groovy'; }
111 /* additional language identifiers from org-babel-shell-names in
112 ob-shell.el: ob-shell is the only babel language using a lambda to put
113 the execution function name together. */
114 pre.src-bash:before { content: 'bash'; }
115 pre.src-csh:before { content: 'csh'; }
116 pre.src-ash:before { content: 'ash'; }
117 pre.src-dash:before { content: 'dash'; }
118 pre.src-ksh:before { content: 'ksh'; }
119 pre.src-mksh:before { content: 'mksh'; }
120 pre.src-posh:before { content: 'posh'; }
121 /* Additional Emacs modes also supported by the LaTeX listings package */
122 pre.src-ada:before { content: 'Ada'; }
123 pre.src-asm:before { content: 'Assembler'; }
124 pre.src-caml:before { content: 'Caml'; }
125 pre.src-delphi:before { content: 'Delphi'; }
126 pre.src-html:before { content: 'HTML'; }
127 pre.src-idl:before { content: 'IDL'; }
128 pre.src-mercury:before { content: 'Mercury'; }
129 pre.src-metapost:before { content: 'MetaPost'; }
130 pre.src-modula-2:before { content: 'Modula-2'; }
131 pre.src-pascal:before { content: 'Pascal'; }
132 pre.src-ps:before { content: 'PostScript'; }
133 pre.src-prolog:before { content: 'Prolog'; }
134 pre.src-simula:before { content: 'Simula'; }
135 pre.src-tcl:before { content: 'tcl'; }
136 pre.src-tex:before { content: 'TeX'; }
137 pre.src-plain-tex:before { content: 'Plain TeX'; }
138 pre.src-verilog:before { content: 'Verilog'; }
139 pre.src-vhdl:before { content: 'VHDL'; }
140 pre.src-xml:before { content: 'XML'; }
141 pre.src-nxml:before { content: 'XML'; }
142 /* add a generic configuration mode; LaTeX export needs an additional
143 (add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
144 pre.src-conf:before { content: 'Configuration File'; }
146 table { border-collapse:collapse; }
147 caption.t-above { caption-side: top; }
148 caption.t-bottom { caption-side: bottom; }
149 td, th { vertical-align:top; }
150 th.org-right { text-align: center; }
151 th.org-left { text-align: center; }
152 th.org-center { text-align: center; }
153 td.org-right { text-align: right; }
154 td.org-left { text-align: left; }
155 td.org-center { text-align: center; }
156 dt { font-weight: bold; }
157 .footpara { display: inline; }
158 .footdef { margin-bottom: 1em; }
159 .figure { padding: 1em; }
160 .figure p { text-align: center; }
161 .inlinetask {
162 padding: 10px;
163 border: 2px solid gray;
164 margin: 10px;
165 background: #ffffcc;
167 #org-div-home-and-up
168 { text-align: right; font-size: 70%; white-space: nowrap; }
169 textarea { overflow-x: auto; }
170 .linenr { font-size: smaller }
171 .code-highlighted { background-color: #ffff00; }
172 .org-info-js_info-navigation { border-style: none; }
173 #org-info-js_console-label
174 { font-size: 10px; font-weight: bold; white-space: nowrap; }
175 .org-info-js_search-highlight
176 { background-color: #ffff00; color: #000000; font-weight: bold; }
177 .org-svg { width: 90%; }
178 /*]]>*/-->
179 </style>
180 <link rel="stylesheet" type="text/css" href="style.css" />
181 <style>pre.src{background:#343131;color:white;} </style>
182 <script type="text/javascript">
184 @licstart The following is the entire license notice for the
185 JavaScript code in this tag.
187 Copyright (C) 2012-2017 Free Software Foundation, Inc.
189 The JavaScript code in this tag is free software: you can
190 redistribute it and/or modify it under the terms of the GNU
191 General Public License (GNU GPL) as published by the Free Software
192 Foundation, either version 3 of the License, or (at your option)
193 any later version. The code is distributed WITHOUT ANY WARRANTY;
194 without even the implied warranty of MERCHANTABILITY or FITNESS
195 FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
197 As additional permission under GNU GPL version 3 section 7, you
198 may distribute non-source (e.g., minimized or compacted) forms of
199 that code without the copy of the GNU GPL normally required by
200 section 4, provided you include this license notice and a URL
201 through which recipients can access the Corresponding Source.
204 @licend The above is the entire license notice
205 for the JavaScript code in this tag.
207 <!--/*--><![CDATA[/*><!--*/
208 function CodeHighlightOn(elem, id)
210 var target = document.getElementById(id);
211 if(null != target) {
212 elem.cacheClassElem = elem.className;
213 elem.cacheClassTarget = target.className;
214 target.className = "code-highlighted";
215 elem.className = "code-highlighted";
218 function CodeHighlightOff(elem, id)
220 var target = document.getElementById(id);
221 if(elem.cacheClassElem)
222 elem.className = elem.cacheClassElem;
223 if(elem.cacheClassTarget)
224 target.className = elem.cacheClassTarget;
226 /*]]>*///-->
227 </script>
228 </head>
229 <body>
230 <div id="content">
231 <header>
232 <h1 class="title">Simple-Date</h1>
233 </header><nav id="table-of-contents">
234 <h2>Table of Contents</h2>
235 <div id="text-table-of-contents">
236 <ul>
237 <li><a href="#orgc96db35">Date type</a>
238 <ul>
239 <li><a href="#org4757ac7">class date</a></li>
240 <li><a href="#orgbecb912">function encode-date (year month day)</a></li>
241 <li><a href="#org17bca57">function decode-date (date)</a></li>
242 <li><a href="#org9596f23">function day-of-week (date)</a></li>
243 <li><a href="#org351e3fc">Timestamp type</a></li>
244 <li><a href="#org9b35463">function encode-timestamp (year month day &amp;optional (hour 0) (minute 0) (second 0) (millisecond 0))</a></li>
245 <li><a href="#org88dc827">function decode-timestamp (timestamp)</a></li>
246 <li><a href="#org00b9c9c">function timestamp-to-universal-time (timestamp)</a></li>
247 <li><a href="#orgf3fb124">function universal-time-to-timestamp (universal-time)</a></li>
248 <li><a href="#org9841ce8">Interval type</a></li>
249 <li><a href="#orgae89286">function encode-interval (&amp;key (year 0) (month 0) (week 0) (day 0) (hour 0) (minute 0) (second 0) (millisecond 0))</a></li>
250 <li><a href="#org491ae2f">function decode-interval (interval)</a></li>
251 </ul>
252 </li>
253 <li><a href="#orge311352">Operations</a>
254 <ul>
255 <li><a href="#orgff3d514">method time-add (a b)</a></li>
256 <li><a href="#org6815ed9">method time-subtract (a b)</a></li>
257 <li><a href="#orgd7aaac8">method time= (a b)</a></li>
258 <li><a href="#orge502f5e">method time&lt; (a b)</a></li>
259 <li><a href="#org7fb03e5">method time&gt; (a b)</a></li>
260 <li><a href="#orgdc2b19c">function time&lt;= (a b)</a></li>
261 <li><a href="#org7dd8012">function time&gt;= (a b)</a></li>
262 </ul>
263 </li>
264 </ul>
265 </div>
266 </nav>
268 Simple-date provides types (CLOS classes) for dates, timestamps, and intervals
269 similar to the ones SQL databases use, in order to be able to store and read
270 these to and from a database in a straighforward way. A few obvious operations
271 are defined on these types.
272 </p>
275 To use this library with cl-postgres or postmodern and get the simple-date reader
276 to be loaded, you need to load simple-date/postgres-glue
277 and then set the readtable. This will register suitable SQL
278 readers and writers for the associated database types.
279 </p>
281 <div class="org-src-container">
282 <pre class="src src-lisp">(ql:quickload <span style="color: #98fb98; font-weight: bold;">:simple-date/postgres-glue</span>)
284 (setf cl-postgres:*sql-readtable*
285 (cl-postgres:copy-sql-readtable
286 simple-date-cl-postgres-glue:*simple-date-sql-readtable*))
287 </pre>
288 </div>
291 The most glaring defect of this library is its ignorance of time zones. It
292 pretends the whole world lives in UTC. Use with care.
293 </p>
296 To get back to the default cl-postgres reader:
297 </p>
298 <div class="org-src-container">
299 <pre class="src src-lisp">(setf cl-postgres:*sql-readtable*
300 (cl-postgres:copy-sql-readtable
301 cl-postgres::*default-sql-readtable*))
302 </pre>
303 </div>
306 To use the simple-date reader when cl-postgres is using the default:
307 </p>
308 <div class="org-src-container">
309 <pre class="src src-lisp">(setf cl-postgres:*sql-readtable*
310 (cl-postgres:copy-sql-readtable
311 simple-date-cl-postgres-glue:*simple-date-sql-readtable*))
312 </pre>
313 </div>
316 As a reminder for those who want to use local-time, to enable the local-time
317 reader:
318 </p>
319 <div class="org-src-container">
320 <pre class="src src-lisp">(local-time:set-local-time-cl-postgres-readers)
321 </pre>
322 </div>
325 <div id="outline-container-orgc96db35" class="outline-2">
326 <h2 id="orgc96db35"><a id="ID-6cefa703-d55b-464d-bad9-7c7ceae0c90d"></a>Date type</h2>
327 <div class="outline-text-2" id="text-orgc96db35">
328 </div>
329 <div id="outline-container-org4757ac7" class="outline-3">
330 <h3 id="org4757ac7"><a id="ID-203d5d98-5ce7-4bcb-81d9-1aeb4fe2796d"></a>class date</h3>
331 <div class="outline-text-3" id="text-org4757ac7">
333 Represents a date, with no time-of-day information.
334 </p>
335 </div>
336 </div>
338 <div id="outline-container-orgbecb912" class="outline-3">
339 <h3 id="orgbecb912"><a id="ID-dbf2a874-80e1-4a43-86be-7febb1573b8d"></a>function encode-date (year month day)</h3>
340 <div class="outline-text-3" id="text-orgbecb912">
342 → date
343 </p>
346 Creates a date object.
347 </p>
348 </div>
349 </div>
351 <div id="outline-container-org17bca57" class="outline-3">
352 <h3 id="org17bca57"><a id="ID-35da4a62-ea64-4053-aa30-4496d56a0f95"></a>function decode-date (date)</h3>
353 <div class="outline-text-3" id="text-org17bca57">
355 → (values year month day)
356 </p>
359 Extract the elements from a date object.
360 </p>
361 </div>
362 </div>
364 <div id="outline-container-org9596f23" class="outline-3">
365 <h3 id="org9596f23"><a id="ID-b1590639-fd02-458d-86e4-6e1bd3c1c003"></a>function day-of-week (date)</h3>
366 <div class="outline-text-3" id="text-org9596f23">
368 → integer
369 </p>
372 Determine the day of the week that the given date falls on. Value ranges from
373 0 to 6, with 0 being Sunday and 6 being Saturday.
374 </p>
375 </div>
376 </div>
378 <div id="outline-container-org351e3fc" class="outline-3">
379 <h3 id="org351e3fc"><a id="ID-6efdaace-0c1c-45ba-8376-9b91e18a0b38"></a>Timestamp type</h3>
380 <div class="outline-text-3" id="text-org351e3fc">
382 class timestamp
383 </p>
386 Represents an absolute timestamp, with a millisecond precision.
387 </p>
388 </div>
389 </div>
391 <div id="outline-container-org9b35463" class="outline-3">
392 <h3 id="org9b35463"><a id="ID-f6817a2a-92e2-44aa-9060-d9ab459f6207"></a>function encode-timestamp (year month day &amp;optional (hour 0) (minute 0) (second 0) (millisecond 0))</h3>
393 <div class="outline-text-3" id="text-org9b35463">
395 → timestamp
396 </p>
399 Create a timestamp. No negative values or values outside of an arguments normal
400 range (i.e. 60 for minutes, 1000 for milliseconds) should be passed.
401 </p>
402 </div>
403 </div>
405 <div id="outline-container-org88dc827" class="outline-3">
406 <h3 id="org88dc827"><a id="ID-5cb5f677-4fc4-4ab3-b2af-65579e660baf"></a>function decode-timestamp (timestamp)</h3>
407 <div class="outline-text-3" id="text-org88dc827">
409 → (values year month day hour minute second millisecond)
410 </p>
413 Decode a timestamp into its components.
414 </p>
415 </div>
416 </div>
418 <div id="outline-container-org00b9c9c" class="outline-3">
419 <h3 id="org00b9c9c"><a id="ID-477dd9e6-3e72-4eaa-b1fd-cf5d06bdfd1b"></a>function timestamp-to-universal-time (timestamp)</h3>
420 <div class="outline-text-3" id="text-org00b9c9c">
422 → universal-time
423 </p>
426 Convert a timestamp to the corresponding universal-time, rounding to seconds.
427 Note that this will treat the timestamp as if it were in UTC.
428 </p>
429 </div>
430 </div>
432 <div id="outline-container-orgf3fb124" class="outline-3">
433 <h3 id="orgf3fb124"><a id="ID-ba44156f-a860-4601-a5fe-6465d6ad8353"></a>function universal-time-to-timestamp (universal-time)</h3>
434 <div class="outline-text-3" id="text-orgf3fb124">
436 → timestamp
437 </p>
440 Create a timestamp from a universal time. Again, the resulting timestamp should
441 be treated as if it were in UTC.
442 </p>
443 </div>
444 </div>
446 <div id="outline-container-org9841ce8" class="outline-3">
447 <h3 id="org9841ce8"><a id="ID-316f3287-fd76-46ce-8c2b-c07ad381fc38"></a>Interval type</h3>
448 <div class="outline-text-3" id="text-org9841ce8">
450 class interval
451 </p>
454 An interval represents a period of time. It contains both an absolute part in
455 milliseconds (days, weeks, minutes, etc are always the same length), and a
456 relative part for months and years ― the amount of time that a month or year
457 represents is not always the same.
458 </p>
459 </div>
460 </div>
462 <div id="outline-container-orgae89286" class="outline-3">
463 <h3 id="orgae89286"><a id="ID-77212a01-b23f-40c7-aeec-fc93d4834f53"></a>function encode-interval (&amp;key (year 0) (month 0) (week 0) (day 0) (hour 0) (minute 0) (second 0) (millisecond 0))</h3>
464 <div class="outline-text-3" id="text-orgae89286">
466 → interval
467 </p>
470 Create an interval. Arguments may be negative and of any size.
471 </p>
472 </div>
473 </div>
475 <div id="outline-container-org491ae2f" class="outline-3">
476 <h3 id="org491ae2f"><a id="ID-cfd906be-cc00-437e-b250-b7d294131aa0"></a>function decode-interval (interval)</h3>
477 <div class="outline-text-3" id="text-org491ae2f">
479 → (values year month day hour minute second millisecond)
480 </p>
483 Decompose an interval into parts. Note that these may be different from the
484 parameters that created it ― an interval of 3600 seconds is the same as one
485 of 1 hour.
486 </p>
487 </div>
488 </div>
489 </div>
491 <div id="outline-container-orge311352" class="outline-2">
492 <h2 id="orge311352"><a id="ID-d2616cd8-622b-464f-994e-e1f9d6309706"></a>Operations</h2>
493 <div class="outline-text-2" id="text-orge311352">
495 To prevent a proliferation of different function names, generic functions
496 are used for operations on time values. The semantics of these differ for
497 the type of the operands.
498 </p>
499 </div>
501 <div id="outline-container-orgff3d514" class="outline-3">
502 <h3 id="orgff3d514"><a id="ID-6846ba8b-a59f-475e-bc25-0c18e4fa5548"></a>method time-add (a b)</h3>
503 <div class="outline-text-3" id="text-orgff3d514">
505 → value
506 </p>
509 Adds two time-related objects. Adding an interval to a date or timestamp
510 will return a new date or timestamp, increased by the value of the interval.
511 Adding two intervals returns a new interval with the sum of the two
512 arguments. Integers can be used in place of intervals, and will be
513 interpreted as an amount of milliseconds.
514 </p>
515 </div>
516 </div>
518 <div id="outline-container-org6815ed9" class="outline-3">
519 <h3 id="org6815ed9"><a id="ID-98dee89f-7178-4487-8d85-3036149f2def"></a>method time-subtract (a b)</h3>
520 <div class="outline-text-3" id="text-org6815ed9">
522 → value
523 </p>
526 Subtracts time-related objects from each other. Subtracting two dates or
527 timestamps results in an interval that represents the difference between
528 them. Similarly, subtracting two intervals also gives their difference.
529 </p>
530 </div>
531 </div>
533 <div id="outline-container-orgd7aaac8" class="outline-3">
534 <h3 id="orgd7aaac8"><a id="ID-74acb8a0-5438-4a56-8d08-3316a7792108"></a>method time= (a b)</h3>
535 <div class="outline-text-3" id="text-orgd7aaac8">
537 → boolean
538 </p>
541 Compare two time-related values, returns a boolean indicating whether
542 they denote the same time or period.
543 </p>
544 </div>
545 </div>
547 <div id="outline-container-orge502f5e" class="outline-3">
548 <h3 id="orge502f5e"><a id="ID-02b06b96-bbd7-482a-aa3c-f9080f97c3fa"></a>method time&lt; (a b)</h3>
549 <div class="outline-text-3" id="text-orge502f5e">
551 → boolean
552 </p>
555 Compare two time-related values, returns a boolean indicating whether the
556 first is less than the second.
557 </p>
558 </div>
559 </div>
561 <div id="outline-container-org7fb03e5" class="outline-3">
562 <h3 id="org7fb03e5"><a id="ID-6901c062-4b1c-4cb1-a9f6-6935141d5fdd"></a>method time&gt; (a b)</h3>
563 <div class="outline-text-3" id="text-org7fb03e5">
565 → boolean
566 </p>
569 Compare two time-related values, returns a boolean indicating whether the
570 first is greater than the second.
571 </p>
572 </div>
573 </div>
575 <div id="outline-container-orgdc2b19c" class="outline-3">
576 <h3 id="orgdc2b19c"><a id="ID-450e4d9e-2f31-4278-817a-bb42eaf0ea04"></a>function time&lt;= (a b)</h3>
577 <div class="outline-text-3" id="text-orgdc2b19c">
579 → boolean
580 </p>
583 The inverse of time&gt;.
584 </p>
585 </div>
586 </div>
588 <div id="outline-container-org7dd8012" class="outline-3">
589 <h3 id="org7dd8012"><a id="ID-d77174da-9511-41c6-bc46-95d62842435c"></a>function time&gt;= (a b)</h3>
590 <div class="outline-text-3" id="text-org7dd8012">
592 → boolean
593 </p>
596 The inverse of time&lt;.
597 </p>
598 </div>
599 </div>
600 </div>
601 </div>
602 </body>
603 </html>