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

Last change on this file since 35737 was 35737, checked in by kon, 10 months ago

rel 3.7.0

File size: 25.9 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) -> number</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) -> number</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->seconds
325
326<procedure>(date->seconds DATE [CLOCK-TYPE (default-date-clock-type)]) -> number</procedure>
327
328Returns the specified {{DATE}} as as an inexact seconds value, based on the
329{{CLOCK-TYPE}}.
330
331The seconds value is relative to the ''TAI-EPOCH'' - 1 January 1970 CE at
33200:00:00 UTC.
333
334===== date->time
335
336<procedure>(date->time DATE [CLOCK-TYPE (default-date-clock-type)]) -> time</procedure>
337
338Returns the specified {{DATE}} as a time-object of type {{CLOCK-TYPE}}.
339
340===== date-zone-name
341
342<procedure>(date-zone-name DATE) -> (or boolean string)</procedure>
343
344Returns the timezone abbreviation of the specified {{DATE}} object. The result
345is either a string or {{#f}}.
346
347===== date-dst?
348
349<procedure>(date-dst? DATE) -> boolean</procedure>
350
351Returns the daylight saving time flag of the specified {{DATE}} object.
352
353Only valid for "current" dates. Historical dates will not have a correct
354setting. Future dates cannot have a correct setting.
355
356==== Date Arithmetic
357
358===== date-difference
359
360<procedure>(date-difference DATE1 DATE2 [CLOCK-TYPE]) -> time</procedure>
361
362Returns the {{time-duration}} between {{DATE1}} and {{DATE2}}.
363
364===== date-add-duration
365
366<procedure>(date-add-duration DATE DURATION [CLOCK-TYPE]) -> date</procedure>
367
368Returns a new date, the {{DATE}} plus the {{DURATION}}.
369
370===== date-subtract-duration
371
372<procedure>(date-subtract-duration DATE DURATION [CLOCK-TYPE]) -> date</procedure>
373
374Returns a new date, the {{DATE}} minus the {{DURATION}}.
375
376===== date-adjust
377
378<procedure>(date-adjust DATE AMOUNT DATE-KEY [CLOCK-TYPE]) -> date</procedure>
379
380Returns a new date, the {{DATE}} adjusted by the {{AMOUNT}} of {{DATE-KEY}}.
381
382{{AMOUNT}} is an {{integer}}.
383
384{{DATE-KEY}} is either {{'years}}, {{'quarters}}, {{'months}}, {{'days}},
385{{'hours}}, {{'minutes}}, {{'seconds}}, {{'milliseconds}}, {{'microseconds}},
386or {{'nanoseconds}}.
387
388If the day of the month of {{DATE}} is greater than the number of
389days in the final month, the day of the month will change to the last day in
390the final month.
391
392Adjusting a time {{DATE-KEY}} (ex: {{'hours}}) follows the semantics of
393{{date-add-duration}}.
394
395==== Date Comparison
396
397===== date-compare
398
399<procedure>(date-compare DATE1 DATE2) -> integer</procedure>
400
401Returns -1, 0, or 1.
402
403===== date=?
404
405<procedure>(date=? DATE1 DATE2) -> boolean</procedure>
406
407Is {{DATE1}} on {{DATE2}}?
408
409===== date>?
410
411<procedure>(date>? DATE1 DATE2) -> boolean</procedure>
412
413Is {{DATE1}} after {{DATE2}}?
414
415===== date<?
416
417<procedure>(date<? DATE1 DATE2) -> boolean</procedure>
418
419Is {{DATE1}} before {{DATE2}}?
420
421===== date>=?
422
423<procedure>(date>=? DATE1 DATE2) -> boolean</procedure>
424
425Is {{DATE1}} after or on {{DATE2}}?
426
427===== date<=?
428
429<procedure>(date<=? DATE1 DATE2) -> boolean</procedure>
430
431Is {{DATE1}} before or on {{DATE2}}?
432
433==== Timezone
434
435* Note that the daylight saving time (summer time) flag is '''always''' taken
436from the system, unless supplied. Any summer time rule component of a
437{{timezone-components}} object is '''not''' processed.
438
439Remember that SRFI-19 timezone offset follows ISO 8601.
440
441===== local-timezone-locale
442
443<parameter>(local-timezone-locale [TZ-COMPONENTS])</parameter>
444
445Gets or sets the local timezone-locale object.
446
447===== utc-timezone-locale
448
449<parameter>(utc-timezone-locale [TZ-COMPONENTS])</parameter>
450
451Gets or sets the utc timezone-locale object.
452
453Probably not a good idea to change the value.
454
455===== timezone-locale-name
456
457<procedure>(timezone-locale-name [TZ-COMPONENTS]) -> symbol</procedure>
458
459Returns the timezone-locale name of the supplied {{TZ-COMPONENTS}}, or the
460{{(local-timezone-locale)}} if missing.
461
462===== timezone-locale-offset
463
464<procedure>(timezone-locale-offset [TZ-COMPONENTS]) -> integer</procedure>
465
466Returns the timezone-locale offset of the supplied {{TZ-COMPONENTS}}, or the
467{{(local-timezone-locale)}} if missing.
468
469===== timezone-locale-dst?
470
471<procedure>(timezone-locale-dst? [TZ-COMPONENTS]) -> boolean</procedure>
472
473Returns the timezone-locale daylight saving time flag of the supplied
474{{TZ-COMPONENTS}}, or the {{(local-timezone-locale)}} if missing.
475
476=== Input/Output Procedures
477
478<enscript language=scheme>
479(require-extension srfi-19-io)
480</enscript>
481
482==== DATE->STRING conversion specifiers
483
484The SRFI-19 document does not mention the padding character override feature
485for the normally zero-padded conversions {{f}}, {{H}}, {{I}}, {{j}}, {{m}},
486{{M}}, {{N}}, {{S}}, {{y}}. If the tilde is followed by a {{-}} then padding
487is suppressed. If followed by a {{_}} the space character is used for padding.
488Otherwise zero-padding is perfomed, the default.
489
490~[-_][fHIjmMNSy]
491
492===== format-date
493
494<procedure>(format-date DESTINATION DATE-FORMAT-STRING DATE)</procedure>
495
496Displays a text form of the {{DATE}} on the {{DESTINATION}} using the
497{{DATE-FORMAT-STRING}}.
498
499When the {{DESTINATION}} is {{#t}} the {{(current-output-port)}} is used, and the
500date object must be specified.
501
502When the {{DESTINATION}} is a port it must be an {{output-port}}, and the date
503object must be specified.
504
505When the {{DESTINATION}} is a number the {{(current-error-port)}} is the
506{{DESTINATION}}, and the {{DATE}} object must be specified.
507
508When the {{DESTINATION}} is {{#f}} the result is returned as a string, and the
509{{DATE}} object must be specified.
510
511<procedure>(format-date DATE-FORMAT-STRING DATE) -> {{string}}</procedure>
512
513Result is returned as a string.
514
515===== scan-date
516
517<procedure>(scan-date SOURCE TEMPLATE-STRING)</procedure>
518
519Reads a text form of a date from the {{SOURCE}}, following the
520{{TEMPLATE-STRING}}, and returns a date object.
521
522When the {{SOURCE}} is {{#t}} the {{(current-input-port)}} is used.
523
524When the {{SOURCE}} is a port it must be an {{input-port}}.
525
526When the {{SOURCE}} is string it should be a date text form.
527
528=== Time Period
529
530==== Usage
531
532<enscript language=scheme>
533(require-extension srfi-19-period)
534</enscript>
535
536A time-period is an interval, [begin end), where begin and end are time objects
537of the same clock type.
538
539===== make-time-period
540
541<procedure>(make-time-period BEGIN END [CLOCK-TYPE (default-date-clock-type)]) -> time-period</procedure>
542
543Returns a new time-period object. The clock types must be compatible.
544
545{{BEGIN}} maybe a seconds value, a date, or a time (except time-duration). A
546seconds value or date are converted to {{CLOCK-TYPE}}.
547
548{{END}} maybe a seconds value, a date, or a time. A seconds value or date are
549converted to the same clock type as {{BEGIN}}. A time-duration is treated as an
550offset from {{BEGIN}}.
551
552===== copy-time-period
553
554<procedure>(copy-time-period TIME-PERIOD) -> time-period</procedure>
555
556Returns a copy of {{TIME-PERIOD}}.
557
558===== time-period-begin
559
560<procedure>(time-period-begin TIME-PERIOD)</procedure>
561
562Returns the start time for the {{TIME-PERIOD}}.
563
564===== time-period-end
565
566<procedure>(time-period-end TIME-PERIOD) -> time</procedure>
567
568Returns the end time for the {{TIME-PERIOD}}.
569
570===== time-period-last
571
572<procedure>(time-period-last TIME-PERIOD) -> time</procedure>
573
574Returns the last time for the {{TIME-PERIOD}}; {{(time-period-end - TIME-FINE-GRAIN)}}.
575
576===== time-period-type
577
578<procedure>(time-period-type TIME-PERIOD) -> symbol</procedure>
579
580Returns the clock-type of the {{TIME-PERIOD}}.
581
582===== time-period?
583
584<procedure>(time-period? OBJECT) -> boolean</procedure>
585
586Is {{OBJECT}} a time-period?
587
588===== time-period-length
589
590<procedure>(time-period-length TIME-PERIOD) -> time</procedure>
591
592Returns the time-duration of the {{TIME-PERIOD}}.
593
594===== time-period-compare
595
596<procedure>(time-period-compare TIME-PERIOD-1 TIME-PERIOD-2) -> integer</procedure>
597
598Returns {{-1}} when {{TIME-PERIOD-1}} < {{TIME-PERIOD-2}}, {{0}} when
599{{TIME-PERIOD-1}} = {{TIME-PERIOD-2}} and {{1}} {{TIME-PERIOD-1}} >
600{{TIME-PERIOD-2}}.
601
602===== time-period=?
603
604<procedure>(time-period=? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
605
606Does {{TIME-PERIOD-1}} begin & end with {{TIME-PERIOD-2}}?
607
608===== time-period<?
609
610<procedure>(time-period<? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
611
612Does {{TIME-PERIOD-1}} end before {{TIME-PERIOD-2}} begins?
613
614===== time-period>?
615
616<procedure>(time-period>? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
617
618Does {{TIME-PERIOD-1}} begin after {{TIME-PERIOD-2}} ends?
619
620===== time-period<=?
621
622<procedure>(time-period<=? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
623
624Does {{TIME-PERIOD-1}} end on or before {{TIME-PERIOD-2}} begins?
625
626===== time-period>=?
627
628<procedure>(time-period>=? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
629
630Does {{TIME-PERIOD-1}} begin on or after {{TIME-PERIOD-2}} ends?
631
632===== time-period-preceding
633
634<procedure>(time-period-preceding TIME-PERIOD-1 TIME-PERIOD-2) -> (or boolean time-period)</procedure>
635
636Return the portion of {{TIME-PERIOD-1}} before {{TIME-PERIOD-2}} or {{#f}} when
637it doesn't precede.
638
639===== time-period-succeeding
640
641<procedure>(time-period-succeeding TIME-PERIOD-1 TIME-PERIOD-2) -> (or boolean time-period)</procedure>
642
643Return the portion of {{TIME-PERIOD-1}} after {{TIME-PERIOD-2}} or {{#f}} when
644it doesn't succeed.
645
646===== time-period-contains/period?
647
648<procedure>(time-period-contains/period? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
649
650Is {{TIME-PERIOD-2}} within {{TIME-PERIOD-1}}?
651
652===== time-period-contains/time?
653
654<procedure>(time-period-contains/time? TIME-PERIOD TIME) -> boolean</procedure>
655
656Is {{TIME}} within {{TIME-PERIOD}}?
657
658{{TIME}} is converted to a compatible clock-type if possible.
659
660===== time-period-contains/date?
661
662<procedure>(time-period-contains/date? TIME-PERIOD DATE) -> boolean</procedure>
663
664Is {{DATE}} within {{TIME-PERIOD}}?
665
666{{DATE}} is converted to a compatible time if possible.
667
668===== time-period-contains?
669
670<procedure>(time-period-contains? TIME-PERIOD OBJECT) -> boolean</procedure>
671
672Is {{OBJECT}} within {{TIME-PERIOD}}?
673
674{{OBJECT}} maybe a time, date, or time-period.
675
676===== time-period-intersects?
677
678<procedure>(time-period-intersects? TIME-PERIOD-1 TIME-PERIOD-2) -> boolean</procedure>
679
680Does {{TIME-PERIOD-2}} overlap {{TIME-PERIOD-1}}?
681
682===== time-period-intersection
683
684<procedure>(time-period-intersection TIME-PERIOD-1 TIME-PERIOD-2) -> (or boolean time-period)</procedure>
685
686The overlapping time-period of {{TIME-PERIOD-2}} and {{TIME-PERIOD-1}}, or
687{{#f}} when no overlap.
688
689===== time-period-union
690
691<procedure>(time-period-union TIME-PERIOD-1 TIME-PERIOD-2) -> (or boolean time-period)</procedure>
692
693Returns the time-period spanned by {{TIME-PERIOD-1}} and {{TIME-PERIOD-2}}, or
694{{#f}} when they do not intersect.
695
696===== time-period-span
697
698<procedure>(time-period-span TIME-PERIOD-1 TIME-PERIOD-2) -> time-period</procedure>
699
700Returns the time-period spanned by {{TIME-PERIOD-1}} and {{TIME-PERIOD-2}},
701including any gaps.
702
703===== time-period-shift
704
705<procedure>(time-period-shift TIME-PERIOD DURATION) -> time-period</procedure>
706
707Returns a copy of {{TIME-PERIOD}} shifted by {{DURATION}}.
708
709===== time-period-shift!
710
711<procedure>(time-period-shift! TIME-PERIOD DURATION) -> time-period</procedure>
712
713Returns {{TIME-PERIOD}} shifted by {{DURATION}}.
714
715
716== Usage
717
718* This module exports the time, date, timezone, and io APIs.
719
720<enscript language=scheme>
721(require-extension srfi-19)
722</enscript>
723
724
725== Examples
726
727* Prevent default timezone initialization by explicitly setting the 'timezone.
728
729<enscript language=scheme>
730;must be done before 1st invocation of a srfi-19 export
731(use locale)
732(set-locale-category! 'timezone
733  (posix-timezone-string->timezone-components
734    ;some acceptable posix tz form
735    "XSX+2:00XDX+1:00:00"
736    ;source of tz info
737    '("POSIX" "TZ")))
738
739;now we can use srfi-19 in our runtime tz
740(use srfi-19 extras)
741(format #t "Present Day: ~A~%Present Time: ~A~%: Hah, hah, hah.~%"
742  (current-date) (current-time))
743</enscript>
744
745
746== Notes
747
748* The {{string->date}} and {{scan-date}} procedures will not create an
749''incomplete'' date. At a minimum the input must include day, month and year
750components; the time and timezone components default to 0 and the locale,
751respectively.
752
753* 31 December 1 BCE + 1 day -> 1 January 1 CE. There is no year 0. Unlike the
754ISO 8601 convention do not subtract 1 when converting a year BCE to a SRFI-19
755year, just negate the year.
756
757* The SRFI-18 {{current-time}} and {{time?}} bindings conflict with SRFI-19
758bindings.
759
760* A SRFI-18 time object is not accepted except by the conversion procedures.
761
762* The expression {{(time=? (seconds->time (nanoseconds->seconds
763(time->nanoseconds <time-duration>))) <time-duration>)}} might be {{#f}}, due
764to the use of inexact arithmetic.
765
766* Be careful using the procedures that return some form of 'julian-day'. These are
767implemented using the full numeric tower and '''will''' return rational numbers.
768Performing arithmetic with such a result will require the "numbers" egg. See the
769file "srfi-19-test.scm" in this egg for an example. This will be a problem with
770code that assumes fixnum and/or flonum '''only''' numbers. Perhaps an intermediate
771file that wraps any 'julian-day' calls and coerces to an inexact number. Use the
772wrapped 'julian-day' call in the problematic code.
773
774
775== Bugs and Limitations
776
777* Local timezone information is not necessarily valid for historic dates and
778problematic for future dates. Daylight saving time is especially an issue.
779Conversion of a time or seconds value to a local date will use the current
780timezone offset value. The current offset will reflect the daylight saving time
781status. So target dates outside of the DST period will be converted
782incorrectly!
783
784* Will not read years less than 1 properly. The ISO 8601 year convention for
785years 1 BCE and before and years 10000 CE and after is not supported.
786
787* Cannot swap SRFI 29 bundle. Fixed at load time.
788
789* Using {{date-adjust}} for the same {{date-key}} MomentJS says:
790
791If you are adding hours, minutes, seconds, or milliseconds, the assumption is
792that you want precision to the hour, and will result in a different hour.
793
794<enscript language=javascript>
795var m = moment(new Date(2011, 2, 12, 5, 0, 0)); // the day before DST in the US
796m.hours(); // 5
797m.add(24, 'hours').hours(); // 6
798</enscript>
799
800but this implementation says 1 day = 24 hours, so same hour.
801
802
803== Requirements
804
805[[locale]]
806[[srfi-29]]
807[[miscmacros]]
808[[numbers]]
809[[check-errors]]
810[[record-variants]]
811
812
813== Author
814
815[[/users/kon-lovett|Kon Lovett]]
816
817
818== Version history
819
820; 3.7.0 : Added {{date->seconds}}.
821; 3.6.0 : Delay locale initialization.
822; 3.5.0 : Document {{time-record-printer-format}} & {{date-record-printer-format}}.
823; 3.4.3 : Fix #1000(?).
824; 3.4.2 : .
825; 3.4.1 : fix nanosecond squared value in date
826; 3.4.0 : add {{TIME-FINE-GRAIN}}, generalize {{make-time}}, add {{date-adjust}}.
827; 3.3.6 : Update leap second table.
828; 3.3.5 :
829; 3.3.4 : Fix for ticket #630.
830; 3.3.3 : Fix for weekday name indexing, ticket #966.
831; 3.3.2 : Fix for removed ##sys#double->number.
832; 3.3.1 : Fix for {{time-monotonic->julian-day}} return, ticket #829.
833; 3.3.0 : Uses compiled ''setup-helper-mod''.
834; 3.2.0 : Removed ''null'' time-period.
835; 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]
836; 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.
837; 3.1.0 : Use of record-variants extension.
838; 3.0.3 : Bug fix for missing {{seconds->time}} & {{seconds->date}} in {{srfi-19}}. (Reported by Alex Suraci)
839; 3.0.2 : Bug fix for {{format-date}} output port check, {{format-date}} and {{scan-date}} argument type checks.
840; 3.0.1 : Bug fix for ~y input conversion.
841; 3.0.0 : Initial Chicken 4 release
842
843== License
844
845Copyright (C) 2009-2018 Kon Lovett.  All rights reserved.
846
847Permission is hereby granted, free of charge, to any person obtaining a
848copy of this software and associated documentation files (the Software),
849to deal in the Software without restriction, including without limitation
850the rights to use, copy, modify, merge, publish, distribute, sublicense,
851and/or sell copies of the Software, and to permit persons to whom the
852Software is furnished to do so, subject to the following conditions:
853
854The above copyright notice and this permission notice shall be included
855in all copies or substantial portions of the Software.
856
857THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
858IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
859FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
860THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
861OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
862ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
863OTHER DEALINGS IN THE SOFTWARE.
864
865Copyright (C) I/NET, Inc. (2000, 2002, 2003). All Rights Reserved.
866Copyright (C) Neodesic Corporation (2000). All Rights Reserved.
867
868This document and translations of it may be copied and furnished to others,
869and derivative works that comment on or otherwise explain it or assist in its
870implementation may be prepared, copied, published and distributed, in whole or
871in part, without restriction of any kind, provided that the above copyright
872notice and this paragraph are included on all such copies and derivative works.
873However, this document itself may not be modified in any way, such as by
874removing the copyright notice or references to the Scheme Request For
875Implementation process or editors, except as needed for the purpose of
876developing SRFIs in which case the procedures for copyrights defined in the SRFI
877process must be followed, or as required to translate it into languages other
878than English.
879
880The limited permissions granted above are perpetual and will not be revoked
881by the authors or their successors or assigns.
882
883This document and the information contained herein is provided on an "AS IS"
884basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL WARRANTIES, EXPRESS OR
885IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
886INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
887MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Note: See TracBrowser for help on using the repository browser.