source: project/wiki/eggref/5/srfi-19 @ 38114

Last change on this file since 38114 was 38114, checked in by Kon Lovett, 5 weeks ago

rel 4.1.0

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