source: project/release/3/srfi-19/trunk/srfi-19.html @ 13907

Last change on this file since 13907 was 13907, checked in by Kon Lovett, 11 years ago

Release.

File size: 30.6 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<!-- Generated by eggdoc Revision: 1.20  -->
3<html>
4<head>
5<title>Eggs Unlimited - srfi-19</title><style type="text/css"> <!--
6      CODE {
7            color: #666666;
8          }
9/*   DT.definition EM { font-weight: bold; font-style: normal; } */
10
11     DT.definition { 
12                   background: #eee;
13                   color: black;
14                   padding: 0.2em 1em 0.2em 0.7em;
15                   margin-left: 0.2em;
16border: 1px solid #bbc;
17                   font-family: "Andale Mono", monospace;
18                   /* font-size: 1.2em; */
19                   
20                 }
21     DD {
22                   margin-top: 0.8em;
23                   margin-bottom: 0.8em;
24     }
25     DIV.subsection {
26                    border-top: 1px solid #448;
27                    padding-left: 1em;
28                    margin-bottom: 1.2em;
29     }
30     DIV.subsubsection {
31                    border-top: 1px dotted #99c;
32                    /* border-left: 1px solid #99c; */
33                    padding-left: 1em;
34                    margin-bottom: 1.2em;
35     }
36     DIV.subsubsubsection {
37                    border-top: 1px solid #ddf;
38                    padding-left: 1em;
39                    margin-bottom: 1.2em;
40     }
41
42         DIV.section {
43                 margin-bottom: 1.5em;
44         }
45         a:link {
46                 color: #336;
47         }
48         a:visited { color: #666; }
49         a:active  { color: #966; }
50         a:hover   { color: #669; }
51         body { margin: 0; padding: 0; background: #fff; color: #000; font: 9pt "Lucida Grande", "Verdana", sans-serif; }
52         H2 {
53                 background: #336;
54                 color: #fff;
55                 padding-top: 0.5em;
56                 padding-bottom: 0.5em;
57                 padding-left: 16px;
58                 margin: 0 0 1em 0;
59        }
60        UL LI {
61                list-style: none;
62        }
63        TT {
64                font-family: "Andale Mono", monospace;
65                /* font-size: 1.2em; */
66        }
67        H3 {
68                color: #113;
69                margin-bottom: 0.5em;
70        }
71        H4, H5, H6 {
72                color: #113;
73                margin-bottom: 1.0em;
74        }
75        H5 {
76                font-weight: normal;
77                font-style: italic;
78                font-size: 100%;
79                margin-top: 1.2em;
80        }
81        H6 {
82                font-weight: bold;
83                font-size: 85%;
84                margin-top: 1.2em;
85        }
86     DIV#eggheader {
87         text-align: center;
88                 float: right;
89                 margin-right: 2em;
90     }
91     DIV#header IMG {
92            /* display: block; margin-left: auto; margin-right: auto;  */
93            /* float: right; */
94            border: none;  /* firefox */
95     }
96     DIV#footer {
97                background: #bbd;
98                padding: 0.7em ;
99                border-top: 1px solid #cce;
100     }
101     DIV#footer hr {
102                display: none;
103     }
104     DIV#footer a {
105                float: left;
106     }
107     DIV#revision-history {
108         float: right;
109     }
110     
111     DIV#body {
112                 margin: 1em 1em 1em 16px;
113         }
114
115     DIV#examples PRE {
116       background: #eef;
117       padding: 0.1em;
118       border: 1px solid #aac;
119     }
120     PRE#license, DIV#examples PRE {
121       padding: 0.5em;
122     }
123     DIV#examples PRE {
124       /* font-size: 85%; */
125     }
126     PRE { font-family: "Andale Mono", monospace; }
127     TABLE {
128       background: #eef;
129       padding: 0.2em;
130       border: 1px solid #aac;
131       border-collapse: collapse;
132       width: 100%;
133     }
134     TABLE.symbol-table TD.symbol {
135          width: 15em;
136          font-family: "Andale Mono", monospace;
137          /* font-size: 1.2em; */
138     }
139     TH {
140       text-align: left;
141       border-bottom: 1px solid #aac;
142       padding: 0.25em 0.5em 0.25em 0.5em;
143     } 
144     TD { padding: 0.25em 0.5em 0.25em 0.5em; }
145     --></style></head>
146<body>
147<div id="header">
148<h2>srfi-19</h2>
149<div id="eggheader"><a href="index.html">
150<img src="egg.jpg" alt="[Picture of an egg]" /></a></div></div>
151<div id="body">
152<div class="section">
153<h3>Description</h3>
154<p>Time Data Types and Procedures</p></div>
155<div class="section">
156<h3>Author</h3><a href="mailto:klovett@pacbell.net">Kon Lovett</a></div>
157<div class="section">
158<h3>Requires</h3>
159<ul>
160<li>Chicken 2.610</li>
161<li>locale</li>
162<li>srfi-29</li>
163<li>numbers</li></ul></div>
164<div class="section">
165<h3>Usage</h3><tt>(require-extension srfi-19)</tt></div>
166<div class="section">
167<h3>Download</h3><a href="srfi-19.egg">srfi-19.egg</a></div>
168<div class="section">
169<h3>Documentation</h3>
170<p>This is a Chicken port of SRFI-19. This document only describes the extensions. For the SRFI-19 API see <a href="http://srfi.schemers.org/srfi-19/srfi-19.html">SRFI-19</a>.</p>
171<div class="subsection">
172<h4>Core Procedures</h4>
173<div class="section">
174<h3>Usage</h3>(require-extension srfi-19-core)</div>
175<div class="subsubsection">
176<h5>SRFI-19 Document Changes</h5>
177<p>The <b>nanosecond</b> time object element is an integer between 0 and 999,999,999 inclusive. (The SRFI-19 document mis-states the value.)</p>
178<p>A <i>tz-offset</i> value follows ISO 8601; positive for <em>east</em> of UTC, and negative for <em>west</em>. This is the <em>opposite</em> of the POSIX TZ environment variable.</p>
179<p>Where the SRFI-19 document states a <i>tz-offset</i> argument a timezone-components object is also legal.</p>
180<p>The <code>string-&gt;date</code> procedure allows the template-name argument to be optional. When missing the locale's date-time-format string is used. The supplied locale bundle's strings are invertible.</p>
181<dt class="definition"><strong>procedure:</strong> (make-date NANOSECOND SECOND MINUTE HOUR DAY MONTH YEAR ZONE-OFFSET [TZ-NAME #f] [DST-FLAG #f])</dt>
182<dd>
183<p>Same as SRFI-19 except for the optional parameters and allowing a timezone-components object for the <tt>ZONE-OFFSET</tt>.</p></dd>
184<dt class="definition"><strong>procedure:</strong> (read-leap-second-table FILENAME)</dt>
185<dd>
186<p>Sets the leap second table from the specified <tt>FILENAME</tt>.</p>
187<p>The file format is the same as the &quot;tai-utc.dat&quot; file in the distribution. Provided by the U.S. Naval Observatory.</p></dd>
188<dt class="definition"><strong>procedure:</strong> (leap-year? DATE)</dt>
189<dd>
190<p>Does the specified <tt>DATE</tt> fall on a leap year?</p></dd></div>
191<div class="subsubsection">
192<h5>SRFI-18 Time</h5>
193<p>Due to conflicts between SRFI-18 and SRFI-19 procedure variables <code>srfi-19:current-time</code> is a synonym for <code>current-time</code> and <code>srfi-19:time?</code> is a synonym for <code>time?</code>.</p>
194<dt class="definition"><strong>procedure:</strong> (time-&gt;srfi-18-time TIME)</dt>
195<dd>
196<p>Converts a SRFI-19 time object to a SRFI-18 time object. The conversion is really only meaningful for time-duration, but any time-type is accepted.</p></dd>
197<dt class="definition"><strong>procedure:</strong> (srfi-18-time-&gt;time TIME)</dt>
198<dd>
199<p>Converts a SRFI-18 time object into a SRFI-19 time-duration object.</p></dd></div>
200<div class="subsubsection">
201<h5>Time Conversion</h5>
202<dt class="definition"><strong>procedure:</strong> (seconds-&gt;time/type SECONDS [TIME-TYPE time-duration])</dt>
203<dd>
204<p>Converts a <tt>SECONDS</tt> value, may be fractional, into a <tt>TIME-TYPE</tt> time object.</p></dd>
205<dt class="definition"><strong>procedure:</strong> (seconds-&gt;date/type SECONDS [TIMEZONE-INFO #f])</dt>
206<dd>
207<p>Converts a <tt>SECONDS</tt> value, which may be fractional, into a date object. The <tt>TIMEZONE-INFO</tt> is <code>#t</code> for the local timezone, <code>#f</code> for the utc timezone, or a timezone-components object.</p>
208<p><tt>SECONDS</tt> is relative to 00:00:00 January 1, 1970 UTC.</p></dd>
209<dt class="definition"><strong>procedure:</strong> (time-&gt;nanoseconds TIME)</dt>
210<dd>
211<p>Returns the <tt>TIME</tt> object value as a nanoseconds value.</p></dd>
212<dt class="definition"><strong>procedure:</strong> (nanoseconds-&gt;time NANOSECONDS [TIME-TYPE time-duration])</dt>
213<dd>
214<p>Returns the <tt>NANOSECONDS</tt> value as a time <tt>TIME-TYPE</tt> object.</p></dd>
215<dt class="definition"><strong>procedure:</strong> (nanoseconds-&gt;seconds NANOSECONDS)</dt>
216<dd>
217<p>Returns the <tt>NANOSECONDS</tt> value as an inexact seconds value.</p></dd>
218<dt class="definition"><strong>procedure:</strong> (time-&gt;milliseconds TIME)</dt>
219<dd>
220<p>Returns the <tt>TIME</tt> object value as a milliseconds value.</p></dd>
221<dt class="definition"><strong>procedure:</strong> (milliseconds-&gt;time MILLISECONDS [TIME-TYPE time-duration])</dt>
222<dd>
223<p>Returns the <tt>MILLISECONDS</tt> value as a time <tt>TIME-TYPE</tt> object.</p></dd>
224<dt class="definition"><strong>procedure:</strong> (milliseconds-&gt;seconds MILLISECONDS)</dt>
225<dd>
226<p>Returns the <tt>MILLISECONDS</tt> value as an inexact seconds value.</p></dd>
227<dt class="definition"><strong>procedure:</strong> (time-&gt;date TIME)</dt>
228<dd>
229<p>Returns the <tt>TIME</tt> object value as a date. A shorthand for the <code>(time-*-&gt;date ...)</code> procedures.</p></dd>
230<dt class="definition"><strong>procedure:</strong> (time-&gt;julian-day TIME)</dt>
231<dd>
232<p>Returns the julian day for the <tt>TIME</tt> object.</p></dd>
233<dt class="definition"><strong>procedure:</strong> (time-&gt;modified-julian-day TIME)</dt>
234<dd>
235<p>Returns the modified julian day for the <tt>TIME</tt> object.</p></dd></div>
236<div class="subsubsection">
237<h5>Time Arithmetic</h5>
238<dt class="definition"><strong>procedure:</strong> (make-duration [#:days 0] [#:hours 0] [#:minutes 0] [#:seconds 0] [#:milliseconds 0] [#:microseconds 0] [#:nanoseconds 0])</dt>
239<dd>
240<p>Returns a time-object of clock-type <code>time-duration</code> where the seconds and nanoseconds values are calculated by summing the keyword arguments.</p>
241<p><code>ONE-SECOND-DURATION</code> and <code>ONE-NANOSECOND-DURATION</code> are pre-defined.</p></dd>
242<dt class="definition"><strong>procedure:</strong> (divide-duration DURATION NUMBER)</dt>
243<dd>
244<p>Returns a duration, from <tt>DURATION</tt>, divided by <tt>NUMBER</tt>, without remainder.</p></dd>
245<dt class="definition"><strong>procedure:</strong> (divide-duration! DURATION NUMBER)</dt>
246<dd>
247<p>Returns <tt>DURATION</tt>, divided by <tt>NUMBER</tt>, without remainder.</p></dd>
248<dt class="definition"><strong>procedure:</strong> (multiply-duration DURATION NUMBER)</dt>
249<dd>
250<p>Returns a duration, from <tt>DURATION</tt>, multiplied by <tt>NUMBER</tt>, truncated.</p></dd>
251<dt class="definition"><strong>procedure:</strong> (multiply-duration! DURATION NUMBER)</dt>
252<dd>
253<p>Returns <tt>DURATION</tt>, multiplied by <tt>NUMBER</tt>, truncated.</p></dd>
254<dt class="definition"><strong>procedure:</strong> (time-negative? TIME)</dt>
255<dd>
256<p>Is <tt>TIME</tt> negative?</p>
257<p>A time object will never have a negative nanoseconds value.</p></dd>
258<dt class="definition"><strong>procedure:</strong> (time-positve? TIME)</dt>
259<dd>
260<p>Is <tt>TIME</tt> positive?</p></dd>
261<dt class="definition"><strong>procedure:</strong> (time-zero? TIME)</dt>
262<dd>
263<p>Is <tt>TIME</tt> zero?</p></dd>
264<dt class="definition"><strong>procedure:</strong> (time-abs TIME)</dt>
265<dd>
266<p>Returns the absolute time value, from <tt>TIME</tt>.</p></dd>
267<dt class="definition"><strong>procedure:</strong> (time-abs! TIME)</dt>
268<dd>
269<p>Returns the absolute <tt>TIME</tt> value.</p></dd>
270<dt class="definition"><strong>procedure:</strong> (time-negate TIME)</dt>
271<dd>
272<p>Returns the sign inverted time value, from <tt>TIME</tt>.</p></dd>
273<dt class="definition"><strong>procedure:</strong> (time-negate! TIME)</dt>
274<dd>
275<p>Returns the<tt>TIME</tt> sign inverted value.</p></dd></div>
276<div class="subsubsection">
277<h5>Time Comparison</h5>
278<dt class="definition"><strong>procedure:</strong> (time-compare TIME1 TIME2)</dt>
279<dd>
280<p>Returns -1, 0, or 1.</p></dd>
281<dt class="definition"><strong>procedure:</strong> (time-max TIME1 [TIME2 ...])</dt>
282<dd>
283<p>Returns the maximum time object from <tt>TIME1 TIME2 ...</tt>.</p></dd>
284<dt class="definition"><strong>procedure:</strong> (time-min TIME1 [TIME2 ...])</dt>
285<dd>
286<p>Returns the minimum time object from <tt>TIME1 TIME2 ...</tt>.</p></dd></div>
287<div class="subsubsection">
288<h5>Dates</h5>
289<dt class="definition"><strong>parameter:</strong> (default-date-clock-type [CLOCK-TYPE time-utc])</dt>
290<dd>
291<p>Sets or gets the clock-type used by default for conversion of a date to a time.</p></dd>
292<dt class="definition"><strong>procedure:</strong> (copy-date DATE)</dt>
293<dd>
294<p>Returns an exact copy of the specified <tt>DATE</tt> object.</p></dd>
295<dt class="definition"><strong>procedure:</strong> (date-&gt;time DATE [CLOCK-TYPE (default-date-clock-type)])</dt>
296<dd>
297<p>Returns the specified <tt>DATE</tt> as a time-object of type <tt>CLOCK-TYPE</tt>.</p></dd>
298<dt class="definition"><strong>procedure:</strong> (date-zone-name DATE)</dt>
299<dd>
300<p>Returns the timezone abbreviation of the specified <tt>DATE</tt> object. The result is either a string or <code>#f</code>.</p></dd>
301<dt class="definition"><strong>procedure:</strong> (date-dst? DATE)</dt>
302<dd>
303<p>Returns the daylight saving time flag of the specified <tt>DATE</tt> object.</p>
304<p>Only valid for &quot;current&quot; dates. Historical dates will not have a correct setting. Future dates cannot have a correct setting.</p></dd></div>
305<div class="subsubsection">
306<h5>Date Arithmetic</h5>
307<dt class="definition"><strong>procedure:</strong> (date-difference DATE1 DATE2 [CLOCK-TYPE])</dt>
308<dd>
309<p>Returns the duration between <tt>DATE1</tt> and <tt>DATE2</tt>.</p></dd>
310<dt class="definition"><strong>procedure:</strong> (date-add-duration DATE DURATION [CLOCK-TYPE])</dt>
311<dd>
312<p>Returns the <tt>DATE</tt> plus the <tt>DURATION</tt>.</p></dd>
313<dt class="definition"><strong>procedure:</strong> (date-subtract-duration DATE DURATION [CLOCK-TYPE])</dt>
314<dd>
315<p>Returns the <tt>DATE</tt> minus the <tt>DURATION</tt>.</p></dd></div>
316<div class="subsubsection">
317<h5>Date Comparison</h5>
318<dt class="definition"><strong>procedure:</strong> (date-compare DATE1 DATE2)</dt>
319<dd>
320<p>Returns -1, 0, or 1.</p></dd>
321<dt class="definition"><strong>procedure:</strong> (date=? DATE1 DATE2)</dt>
322<dd>
323<p>Is <tt>DATE1</tt> on <tt>DATE2</tt>?</p></dd>
324<dt class="definition"><strong>procedure:</strong> (date&gt;? DATE1 DATE2)</dt>
325<dd>
326<p>Is <tt>DATE1</tt> after <tt>DATE2</tt>?</p></dd>
327<dt class="definition"><strong>procedure:</strong> (date&lt;? DATE1 DATE2)</dt>
328<dd>
329<p>Is <tt>DATE1</tt> before <tt>DATE2</tt>?</p></dd>
330<dt class="definition"><strong>procedure:</strong> (date&gt;=? DATE1 DATE2)</dt>
331<dd>
332<p>Is <tt>DATE1</tt> after or on <tt>DATE2</tt>?</p></dd>
333<dt class="definition"><strong>procedure:</strong> (date&lt;=? DATE1 DATE2)</dt>
334<dd>
335<p>Is <tt>DATE1</tt> before or on <tt>DATE2</tt>?</p></dd></div>
336<div class="subsubsection">
337<h5>Timezone</h5>
338<p><b>Note</b> that the daylight saving time (summer time) flag is <em>always</em> taken from the system, unless supplied. Any summer time rule component of a <code>timezone-components</code> object is <em>not</em> processed.</p>
339<p>Remember that SRFI-19 timezone offset follows ISO 8601.</p>
340<dt class="definition"><strong>parameter:</strong> (local-timezone-locale [TZ-COMPONENTS])</dt>
341<dd>
342<p>Gets or sets the local timezone-locale object.</p></dd>
343<dt class="definition"><strong>parameter:</strong> (utc-timezone-locale [TZ-COMPONENTS])</dt>
344<dd>
345<p>Gets or sets the utc timezone-locale object.</p>
346<p>Probably not a good idea to change the value.</p></dd>
347<dt class="definition"><strong>procedure:</strong> (timezone-locale-name [TZ-COMPONENTS])</dt>
348<dd>
349<p>Returns the timezone-locale name of the supplied <tt>TZ-COMPONENTS</tt>, or the <code>(local-timezone-locale)</code> if missing.</p></dd>
350<dt class="definition"><strong>procedure:</strong> (timezone-locale-offset [TZ-COMPONENTS])</dt>
351<dd>
352<p>Returns the timezone-locale offset of the supplied <tt>TZ-COMPONENTS</tt>, or the <code>(local-timezone-locale)</code> if missing.</p></dd>
353<dt class="definition"><strong>procedure:</strong> (timezone-locale-dst? [TZ-COMPONENTS])</dt>
354<dd>
355<p>Returns the timezone-locale daylight saving time flag of the supplied <tt>TZ-COMPONENTS</tt>, or the <code>(local-timezone-locale)</code> if missing.</p></dd>
356<div class="subsubsubsection">
357<h6>Deprecated</h6>
358<dt class="definition"><strong>procedure:</strong> (make-timezone-locale DST-FLAG TZ-COMPONENTS)</dt>
359<dd>
360<p>Returns a timezone-locale object.</p>
361<p>A <tt>TZ-COMPONENTS</tt> object is as described by the <a href="locale.html">locale egg</a>.</p></dd>
362<dt class="definition"><strong>procedure:</strong> (timezone-locale? OBJ)</dt>
363<dd>
364<p>Is the <tt>OBJ</tt> a timezone-locale object?</p></dd></div></div></div>
365<div class="subsection">
366<h4>Time Period</h4>
367<div class="section">
368<h3>Usage</h3>(require-extension srfi-19-period)</div>
369<p>A time-period is an interval, [begin end), where begin and end are time objects of the same clock type. When end &lt;= begin the interval is null.</p>
370<dt class="definition"><strong>procedure:</strong> (make-null-time-period [CLOCK-TYPE (default-date-clock-type)])</dt>
371<dd>
372<p>Returns a null interval for the specified <tt>CLOCK-TYPE</tt>.</p></dd>
373<dt class="definition"><strong>procedure:</strong> (make-time-period BEGIN END [CLOCK-TYPE (default-date-clock-type)])</dt>
374<dd>
375<p>Returns a new time-period object. The clock types must be compatible.</p>
376<p><tt>BEGIN</tt> maybe a seconds value, a date, or a time (except time-duration). A seconds value or date are converted to <tt>CLOCK-TYPE</tt>.</p>
377<p><tt>END</tt> maybe a seconds value, a date, or a time. A seconds value or date are converted to the same clock type as <tt>BEGIN</tt>. A time-duration is treated as an offset from <tt>BEGIN</tt>.</p></dd>
378<dt class="definition"><strong>procedure:</strong> (copy-time-period TIME-PERIOD)</dt>
379<dd>
380<p>Returns a copy of <tt>TIME-PERIOD</tt>.</p></dd>
381<dt class="definition"><strong>procedure:</strong> (time-period-begin TIME-PERIOD)</dt>
382<dd>
383<p>Returns the start time for the <tt>TIME-PERIOD</tt>.</p></dd>
384<dt class="definition"><strong>procedure:</strong> (time-period-end TIME-PERIOD)</dt>
385<dd>
386<p>Returns the end time for the <tt>TIME-PERIOD</tt>.</p></dd>
387<dt class="definition"><strong>procedure:</strong> (time-period-last TIME-PERIOD)</dt>
388<dd>
389<p>Returns the last time for the <tt>TIME-PERIOD</tt>; (time-period-end - 1ns).</p></dd>
390<dt class="definition"><strong>procedure:</strong> (time-period-type TIME-PERIOD)</dt>
391<dd>
392<p>Returns the clock-type of the <tt>TIME-PERIOD</tt>.</p></dd>
393<dt class="definition"><strong>procedure:</strong> (time-period? OBJECT)</dt>
394<dd>
395<p>Is <tt>OBJECT</tt> a time-period?</p></dd>
396<dt class="definition"><strong>procedure:</strong> (time-period-null? TIME-PERIOD)</dt>
397<dd>
398<p>Is the <tt>TIME-PERIOD</tt> null?</p></dd>
399<dt class="definition"><strong>procedure:</strong> (time-period-length TIME-PERIOD)</dt>
400<dd>
401<p>Returns the time-duration of the <tt>TIME-PERIOD</tt>.</p></dd>
402<dt class="definition"><strong>procedure:</strong> (time-period=? TIME-PERIOD-1 TIME-PERIOD-2)</dt>
403<dd>
404<p>Does <tt>TIME-PERIOD-1</tt> begin &amp; end with <tt>TIME-PERIOD-2</tt>?</p></dd>
405<dt class="definition"><strong>procedure:</strong> (time-period&lt;? TIME-PERIOD-1 TIME-PERIOD-2)</dt>
406<dd>
407<p>Does <tt>TIME-PERIOD-1</tt> end before <tt>TIME-PERIOD-2</tt> begins?</p></dd>
408<dt class="definition"><strong>procedure:</strong> (time-period&gt;? TIME-PERIOD-1 TIME-PERIOD-2)</dt>
409<dd>
410<p>Does <tt>TIME-PERIOD-1</tt> begin after <tt>TIME-PERIOD-2</tt> ends?</p></dd>
411<dt class="definition"><strong>procedure:</strong> (time-period&lt;=? TIME-PERIOD-1 TIME-PERIOD-2)</dt>
412<dd>
413<p>Does <tt>TIME-PERIOD-1</tt> end on or before <tt>TIME-PERIOD-2</tt> begins?</p></dd>
414<dt class="definition"><strong>procedure:</strong> (time-period&gt;=? TIME-PERIOD-1 TIME-PERIOD-2)</dt>
415<dd>
416<p>Does <tt>TIME-PERIOD-1</tt> begin on or after <tt>TIME-PERIOD-2</tt> ends?</p></dd>
417<dt class="definition"><strong>procedure:</strong> (time-period-preceding TIME-PERIOD-1 TIME-PERIOD-2)</dt>
418<dd>
419<p>Return the portion of <tt>TIME-PERIOD-1</tt> before <tt>TIME-PERIOD-2</tt> or <code>#f</code> when it doesn't precede.</p></dd>
420<dt class="definition"><strong>procedure:</strong> (time-period-succeeding TIME-PERIOD-1 TIME-PERIOD-2)</dt>
421<dd>
422<p>Return the portion of <tt>TIME-PERIOD-1</tt> after <tt>TIME-PERIOD-2</tt> or <code>#f</code> when it doesn't succeed.</p></dd>
423<dt class="definition"><strong>procedure:</strong> (time-period-contains/period? TIME-PERIOD-1 TIME-PERIOD-2)</dt>
424<dd>
425<p>Is <tt>TIME-PERIOD-2</tt> within <tt>TIME-PERIOD-1</tt>?</p></dd>
426<dt class="definition"><strong>procedure:</strong> (time-period-contains/time? TIME-PERIOD TIME)</dt>
427<dd>
428<p>Is <tt>TIME</tt> within <tt>TIME-PERIOD</tt>?</p>
429<p><tt>TIME</tt> is converted to a compatible clock-type if possible.</p></dd>
430<dt class="definition"><strong>procedure:</strong> (time-period-contains/date? TIME-PERIOD DATE)</dt>
431<dd>
432<p>Is <tt>DATE</tt> within <tt>TIME-PERIOD</tt>?</p>
433<p><tt>DATE</tt> is converted to a compatible time if possible.</p></dd>
434<dt class="definition"><strong>procedure:</strong> (time-period-contains? TIME-PERIOD OBJECT)</dt>
435<dd>
436<p>Is <tt>OBJECT</tt> within <tt>TIME-PERIOD</tt>?</p>
437<p><tt>OBJECT</tt> maybe a time, date, or time-period.</p></dd>
438<dt class="definition"><strong>procedure:</strong> (time-period-intersects? TIME-PERIOD-1 TIME-PERIOD-2)</dt>
439<dd>
440<p>Does <tt>TIME-PERIOD-2</tt> overlap <tt>TIME-PERIOD-1</tt>?</p></dd>
441<dt class="definition"><strong>procedure:</strong> (time-period-intersection TIME-PERIOD-1 TIME-PERIOD-2)</dt>
442<dd>
443<p>The overlapping time-period of <tt>TIME-PERIOD-2</tt> and <tt>TIME-PERIOD-1</tt>, or <code>#f</code> when no overlap.</p></dd>
444<dt class="definition"><strong>procedure:</strong> (time-period-union TIME-PERIOD-1 TIME-PERIOD-2)</dt>
445<dd>
446<p>Returns the time-period spanned by <tt>TIME-PERIOD-1</tt> and <tt>TIME-PERIOD-2</tt>, or <code>#f</code> when they do not intersect.</p></dd>
447<dt class="definition"><strong>procedure:</strong> (time-period-span TIME-PERIOD-1 TIME-PERIOD-2)</dt>
448<dd>
449<p>Returns the time-period spanned by <tt>TIME-PERIOD-1</tt> and <tt>TIME-PERIOD-2</tt>, including any gaps.</p></dd>
450<dt class="definition"><strong>procedure:</strong> (time-period-shift TIME-PERIOD DURATION)</dt>
451<dd>
452<p>Returns a copy of <tt>TIME-PERIOD</tt> shifted by <tt>DURATION</tt>.</p></dd>
453<dt class="definition"><strong>procedure:</strong> (time-period-shift! TIME-PERIOD DURATION)</dt>
454<dd>
455<p>Returns <tt>TIME-PERIOD</tt> shifted by <tt>DURATION</tt>.</p></dd></div>
456<div class="subsection">
457<h4>Input/Output Procedures</h4>
458<div class="section">
459<h3>Usage</h3>(require-extension srfi-19-io)</div>
460<dt class="definition"><strong>procedure:</strong> (format-date DESTINATION DATE-FORMAT-STRING [DATE])</dt>
461<dd>
462<p>Displays a text form of the <tt>DATE</tt> on the <tt>DESTINATION</tt> using the <tt>DATE-FORMAT-STRING</tt>.</p>
463<p>When the destination is <code>#t</code> the <code>(current-output-port)</code> is used, and the date object must be specified.</p>
464<p>When the destination is a string the <tt>DATE-FORMAT-STRING</tt> value must be a date object, the <tt>DESTINATION</tt> value is used as the <tt>DATE-FORMAT-STRING</tt>, and the result is returned as a string.</p>
465<p>When the destination is a port it must be an <code>output-port</code>, and the date object must be specified. When the destination is a number the <code>(current-error-port)</code> is the destination, and the <tt>DATE</tt> object must be specified.</p>
466<p>When the destination is <code>#f</code> the result is returned as a string, and the <tt>DATE</tt> object must be specified.</p></dd>
467<dt class="definition"><strong>procedure:</strong> (scan-date SOURCE TEMPLATE-STRING)</dt>
468<dd>
469<p>Reads a text form of a date from the <tt>SOURCE</tt>, following the <tt>TEMPLATE-STRING</tt>, and returns a date object.</p>
470<p>When the source is <code>#t</code> the <code>(current-input-port)</code> is used.</p>
471<p>When the source is a port it must be an <code>input-port</code>.</p>
472<p>When the source is string it should be a date text form.</p></dd></div></div>
473<div class="section">
474<h3>Bugs</h3>
475<p>Local timezone information is not necessarily valid for historic dates and problematic for future dates. Daylight saving time is especially an issue. Conversion of a time or seconds value to a local date will use the current timezone offset value. The current offset will reflect the daylight saving time status. So target dates outside of the DST period will be converted incorrectly!</p>
476<p>Will not read years less than 1 properly. The ISO 8601 year convention for years 1 BCE and before and years 10000 CE and after is not supported.</p></div>
477<div class="section">
478<h3>Issues</h3>
479<p>31 December 1 BCE + 1 day =&gt; 1 January 1 CE. There is no year 0. Unlike the ISO 8601 convention do not subtract 1 when converting a year BCE to a SRFI-19 year, just negate the year.</p>
480<p>The SRFI-18 <code>current-time</code> and <code>time?</code> bindings conflict with SRFI-19 bindings.</p>
481<p>The SRFI-18 time object is not accepted except by the conversion procedures.</p>
482<p>The expression <code>(time=? (seconds-&gt;time/type (nanoseconds-&gt;seconds (time-&gt;nanoseconds &lt;time-duration&gt;))) &lt;time-duration&gt;)</code> might be <code>#f</code>, due to the use of inexact arithmetic.</p>
483<p>Be careful using the procedures that return some form of 'julian-day'. These are implemented using the full numeric tower and <em>will</em> return rational numbers. Performing arithmetic with such a result will require the &quot;numbers&quot; egg. See the file &quot;srfi-19-test.scm&quot; in this egg for an example.</p>
484<p>This will be a problem with code that assumes fixnum and/or flonum <em>only</em> numbers. Perhaps an intermediate file that wraps any 'julian-day' calls and coerces to an inexact number. Use the wrapped 'julian-day' call in the problematic code.</p></div>
485<div class="section">
486<h3>Examples</h3>
487<div id="examples">; See the &quot;srfi-19-test.scm&quot; file in the egg.</div></div>
488<div class="section">
489<h3>Version</h3>
490<ul>
491<li>2.8.0 Timezone locale creation removed. Removed 'make-local-timezone-locale'.</li>
492<li>2.7.1 Fix for 'add/subtract-duration[!].</li>
493<li>2.7.0 Replaced date comparison w/ a field by field algorithm. Removed local-timezone-info, local-timezone-name, local-timezone-offset, and local-timezone-dst?.</li>
494<li>2.6.11 Printing of &quot;xxx.0&quot; =&gt; xxx. More use of fixnum ops in srfi-19-io.</li>
495<li>2.6.10 Dropped :optional.</li>
496<li>2.6.9 Needs Chicken 2.610 for MacOS X &amp; Windows.</li>
497<li>2.6.8 Bug fix for make-date supplied dst flag. Added Bugs section.</li>
498<li>2.6.7 Uses fixnum arithmetic where possible. Added time-&gt;julian-day, time-&gt;modified-julian-day, date comparisons. Bug fix for multiply-duration, divide-duration, &amp; make-duration. Changed read-leap-second-table to required filename parameter.</li>
499<li>2.6.6 Bug fix for time&lt;=? &amp; time&gt;=?. Added time-period-preceding &amp; time-period-succeeding. Split periods into srfi-19-period.</li>
500<li>2.6.5 Bug fix for platforms not MacOS X, timezone offset was sign reversed.</li>
501<li>2.6.4 Bug fix to time ctors/setters - allowed negative nanoseconds. Added make-local-timezone-locale w/ special case for platforms not Windows or Macintosh. Made local-timezone-locale a parameter.</li>
502<li>2.6.3 Made time-max &amp; time-min n-ary. Added make-null-time-period, time-negative?, time-positive?, time-zero?. Bug fix for local-timezone-offset [reported by Hans Bulfone]</li>
503<li>2.6.2 Bug fix for local-timezone-locale, seconds-&gt;date/type, current-nanoseconds, &amp; current-date [reported by Hans Bulfone]</li>
504<li>2.6.1 Deprecated local-timezone-info, local-timezone-name, local-timezone-offset, and local-timezone-dst?. Bug fix for milliseconds-&gt;time. Bug fix for current-date when no tz-locale. [reported by Graham Fawcett]</li>
505<li>2.6 Added time-period, date arithmetic, duration routines, fix for possible seconds limit in time object</li>
506<li>2.5 Added Dutch locale, ISO-8601 conversion bug fix, 'date-year-day' bug fix [thanks to Arno Peters]</li>
507<li>2.4 Removed annoying warnings, made srfi-19 an umbrella - uses -core &amp; -io</li>
508<li>2.3 Date dst? field, timezone-locale structure accessors</li>
509<li>2.2 Bug fix for no local timezone setting situation [reported by Mario Domenech Goulart]</li>
510<li>2.1 Bug fix for -&gt;fixnum [reported by Mario Domenech Goulart]</li>
511<li>2.0 Removed I/O routines to own extension</li>
512<li>1.9 Fix, in conjunction w/ srfi-29, for locale details</li>
513<li>1.8 Version removed</li>
514<li>1.7 Brazilian Portuguese [thanks to Mario Domenech Goulart]</li>
515<li>1.6 Bug fix for inexact seconds in time-&gt;date [thanks to Peter Bex]</li>
516<li>1.5 Bug fix for compiled use</li>
517<li>1.4 Exports</li>
518<li>1.3 Bug fix</li>
519<li>1.2 Slightly smaller and faster</li>
520<li>1.1 Some SRFI-18 conflict reduction</li>
521<li>1.0 Initial release</li></ul></div>
522<div class="section">
523<h3>License</h3>
524<pre>Copyright (c) 2005, Kon Lovett.  All rights reserved.
525
526Permission is hereby granted, free of charge, to any person obtaining a
527copy of this software and associated documentation files (the Software),
528to deal in the Software without restriction, including without limitation
529the rights to use, copy, modify, merge, publish, distribute, sublicense,
530and/or sell copies of the Software, and to permit persons to whom the
531Software is furnished to do so, subject to the following conditions:
532
533The above copyright notice and this permission notice shall be included
534in all copies or substantial portions of the Software.
535
536THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
537IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
538FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
539THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
540OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
541ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
542OTHER DEALINGS IN THE SOFTWARE.
543
544Copyright (C) I/NET, Inc. (2000, 2002, 2003). All Rights Reserved.
545Copyright (C) Neodesic Corporation (2000). All Rights Reserved.
546
547This document and translations of it may be copied and furnished to others,
548and derivative works that comment on or otherwise explain it or assist in its
549implementation may be prepared, copied, published and distributed, in whole or
550in part, without restriction of any kind, provided that the above copyright
551notice and this paragraph are included on all such copies and derivative works.
552However, this document itself may not be modified in any way, such as by
553removing the copyright notice or references to the Scheme Request For
554Implementation process or editors, except as needed for the purpose of
555developing SRFIs in which case the procedures for copyrights defined in the SRFI
556process must be followed, or as required to translate it into languages other
557than English.
558
559The limited permissions granted above are perpetual and will not be revoked
560by the authors or their successors or assigns.
561
562This document and the information contained herein is provided on an &quot;AS IS&quot;
563basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL WARRANTIES, EXPRESS OR
564IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
565INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
566MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</pre></div></div>
567<div id="footer">
568<hr /><a href="index.html">&lt; Egg index</a>
569<div id="revision-history">$Revision$ $Date$</div>&nbsp;</div></body></html>
Note: See TracBrowser for help on using the repository browser.