doc/simple-date.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3
   4   <head>
   5     <title>Simple-date reference manual</title>
   6     <link rel="stylesheet" type="text/css" href="style.css"/>
   7     <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
   8   </head>
   9
  10   <body>
  11
  12     <h1>Simple-date reference manual</h1>
  13
  14     <p>Simple-date provides types (CLOS classes) for dates,
  15     timestamps, and intervals similar to the ones SQL databases use,
  16     in order to be able to store and read these to and from a database
  17     in a straighforward way. A few obvious operations are defined on
  18     these types.</p>
  19
  20     <p>The most glaring defect of this library is its ignorance of
  21     time zones. It pretends the whole world lives in UTC. <em>Use with
  22     care.</em></p>
  23
  24     <p>When this libary is loaded after <a
  25     href="cl-postgres.html">CL-postgres</a>, it will register suitable
  26     SQL readers and writers for the associated database types.</p>
  27
  28     <h2>Contents</h2>
  29
  30     <ol>
  31       <li><a href="#date">Date type</a></li>
  32       <li><a href="#timestamp">Timestamp type</a></li>
  33       <li><a href="#interval">Interval type</a></li>
  34       <li><a href="#operations">Operations</a></li>
  35       <li><a href="#index">Symbol-index</a></li>
  36     </ol>
  37
  38     <h2><a name="date"></a>Date type</h2>
  39
  40     <p class="def">
  41       <span>class</span>
  42       date
  43     </p>
  44
  45     <p class="desc">Represents a date, with no time-of-day information.</p>
  46
  47     <p class="def">
  48       <span>function</span>
  49       <a name="encode-date"></a>
  50       encode-date (year month day)
  51       <br/>&#8594; date
  52     </p>
  53
  54     <p class="desc">Creates a date object.</p>
  55
  56     <p class="def">
  57       <span>function</span>
  58       <a name="decode-date"></a>
  59       decode-date (date)
  60       <br/>&#8594; (values year month day)
  61     </p>
  62
  63     <p class="desc">Extract the elements from a date object.</p>
  64
  65     <p class="def">
  66       <span>function</span>
  67       <a name="day-of-week"></a>
  68       day-of-week (date)
  69       <br/>&#8594; integer
  70     </p>
  71
  72     <p class="desc">Determine the day of the week that the given date
  73     falls on. Value ranges from 0 to 6, with 0 being Sunday and 6
  74     being Saturday.</p>
  75
  76     <h2><a name="timestamp"></a>Timestamp type</h2>
  77
  78     <p class="def">
  79       <span>class</span>
  80       timestamp
  81     </p>
  82
  83     <p class="desc">Represents an absolute timestamp, with a
  84     millisecond precision.</p>
  85
  86     <p class="def">
  87       <span>function</span>
  88       <a name="encode-timestamp"></a>
  89       encode-timestamp (year month day &amp;optional (hour 0) (minute 0) (second 0) (millisecond 0))
  90       <br/>&#8594; timestamp
  91     </p>
  92
  93     <p class="desc">Create a timestamp. No negative values or values
  94     outside of an arguments normal range (i.e. 60 for minutes, 1000
  95     for milliseconds) should be passed.</p>
  96
  97     <p class="def">
  98       <span>function</span>
  99       <a name="decode-timestamp"></a>
 100       decode-timestamp (timestamp)
 101       <br/>&#8594; (values year month day hour minute second millisecond)
 102     </p>
 103
 104     <p class="desc">Decode a timestamp into its components.</p>
 105
 106     <p class="def">
 107       <span>function</span>
 108       <a name="timestamp-to-universal-time"></a>
 109       timestamp-to-universal-time (timestamp)
 110       <br/>&#8594; universal-time
 111     </p>
 112
 113     <p class="desc">Convert a timestamp to the corresponding
 114     universal-time, rounding to seconds. Note that this will treat the
 115     timestamp as if it were in UTC.</p>
 116
 117     <p class="def">
 118       <span>function</span>
 119       <a name="universal-time-to-timestamp"></a>
 120       universal-time-to-timestamp (universal-time)
 121       <br/>&#8594; timestamp
 122     </p>
 123
 124     <p class="desc">Create a timestamp from a universal time. Again,
 125     the resulting timestamp should be treated as if it were in
 126     UTC.</p>
 127
 128     <h2><a name="interval"></a>Interval type</h2>
 129
 130     <p class="def">
 131       <span>class</span>
 132       interval
 133     </p>
 134
 135     <p class="desc">An interval represents a period of time. It
 136     contains both an absolute part in milliseconds (days, weeks,
 137     minutes, etc are always the same length), and a relative part for
 138     months and years &#x2015; the amount of time that a month or year
 139     represents is not always the same.</p>
 140
 141     <p class="def">
 142       <span>function</span>
 143       <a name="encode-interval"></a>
 144       encode-interval (&amp;key (year 0) (month 0) (week 0) (day 0) (hour 0) (minute 0) (second 0) (millisecond 0))
 145       <br/>&#8594; interval
 146     </p>
 147
 148     <p class="desc">Create an interval. Arguments may be negative and
 149     of any size.</p>
 150
 151     <p class="def">
 152       <span>function</span>
 153       <a name="decode-interval"></a>
 154       decode-interval (interval)
 155       <br/>&#8594; (values year month day hour minute second millisecond)
 156     </p>
 157
 158     <p class="desc">Decompose an interval into parts. Note that these
 159     may be different from the parameters that created it &#x2015; an
 160     interval of 3600 seconds is the same as one of 1 hour.</p>
 161
 162     <h2><a name="operations"></a>Operations</h2>
 163
 164     <p>To prevent a proliferation of different function names, generic
 165     functions are used for operations on time values. The semantics of
 166     these differ for the type of the operands.</p>
 167
 168     <p class="def">
 169       <span>method</span>
 170       <a name="time-add"></a>
 171       time-add (a b)
 172       <br/>&#8594; value
 173     </p>
 174
 175     <p class="desc">Adds two time-related objects. Adding an interval
 176     to a date or timestamp will return a new date or timestamp,
 177     increased by the value of the interval. Adding two intervals
 178     returns a new interval with the sum of the two arguments. Integers
 179     can be used in place of intervals, and will be interpreted as an
 180     amount of milliseconds.</p>
 181
 182     <p class="def">
 183       <span>method</span>
 184       <a name="time-subtract"></a>
 185       time-subtract (a b)
 186       <br/>&#8594; value
 187     </p>
 188
 189     <p class="desc">Subtracts time-related objects from each other.
 190     Subtracting two dates or timestamps results in an interval that
 191     represents the difference between them. Similarly, subtracting two
 192     intervals also gives their difference.</p>
 193
 194     <p class="def">
 195       <span>method</span>
 196       <a name="time="></a>
 197       time= (a b)
 198       <br/>&#8594; boolean
 199     </p>
 200
 201     <p class="desc">Compare two time-related values, returns a boolean
 202     indicating whether they denote the same time or period.</p>
 203
 204     <p class="def">
 205       <span>method</span>
 206       <a name="time&lt;"></a>
 207       time&lt; (a b)
 208       <br/>&#8594; boolean
 209     </p>
 210
 211     <p class="desc">Compare two time-related values, returns a boolean
 212     indicating whether the first is less than the second.</p>
 213
 214     <p class="def">
 215       <span>method</span>
 216       <a name="time&gt;"></a>
 217       time&gt; (a b)
 218       <br/>&#8594; boolean
 219     </p>
 220
 221     <p class="desc">Compare two time-related values, returns a boolean
 222     indicating whether the first is greater than the second.</p>
 223
 224     <p class="def">
 225       <span>function</span>
 226       <a name="time&lt;="></a>
 227       time&lt;= (a b)
 228       <br/>&#8594; boolean
 229     </p>
 230
 231     <p class="desc">The inverse of <a
 232     href="#time&gt;"><code>time&gt;</code></a>.</p>
 233
 234     <p class="def">
 235       <span>function</span>
 236       <a name="time&gt;="></a>
 237       time&gt;= (a b)
 238       <br/>&#8594; boolean
 239     </p>
 240
 241     <p class="desc">The inverse of <a
 242     href="#time&lt;"><code>time&lt;</code></a>.</p>
 243
 244     <h2><a name="index"></a>Symbol-index</h2>
 245
 246     <ul class="symbol-index">
 247       <li><a href="#date">date</a></li>
 248       <li><a href="#day-of-week">day-of-week</a></li>
 249       <li><a href="#decode-date">decode-date</a></li>
 250       <li><a href="#decode-interval">decode-interval</a></li>
 251       <li><a href="#decode-timestamp">decode-timestamp</a></li>
 252       <li><a href="#encode-date">encode-date</a></li>
 253       <li><a href="#encode-interval">encode-interval</a></li>
 254       <li><a href="#encode-timestamp">encode-timestamp</a></li>
 255       <li><a href="#interval">interval</a></li>
 256       <li><a href="#time&gt;">time&gt;</a></li>
 257       <li><a href="#time&lt;">time&lt;</a></li>
 258       <li><a href="#time&lt;=">time&gt;=</a></li>
 259       <li><a href="#time&lt;=">time&lt;=</a></li>
 260       <li><a href="#time-add">time-add</a></li>
 261       <li><a href="#time-subtract">time-subtract</a></li>
 262       <li><a href="#time=">time=</a></li>
 263       <li><a href="#timestamp">timestamp</a></li>
 264       <li><a href="#timestamp-to-universal-time">timestamp-to-universal-time</a></li>
 265       <li><a href="#universal-time-to-timestamp">universal-time-to-timestamp</a></li>
 266     </ul>
 267
 268   </body>
 269
 270 </html>