Permalink
Switch branches/tags
Find file
Fetching contributors…
Cannot retrieve contributors at this time
271 lines (215 sloc) 8.37 KB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Simple-date reference manual</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
</head>
<body>
<h1>Simple-date reference manual</h1>
<p>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.</p>
<p>The most glaring defect of this library is its ignorance of
time zones. It pretends the whole world lives in UTC. <em>Use with
care.</em></p>
<p>When this libary is loaded after <a
href="cl-postgres.html">CL-postgres</a>, it will register suitable
SQL readers and writers for the associated database types.</p>
<h2>Contents</h2>
<ol>
<li><a href="#date">Date type</a></li>
<li><a href="#timestamp">Timestamp type</a></li>
<li><a href="#interval">Interval type</a></li>
<li><a href="#operations">Operations</a></li>
<li><a href="#index">Symbol-index</a></li>
</ol>
<h2><a name="date"></a>Date type</h2>
<p class="def">
<span>class</span>
date
</p>
<p class="desc">Represents a date, with no time-of-day information.</p>
<p class="def">
<span>function</span>
<a name="encode-date"></a>
encode-date (year month day)
<br/>&#8594; date
</p>
<p class="desc">Creates a date object.</p>
<p class="def">
<span>function</span>
<a name="decode-date"></a>
decode-date (date)
<br/>&#8594; (values year month day)
</p>
<p class="desc">Extract the elements from a date object.</p>
<p class="def">
<span>function</span>
<a name="day-of-week"></a>
day-of-week (date)
<br/>&#8594; integer
</p>
<p class="desc">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.</p>
<h2><a name="timestamp"></a>Timestamp type</h2>
<p class="def">
<span>class</span>
timestamp
</p>
<p class="desc">Represents an absolute timestamp, with a
millisecond precision.</p>
<p class="def">
<span>function</span>
<a name="encode-timestamp"></a>
encode-timestamp (year month day &amp;optional (hour 0) (minute 0) (second 0) (millisecond 0))
<br/>&#8594; timestamp
</p>
<p class="desc">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.</p>
<p class="def">
<span>function</span>
<a name="decode-timestamp"></a>
decode-timestamp (timestamp)
<br/>&#8594; (values year month day hour minute second millisecond)
</p>
<p class="desc">Decode a timestamp into its components.</p>
<p class="def">
<span>function</span>
<a name="timestamp-to-universal-time"></a>
timestamp-to-universal-time (timestamp)
<br/>&#8594; universal-time
</p>
<p class="desc">Convert a timestamp to the corresponding
universal-time, rounding to seconds. Note that this will treat the
timestamp as if it were in UTC.</p>
<p class="def">
<span>function</span>
<a name="universal-time-to-timestamp"></a>
universal-time-to-timestamp (universal-time)
<br/>&#8594; timestamp
</p>
<p class="desc">Create a timestamp from a universal time. Again,
the resulting timestamp should be treated as if it were in
UTC.</p>
<h2><a name="interval"></a>Interval type</h2>
<p class="def">
<span>class</span>
interval
</p>
<p class="desc">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 &#x2015; the amount of time that a month or year
represents is not always the same.</p>
<p class="def">
<span>function</span>
<a name="encode-interval"></a>
encode-interval (&amp;key (year 0) (month 0) (week 0) (day 0) (hour 0) (minute 0) (second 0) (millisecond 0))
<br/>&#8594; interval
</p>
<p class="desc">Create an interval. Arguments may be negative and
of any size.</p>
<p class="def">
<span>function</span>
<a name="decode-interval"></a>
decode-interval (interval)
<br/>&#8594; (values year month day hour minute second millisecond)
</p>
<p class="desc">Decompose an interval into parts. Note that these
may be different from the parameters that created it &#x2015; an
interval of 3600 seconds is the same as one of 1 hour.</p>
<h2><a name="operations"></a>Operations</h2>
<p>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.</p>
<p class="def">
<span>method</span>
<a name="time-add"></a>
time-add (a b)
<br/>&#8594; value
</p>
<p class="desc">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.</p>
<p class="def">
<span>method</span>
<a name="time-subtract"></a>
time-subtract (a b)
<br/>&#8594; value
</p>
<p class="desc">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.</p>
<p class="def">
<span>method</span>
<a name="time="></a>
time= (a b)
<br/>&#8594; boolean
</p>
<p class="desc">Compare two time-related values, returns a boolean
indicating whether they denote the same time or period.</p>
<p class="def">
<span>method</span>
<a name="time&lt;"></a>
time&lt; (a b)
<br/>&#8594; boolean
</p>
<p class="desc">Compare two time-related values, returns a boolean
indicating whether the first is less than the second.</p>
<p class="def">
<span>method</span>
<a name="time&gt;"></a>
time&gt; (a b)
<br/>&#8594; boolean
</p>
<p class="desc">Compare two time-related values, returns a boolean
indicating whether the first is greater than the second.</p>
<p class="def">
<span>function</span>
<a name="time&lt;="></a>
time&lt;= (a b)
<br/>&#8594; boolean
</p>
<p class="desc">The inverse of <a
href="#time&gt;"><code>time&gt;</code></a>.</p>
<p class="def">
<span>function</span>
<a name="time&gt;="></a>
time&gt;= (a b)
<br/>&#8594; boolean
</p>
<p class="desc">The inverse of <a
href="#time&lt;"><code>time&lt;</code></a>.</p>
<h2><a name="index"></a>Symbol-index</h2>
<ul class="symbol-index">
<li><a href="#date">date</a></li>
<li><a href="#day-of-week">day-of-week</a></li>
<li><a href="#decode-date">decode-date</a></li>
<li><a href="#decode-interval">decode-interval</a></li>
<li><a href="#decode-timestamp">decode-timestamp</a></li>
<li><a href="#encode-date">encode-date</a></li>
<li><a href="#encode-interval">encode-interval</a></li>
<li><a href="#encode-timestamp">encode-timestamp</a></li>
<li><a href="#interval">interval</a></li>
<li><a href="#time&gt;">time&gt;</a></li>
<li><a href="#time&lt;">time&lt;</a></li>
<li><a href="#time&lt;=">time&gt;=</a></li>
<li><a href="#time&lt;=">time&lt;=</a></li>
<li><a href="#time-add">time-add</a></li>
<li><a href="#time-subtract">time-subtract</a></li>
<li><a href="#time=">time=</a></li>
<li><a href="#timestamp">timestamp</a></li>
<li><a href="#timestamp-to-universal-time">timestamp-to-universal-time</a></li>
<li><a href="#universal-time-to-timestamp">universal-time-to-timestamp</a></li>
</ul>
</body>
</html>