source: project/wiki/eggref/4/srfi-19 @ 35417

Last change on this file since 35417 was 35417, checked in by kon, 14 months ago

add 'timezone runtime init ex

File size: 25.5 KB
Line 
1[[tags: egg]]
2
3== srfi-19
4
5Time Data Types and Procedures
6
7[[toc:]]
8
9== Documentation
10
11This is a Chicken port of SRFI-19. This document only describes the extensions.
12For the SRFI-19 API see [[http://srfi.schemers.org/srfi-19/srfi-19.html|SRFI-19]].
13
14=== Core Procedures
15
16The ''core'' procedures are those pertaining to time, date, and timezone:
17
18<enscript language=scheme>
19(require-extension srfi-19-core)
20</enscript>
21
22The ''core'' procedures can be separately accessed:
23
24<enscript language=scheme>
25(require-extension srfi-19-time)
26</enscript>
27<enscript language=scheme>
28(require-extension srfi-19-date)
29</enscript>
30<enscript language=scheme>
31(require-extension srfi-19-timezone)
32</enscript>
33<enscript language=scheme>
34(require-extension srfi-19-io)
35</enscript>
36
37==== SRFI-19 Document Changes
38
39The '''nanosecond''' time object element is an integer between 0 and
40999,999,999 inclusive. (The SRFI-19 document mis-states the value.)
41
42A ''tz-offset'' value follows ISO 8601; positive for '''east''' of UTC, and
43negative for '''west'''. This is the '''opposite''' of the POSIX TZ environment
44variable.
45
46Where the SRFI-19 document states a ''tz-offset'' argument a
47{{timezone-components}} object is also legal.
48
49The {{string->date}} procedure allows the template-name argument to be
50optional. When missing the locale's {{date-time-format}} string is used. The
51supplied locale bundle's strings are invertible.
52
53===== make-date
54
55<procedure>(make-date NANOSECOND SECOND MINUTE HOUR DAY MONTH YEAR [ZONE-OFFSET [TZ-NAME [DST-FLAG]]]) -> date</procedure>
56
57Same as SRFI-19 except for the optional parameters and allowing a
58timezone-components object for the {{ZONE-OFFSET}}.
59
60The {{ZONE-OFFSET}} is an {{integer}} or {{timezone-components}}. Default is
61the {{(timezone-locale-offset)}}, the current locale timezone offset.
62
63The {{TZ-NAME}} is a {{string}} or {{#f}}, and is the timezone name. Default is {{#f}}.
64
65The {{DST-FLAG}} is a {{boolean}}, and indicates whether Day Saving TIme (or
66Summer Time) is active. Default is {{#f}}.
67
68When the {{ZONE-OFFSET}} is a {{timezone-components}} object the {{TZ-NAME}}
69and {{DST-FLAG}} are pulled from the {{timezone-components}}, unless explicitly
70supplied.
71
72===== read-leap-second-table
73
74<procedure>(read-leap-second-table FILENAME)</procedure>
75
76Sets the leap second table from the specified {{FILENAME}}.
77
78The file format is the same as the "tai-utc.dat" file in the distribution.
79Provided by the U.S. Naval Observatory.
80
81===== leap-year?
82
83<procedure>(leap-year? DATE) -> boolean</procedure>
84
85Does the specified {{DATE}} fall on a leap year?
86
87The {{DATE}} may be a numeric year or a {{date}} object.
88
89==== SRFI-18 Time
90
91Note that the '''SRFI-18''' identifiers {{time?}}, {{current-time}},
92{{seconds->time}}, {{time->seconds}}, {{milliseconds->time}}, and
93{{time->milliseconds}} are in conflict with those of '''SRFI-19'''.
94
95===== time->srfi-18-time
96
97<procedure>(time->srfi-18-time TIME) -> srfi-18#time</procedure>
98
99Converts a SRFI-19 time object to a SRFI-18 time object. The conversion is
100really only meaningful for {{time-duration}}, but any time-type is accepted.
101
102===== srfi-18-time->time
103
104<procedure>(srfi-18-time->time TIME) -> srfi-19#time</procedure>
105
106Converts a SRFI-18 time object into a SRFI-19 {{time-duration}} object.
107
108==== Object Printing
109
110===== time-record-printer-format
111
112<procedure>(time-record-printer-format [FORM]) -> (or symbol boolean)</procedure>
113
114{{FORM}} is {{'srfi-10}} or  {{'#f}}.
115
116===== date-record-printer-format
117
118<procedure>(date-record-printer-format [FORM]) -> (or symbol boolean)</procedure>
119
120{{FORM}} is {{'srfi-10}} or  {{'#f}}.
121
122==== Time Conversion
123
124===== seconds->time
125
126<procedure>(seconds->time SECONDS [TIME-TYPE time-duration]) -> time</procedure>
127
128Converts a {{SECONDS}} value, may be fractional, into a {{TIME-TYPE}} time
129object.
130
131===== seconds->date
132
133<procedure>(seconds->date SECONDS [TIMEZONE-INFO #t]) -> date</procedure>
134
135Converts a {{SECONDS}} value, which may be fractional, into a date object. The
136{{TIMEZONE-INFO}} is {{#t}} for the local timezone, {{#f}} for the utc
137timezone, or a timezone-components object.
138
139{{SECONDS}} is relative to 00:00:00 January 1, 1970 UTC.
140
141===== time->nanoseconds
142
143<procedure>(time->nanoseconds TIME) -> integer</procedure>
144
145Returns the {{TIME}} object value as a nanoseconds value.
146
147===== nanoseconds->time
148
149<procedure>(nanoseconds->time NANOSECONDS [TIME-TYPE time-duration]) -> time</procedure>
150
151Returns the {{NANOSECONDS}} value as a time {{TIME-TYPE}} object.
152
153===== nanoseconds->seconds
154
155<procedure>(nanoseconds->seconds NANOSECONDS) -> integer</procedure>
156
157Returns the {{NANOSECONDS}} value as an inexact seconds value.
158
159===== time->milliseconds
160
161<procedure>(time->milliseconds TIME) -> integer</procedure>
162
163Returns the {{TIME}} object value as a milliseconds value.
164
165===== milliseconds->time
166
167<procedure>(milliseconds->time MILLISECONDS [TIME-TYPE time-duration]) -> time</procedure>
168
169Returns the {{MILLISECONDS}} value as a time {{TIME-TYPE}} object.
170
171===== milliseconds->seconds
172
173<procedure>(milliseconds->seconds MILLISECONDS) -> integer</procedure>
174
175Returns the {{MILLISECONDS}} value as an inexact seconds value.
176
177===== time->date
178
179<procedure>(time->date TIME) -> date</procedure>
180
181Returns the {{TIME}} object value as a date. A shorthand for the
182{{(time-*->date...)}} procedures.
183
184===== time->julian-day
185
186<procedure>(time->julian-day TIME) -> rational</procedure>
187
188Returns the julian day for the {{TIME}} object.
189
190===== time->modified-julian-day
191
192<procedure>(time->modified-julian-day TIME) -> rational</procedure>
193
194Returns the modified julian day for the {{TIME}} object.
195
196==== Time Arithmetic
197
198===== make-duration
199
200<procedure>(make-duration [#:days 0] [#:hours 0] [#:minutes 0] [#:seconds 0] [#:milliseconds 0] [#:microseconds 0] [#:nanoseconds 0]) -> time</procedure>
201
202Returns a time-object of clock-type {{time-duration}} where the seconds and
203nanoseconds values are calculated by summing the keyword arguments.
204
205===== one-second-duration
206
207<procedure>(one-second-duration) -> time</procedure>
208
209===== one-nanosecond-duration
210
211<procedure>(one-nanosecond-duration) -> time</procedure>
212
213===== zero-time
214
215<procedure>(zero-time [TIME-TYPE time-duration]) -> time</procedure>
216
217===== TIME-FINE-GRAIN
218
219Most minimum positive amount of time, as a duration.
220
221===== divide-duration
222
223<procedure>(divide-duration DURATION NUMBER) -> time</procedure>
224
225Returns a duration, from {{DURATION}}, divided by {{NUMBER}}, without
226remainder.
227
228===== divide-duration!
229
230<procedure>(divide-duration! DURATION NUMBER) -> time</procedure>
231
232Returns {{DURATION}}, divided by {{NUMBER}}, without remainder.
233
234===== multiply-duration
235
236<procedure>(multiply-duration DURATION NUMBER) -> time</procedure>
237
238Returns a duration, from {{DURATION}}, multiplied by {{NUMBER}}, truncated.
239
240===== multiply-duration!
241
242<procedure>(multiply-duration! DURATION NUMBER) -> time</procedure>
243
244Returns {{DURATION}}, multiplied by {{NUMBER}}, truncated.
245
246===== time-negative?
247
248<procedure>(time-negative? TIME) -> boolean</procedure>
249
250Is {{TIME}} negative?
251
252A time object will never have a negative nanoseconds value.
253
254===== time-positve?
255
256<procedure>(time-positve? TIME) -> boolean</procedure>
257
258Is {{TIME}} positive?
259
260===== time-zero?
261
262<procedure>(time-zero? TIME) -> boolean</procedure>
263
264Is {{TIME}} zero?
265
266===== time-abs
267
268<procedure>(time-abs TIME) -> time</procedure>
269
270Returns the absolute time value, from {{TIME}}.
271
272===== time-abs!
273
274<procedure>(time-abs! TIME) -> time</procedure>
275
276Returns the absolute {{TIME}} value.
277
278===== time-negate
279
280<procedure>(time-negate TIME) -> time</procedure>
281
282Returns the sign inverted time value, from {{TIME}}.
283
284===== time-negate!
285
286<procedure>(time-negate! TIME) -> time</procedure>
287
288Returns the {{TIME}} sign inverted value.
289
290==== Time Comparison
291
292===== time-compare
293
294<procedure>(time-compare TIME1 TIME2) -> integer</procedure>
295
296Returns -1, 0, or 1.
297
298===== time-max
299
300<procedure>(time-max TIME1 [TIME2...]) -> time</procedure>
301
302Returns the maximum time object from {{TIME1 TIME2...}}.
303
304===== time-min
305
306<procedure>(time-min TIME1 [TIME2...]) -> time</procedure>
307
308Returns the minimum time object from {{TIME1 TIME2...}}.
309
310==== Dates
311
312===== default-date-clock-type
313
314<parameter>(default-date-clock-type [CLOCK-TYPE time-utc]) -> symbol</parameter>
315
316Sets or gets the clock-type used by default for conversion of a date to a time.
317
318===== copy-date
319
320<procedure>(copy-date DATE) -> date</procedure>
321
322Returns an exact copy of the specified {{DATE}} object.
323
324===== date->time
325
326<procedure>(date->time DATE [CLOCK-TYPE (default-date-clock-type)]) -> time</procedure>
327
328Returns the specified {{DATE}} as a time-object of type {{CLOCK-TYPE}}.
329
330===== date-zone-name
331
332<procedure>(date-zone-name DATE) -> (or boolean string)</procedure>
333
334Returns the timezone abbreviation of the specified {{DATE}} object. The result
335is either a string or {{#f}}.
336
337===== date-dst?
338
339<procedure>(date-dst? DATE) -> boolean</procedure>
340
341Returns the daylight saving time flag of the specified {{DATE}} object.
342
343Only valid for "current" dates. Historical dates will not have a correct
344setting. Future dates cannot have a correct setting.
345
346==== Date Arithmetic
347
348===== date-difference
349
350<procedure>(date-difference DATE1 DATE2 [CLOCK-TYPE]) -> time</procedure>
351
352Returns the {{time-duration}} between {{DATE1}} and {{DATE2}}.
353
354===== date-add-duration
355
356<procedure>(date-add-duration DATE DURATION [CLOCK-TYPE]) -> date</procedure>
357
358Returns a new date, the {{DATE}} plus the {{DURATION}}.
359
360===== date-subtract-duration
361
362<procedure>(date-subtract-duration DATE DURATION [CLOCK-TYPE]) -> date</procedure>
363
364Returns a new date, the {{DATE}} minus the {{DURATION}}.
365
366===== date-adjust
367
368<procedure>(date-adjust DATE AMOUNT DATE-KEY [CLOCK-TYPE]) -> date</procedure>
369
370Returns a new date, the {{DATE}} adjusted by the {{AMOUNT}} of {{DATE-KEY}}.
371
372{{AMOUNT}} is an {{integer}}.
373
374{{DATE-KEY}} is either {{'years}}, {{'quarters}}, {{'months}}, {{'days}},
375{{'hours}}, {{'minutes}}, {{'seconds}}, {{'milliseconds}}, {{'microseconds}},
376or {{'nanoseconds}}.
377
378If the day of the month of {{DATE}} is greater than the number of
379days in the final month, the day of the month will change to the last day in
380the final month.
381
382Adjusting a time {{DATE-KEY}} (ex: {{'hours}}) follows the semantics of
383{{date-add-duration}}.
384
385==== Date Comparison
386
387===== date-compare
388
389<procedure>(date-compare DATE1 DATE2) -> integer</procedure>
390
391Returns -1, 0, or 1.
392
393===== date=?
394
395<procedure>(date=? DATE1 DATE2) -> boolean</procedure>
396
397Is {{DATE1}} on {{DATE2}}?
398
399===== date>?
400
401<procedure>(date>? DATE1 DATE2) -> boolean</procedure>
402
403Is {{DATE1}} after {{DATE2}}?
404
405===== date<?
406
407<procedure>(date<? DATE1 DATE2) -> boolean</procedure>
408
409Is {{DATE1}} before {{DATE2}}?
410
411===== date>=?
412
413<procedure>(date>=? DATE1 DATE2) -> boolean</procedure>
414
415Is {{DATE1}} after or on {{DATE2}}?
416
417===== date<=?
418
419<procedure>(date<=? DATE1 DATE2) -> boolean</procedure>
420
421Is {{DATE1}} before or on {{DATE2}}?
422
423==== Timezone
424
425* Note that the daylight saving time (summer time) flag is '''always''' taken
426from the system, unless supplied. Any summer time rule component of a
427{{timezone-components}} object is '''not''' processed.
428
429Remember that SRFI-19 timezone offset follows ISO 8601.
430
431===== local-timezone-locale
432
433<parameter>(local-timezone-locale [TZ-COMPONENTS])</parameter>
434
435Gets or sets the local timezone-locale object.
436
437===== utc-timezone-locale
438
439<parameter>(utc-timezone-locale [TZ-COMPONENTS])</parameter>
440
441Gets or sets the utc timezone-locale object.
442
443Probably not a good idea to change the value.
444
445===== timezone-locale-name
446
447<procedure>(timezone-locale-name [TZ-COMPONENTS]) -> symbol</procedure>
448
449Returns the timezone-locale name of the supplied {{TZ-COMPONENTS}}, or the
450{{(local-timezone-locale)}} if missing.
451
452===== timezone-locale-offset
453
454<procedure>(timezone-locale-offset [TZ-COMPONENTS]) -> integer</procedure>
455
456Returns the timezone-locale offset of the supplied {{TZ-COMPONENTS}}, or the
457{{(local-timezone-locale)}} if missing.
458
459===== timezone-locale-dst?
460
461<procedure>(timezone-locale-dst? [TZ-COMPONENTS]) -> boolean</procedure>
462
463Returns the timezone-locale daylight saving time flag of the supplied
464{{TZ-COMPONENTS}}, or the {{(local-timezone-locale)}} if missing.
465
466=== Input/Output Procedures
467
468<enscript language=scheme>
469(require-extension srfi-19-io)
470</enscript>
471
472==== DATE->STRING conversion specifiers
473
474The SRFI-19 document does not mention the padding character override feature
475for the normally zero-padded conversions {{f}}, {{H}}, {{I}}, {{j}}, {{m}},
476{{M}}, {{N}}, {{S}}, {{y}}. If the tilde is followed by a {{-}} then padding
477is suppressed. If followed by a {{_}} the space character is used for padding.
478Otherwise zero-padding is perfomed, the default.
479
480~[-_][fHIjmMNSy]
481
482===== format-date
483
484<procedure>(format-date DESTINATION DATE-FORMAT-STRING DATE)</procedure>
485
486Displays a text form of the {{DATE}} on the {{DESTINATION}} using the
487{{DATE-FORMAT-STRING}}.
488
489When the {{DESTINATION}} is {{#t}} the {{(current-output-port)}} is used, and the
490date object must be specified.
491
492When the {{DESTINATION}} is a port it must be an {{output-port}}, and the date
493object must be specified.
494
495When the {{DESTINATION}} is a number the {{(current-error-port)}} is the
496{{DESTINATION}}, and the {{DATE}} object must be specified.
497
498When the {{DESTINATION}} is {{#f}} the result is returned as a string, and the
499{{DATE}} object must be specified.
500
501<procedure>(format-date DATE-FORMAT-STRING DATE) -> {{string}}</procedure>
502
503Result is returned as a string.
504
505===== scan-date
506
507<procedure>(scan-date SOURCE TEMPLATE-STRING)</procedure>
508
509Reads a text form of a date from the {{SOURCE}}, following the
510{{TEMPLATE-STRING}}, and returns a date object.
511
512When the {{SOURCE}} is {{#t}} the {{(current-input-port)}} is used.
513
514When the {{SOURCE}} is a port it must be an {{input-port}}.
515
516When the {{SOURCE}} is string it should be a date text form.
517
518=== Time Period
519
520==== Usage
521
522<enscript language=scheme>
523(require-extension srfi-19-period)
524</enscript>
525
526A time-period is an interval, [begin end), where begin and end are time objects
527of the same clock type.
528
529===== make-time-period
530
531<procedure>(make-time-period BEGIN END [CLOCK-TYPE (default-date-clock-type)]) -> time-period</procedure>
532
533Returns a new time-period object. The clock types must be compatible.
534
535{{BEGIN}} maybe a seconds value, a date, or a time (except time-duration). A
536seconds value or date are converted to {{CLOCK-TYPE}}.
537
538{{END}} maybe a seconds value, a date, or a time. A seconds value or date are
539converted to the same clock type as {{BEGIN}}. A time-duration is treated as an
540offset from {{BEGIN}}.
541
542===== copy-time-period
543
544<procedure>(copy-time-period TIME-PERIOD) -> time-period</procedure>
545
546Returns a copy of {{TIME-PERIOD}}.
547
548===== time-period-begin
549
550<procedure>(time-period-begin TIME-PERIOD)</procedure>
551
552Returns the start time for the {{TIME-PERIOD}}.
553
554===== time-period-end
555
556<procedure>(time-period-end TIME-PERIOD) -> time</procedure>
557
558Returns the end time for the {{TIME-PERIOD}}.
559
560===== time-period-last
561
562<procedure>(time-period-last TIME-PERIOD) -> time</procedure>
563
564Returns the last time for the {{TIME-PERIOD}}; {{(time-period-end - TIME-FINE-GRAIN)}}.
565
566===== time-period-type
567
568<procedure>(time-period-type TIME-PERIOD) -> symbol</procedure>
569
570Returns the clock-type of the {{TIME-PERIOD}}.
571
572===== time-period?
573
574<procedure>(time-period? OBJECT) -> boolean</procedure>
575
576Is {{OBJECT}} a time-period?
577
578===== time-period-length
579
580<procedure>(time-period-length TIME-PERIOD) -> time</procedure>
581
582Returns the time-duration of the {{TIME-PERIOD}}.
583
584===== time-period-compare
585
586<procedure>(time-period-compare TIME-PERIOD-1 TIME-PERIOD-2) -> integer</procedure>
587
588Returns {{-1}} when {{TIME-PERIOD-1}} < {{TIME-PERIOD-2}}, {{0}} when
589{{TIME-PERIOD-1}} = {{TIME-PERIOD-2}} and {{1}} {{TIME-PERIOD-1}} >
590{{TIME-PERIOD-2}}.
591
592===== time-period=?
593
594<procedure>(time-period=? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
595
596Does {{TIME-PERIOD-1}} begin & end with {{TIME-PERIOD-2}}?
597
598===== time-period<?
599
600<procedure>(time-period<? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
601
602Does {{TIME-PERIOD-1}} end before {{TIME-PERIOD-2}} begins?
603
604===== time-period>?
605
606<procedure>(time-period>? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
607
608Does {{TIME-PERIOD-1}} begin after {{TIME-PERIOD-2}} ends?
609
610===== time-period<=?
611
612<procedure>(time-period<=? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
613
614Does {{TIME-PERIOD-1}} end on or before {{TIME-PERIOD-2}} begins?
615
616===== time-period>=?
617
618<procedure>(time-period>=? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
619
620Does {{TIME-PERIOD-1}} begin on or after {{TIME-PERIOD-2}} ends?
621
622===== time-period-preceding
623
624<procedure>(time-period-preceding TIME-PERIOD-1 TIME-PERIOD-2) -> (or boolean time-period)</procedure>
625
626Return the portion of {{TIME-PERIOD-1}} before {{TIME-PERIOD-2}} or {{#f}} when
627it doesn't precede.
628
629===== time-period-succeeding
630
631<procedure>(time-period-succeeding TIME-PERIOD-1 TIME-PERIOD-2) -> (or boolean time-period)</procedure>
632
633Return the portion of {{TIME-PERIOD-1}} after {{TIME-PERIOD-2}} or {{#f}} when
634it doesn't succeed.
635
636===== time-period-contains/period?
637
638<procedure>(time-period-contains/period? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
639
640Is {{TIME-PERIOD-2}} within {{TIME-PERIOD-1}}?
641
642===== time-period-contains/time?
643
644<procedure>(time-period-contains/time? TIME-PERIOD TIME) -> boolean</procedure>
645
646Is {{TIME}} within {{TIME-PERIOD}}?
647
648{{TIME}} is converted to a compatible clock-type if possible.
649
650===== time-period-contains/date?
651
652<procedure>(time-period-contains/date? TIME-PERIOD DATE) -> boolean</procedure>
653
654Is {{DATE}} within {{TIME-PERIOD}}?
655
656{{DATE}} is converted to a compatible time if possible.
657
658===== time-period-contains?
659
660<procedure>(time-period-contains? TIME-PERIOD OBJECT) -> boolean</procedure>
661
662Is {{OBJECT}} within {{TIME-PERIOD}}?
663
664{{OBJECT}} maybe a time, date, or time-period.
665
666===== time-period-intersects?
667
668<procedure>(time-period-intersects? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
669
670Does {{TIME-PERIOD-2}} overlap {{TIME-PERIOD-1}}?
671
672===== time-period-intersection
673
674<procedure>(time-period-intersection TIME-PERIOD-1 TIME-PERIOD-2) -> (or boolean time-period)</procedure>
675
676The overlapping time-period of {{TIME-PERIOD-2}} and {{TIME-PERIOD-1}}, or
677{{#f}} when no overlap.
678
679===== time-period-union
680
681<procedure>(time-period-union TIME-PERIOD-1 TIME-PERIOD-2) -> (or boolean time-period)</procedure>
682
683Returns the time-period spanned by {{TIME-PERIOD-1}} and {{TIME-PERIOD-2}}, or
684{{#f}} when they do not intersect.
685
686===== time-period-span
687
688<procedure>(time-period-span TIME-PERIOD-1 TIME-PERIOD-2) -> time-period</procedure>
689
690Returns the time-period spanned by {{TIME-PERIOD-1}} and {{TIME-PERIOD-2}},
691including any gaps.
692
693===== time-period-shift
694
695<procedure>(time-period-shift TIME-PERIOD DURATION) -> time-period</procedure>
696
697Returns a copy of {{TIME-PERIOD}} shifted by {{DURATION}}.
698
699===== time-period-shift!
700
701<procedure>(time-period-shift! TIME-PERIOD DURATION) -> time-period</procedure>
702
703Returns {{TIME-PERIOD}} shifted by {{DURATION}}.
704
705
706== Usage
707
708* This module exports the time, date, timezone, and io APIs.
709
710<enscript language=scheme>
711(require-extension srfi-19)
712</enscript>
713
714
715== Examples
716
717* Prevent default timezone initialization by explicitly setting the 'timezone.
718
719<enscript language=scheme>
720;must be done before 1st invocation of a srfi-19 export
721(use locale)
722(set-locale-category! 'timezone
723  (posix-timezone-string->timezone-components
724    ;some acceptable posix tz form
725    "XSX+2:00XDX+1:00:00"
726    ;source of tz info
727    '("POSIX" "TZ")))
728
729;now we can use srfi-19 in our runtime tz
730(use srfi-19 extras)
731(format #t "Present Day: ~A~%Present Time: ~A~%: Hah, hah, hah.~%"
732  (current-date) (current-time))
733</enscript>
734
735
736== Notes
737
738* The {{string->date}} and {{scan-date}} procedures will not create an
739''incomplete'' date. At a minimum the input must include day, month and year
740components; the time and timezone components default to 0 and the locale,
741respectively.
742
743* 31 December 1 BCE + 1 day -> 1 January 1 CE. There is no year 0. Unlike the
744ISO 8601 convention do not subtract 1 when converting a year BCE to a SRFI-19
745year, just negate the year.
746
747* The SRFI-18 {{current-time}} and {{time?}} bindings conflict with SRFI-19
748bindings.
749
750* A SRFI-18 time object is not accepted except by the conversion procedures.
751
752* The expression {{(time=? (seconds->time (nanoseconds->seconds
753(time->nanoseconds <time-duration>))) <time-duration>)}} might be {{#f}}, due
754to the use of inexact arithmetic.
755
756* Be careful using the procedures that return some form of 'julian-day'. These are
757implemented using the full numeric tower and '''will''' return rational numbers.
758Performing arithmetic with such a result will require the "numbers" egg. See the
759file "srfi-19-test.scm" in this egg for an example. This will be a problem with
760code that assumes fixnum and/or flonum '''only''' numbers. Perhaps an intermediate
761file that wraps any 'julian-day' calls and coerces to an inexact number. Use the
762wrapped 'julian-day' call in the problematic code.
763
764
765== Bugs and Limitations
766
767* Local timezone information is not necessarily valid for historic dates and
768problematic for future dates. Daylight saving time is especially an issue.
769Conversion of a time or seconds value to a local date will use the current
770timezone offset value. The current offset will reflect the daylight saving time
771status. So target dates outside of the DST period will be converted
772incorrectly!
773
774* Will not read years less than 1 properly. The ISO 8601 year convention for
775years 1 BCE and before and years 10000 CE and after is not supported.
776
777* Cannot swap SRFI 29 bundle. Fixed at load time.
778
779* Using {{date-adjust}} for the same {{date-key}} MomentJS says:
780
781If you are adding hours, minutes, seconds, or milliseconds, the assumption is
782that you want precision to the hour, and will result in a different hour.
783
784<enscript language=javascript>
785var m = moment(new Date(2011, 2, 12, 5, 0, 0)); // the day before DST in the US
786m.hours(); // 5
787m.add(24, 'hours').hours(); // 6
788</enscript>
789
790but this implementation says 1 day = 24 hours, so same hour.
791
792
793== Requirements
794
795[[locale]]
796[[srfi-29]]
797[[miscmacros]]
798[[numbers]]
799[[check-errors]]
800[[record-variants]]
801
802
803== Author
804
805[[/users/kon-lovett|Kon Lovett]]
806
807
808== Version history
809
810; 3.6.0 : Delay locale initialization.
811; 3.5.0 : Document {{time-record-printer-format}} & {{date-record-printer-format}}.
812; 3.4.3 : Fix #1000(?).
813; 3.4.2 : .
814; 3.4.1 : fix nanosecond squared value in date
815; 3.4.0 : add {{TIME-FINE-GRAIN}}, generalize {{make-time}}, add {{date-adjust}}.
816; 3.3.6 : Update leap second table.
817; 3.3.5 :
818; 3.3.4 : Fix for ticket #630.
819; 3.3.3 : Fix for weekday name indexing, ticket #966.
820; 3.3.2 : Fix for removed ##sys#double->number.
821; 3.3.1 : Fix for {{time-monotonic->julian-day}} return, ticket #829.
822; 3.3.0 : Uses compiled ''setup-helper-mod''.
823; 3.2.0 : Removed ''null'' time-period.
824; 3.1.2 : Fix for flonum {{(current-milliseconds)}}. Fix for {{date-add/subtract-duration}} (actually {{time->date}} support for {{date-timezone-info}}). [Reported by Thomas Hintz]
825; 3.1.1 : Bug fix for non-unique month name key for ''May''. Added padding character override information. The {{ZONE-OFFSET}} argument of {{make-date}} is optional. Added German bundle by Moritz Heidkamp.
826; 3.1.0 : Use of record-variants extension.
827; 3.0.3 : Bug fix for missing {{seconds->time}} & {{seconds->date}} in {{srfi-19}}. (Reported by Alex Suraci)
828; 3.0.2 : Bug fix for {{format-date}} output port check, {{format-date}} and {{scan-date}} argument type checks.
829; 3.0.1 : Bug fix for ~y input conversion.
830; 3.0.0 : Initial Chicken 4 release
831
832== License
833
834Copyright (C) 2009-2017 Kon Lovett.  All rights reserved.
835
836Permission is hereby granted, free of charge, to any person obtaining a
837copy of this software and associated documentation files (the Software),
838to deal in the Software without restriction, including without limitation
839the rights to use, copy, modify, merge, publish, distribute, sublicense,
840and/or sell copies of the Software, and to permit persons to whom the
841Software is furnished to do so, subject to the following conditions:
842
843The above copyright notice and this permission notice shall be included
844in all copies or substantial portions of the Software.
845
846THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
847IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
848FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
849THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
850OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
851ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
852OTHER DEALINGS IN THE SOFTWARE.
853
854Copyright (C) I/NET, Inc. (2000, 2002, 2003). All Rights Reserved.
855Copyright (C) Neodesic Corporation (2000). All Rights Reserved.
856
857This document and translations of it may be copied and furnished to others,
858and derivative works that comment on or otherwise explain it or assist in its
859implementation may be prepared, copied, published and distributed, in whole or
860in part, without restriction of any kind, provided that the above copyright
861notice and this paragraph are included on all such copies and derivative works.
862However, this document itself may not be modified in any way, such as by
863removing the copyright notice or references to the Scheme Request For
864Implementation process or editors, except as needed for the purpose of
865developing SRFIs in which case the procedures for copyrights defined in the SRFI
866process must be followed, or as required to translate it into languages other
867than English.
868
869The limited permissions granted above are perpetual and will not be revoked
870by the authors or their successors or assigns.
871
872This document and the information contained herein is provided on an "AS IS"
873basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL WARRANTIES, EXPRESS OR
874IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
875INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
876MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Note: See TracBrowser for help on using the repository browser.