Outdated egg!
This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.
If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.
srfi-19
Time Data Types and Procedures
TOC »
- Outdated egg!
- srfi-19
- Documentation
- Core Procedures
- Input/Output Procedures
- Time Period
- Usage
- make-time-period
- copy-time-period
- time-period-begin
- time-period-end
- time-period-last
- time-period-type
- time-period?
- time-period-length
- time-period-compare
- time-period=?
- time-period<?
- time-period>?
- time-period<=?
- time-period>=?
- time-period-preceding
- time-period-succeeding
- time-period-contains/period?
- time-period-contains/time?
- time-period-contains/date?
- time-period-contains?
- time-period-intersects?
- time-period-intersection
- time-period-union
- time-period-span
- time-period-shift
- time-period-shift!
- Usage
- Usage
- Examples
- Notes
- Bugs and Limitations
- Requirements
- Author
- Version history
- License
Documentation
This is a Chicken port of SRFI-19. This document only describes the extensions. For the SRFI-19 API see SRFI-19.
Core Procedures
The core procedures are those pertaining to time, date, and timezone:
(require-extension srfi-19-core)
The core procedures can be separately accessed:
(require-extension srfi-19-time)
(require-extension srfi-19-date)
(require-extension srfi-19-timezone)
(require-extension srfi-19-io)
SRFI-19 Document Changes
The nanosecond time object element is an integer between 0 and 999,999,999 inclusive. (The SRFI-19 document mis-states the value.)
A tz-offset value follows ISO 8601; positive for east of UTC, and negative for west. This is the opposite of the POSIX TZ environment variable.
Where the SRFI-19 document states a tz-offset argument a timezone-components object is also legal.
The string->date 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.
make-date
- make-date NANOSECOND SECOND MINUTE HOUR DAY MONTH YEAR #!optional ZONE-OFFSET TZ-NAME DST-FLAGprocedure
Same as SRFI-19 except for the optional parameters and allowing a timezone-components object for the ZONE-OFFSET.
The ZONE-OFFSET is an integer or timezone-components. Default is the (timezone-locale-offset), the current locale timezone offset.
The TZ-NAME is a string or #f, and is the timezone name. Default is #f.
The DST-FLAG is a boolean, and indicates whether Day Saving TIme (or Summer Time) is active. Default is #f.
When the ZONE-OFFSET is a timezone-components object the TZ-NAME and DST-FLAG are pulled from the timezone-components, unless explicitly supplied.
read-leap-second-table
- read-leap-second-table FILENAMEprocedure
Sets the leap second table from the specified FILENAME.
The file format is the same as the "tai-utc.dat" file in the distribution. Provided by the U.S. Naval Observatory.
leap-year?
- leap-year? DATEprocedure
Does the specified DATE fall on a leap year?
The DATE may be a numeric year or a date object.
SRFI-18 Time
Note that the SRFI-18 identifiers time?, current-time, seconds->time, time->seconds, milliseconds->time, and time->milliseconds are in conflict with those of SRFI-19.
time->srfi-18-time
- time->srfi-18-time TIMEprocedure
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.
srfi-18-time->time
- srfi-18-time->time TIMEprocedure
Converts a SRFI-18 time object into a SRFI-19 time-duration object.
Object Printing
time-record-printer-format
- time-record-printer-format #!optional FORMprocedure
FORM is 'srfi-10 or '#f.
date-record-printer-format
- date-record-printer-format #!optional FORMprocedure
FORM is 'srfi-10 or '#f.
Time Conversion
seconds->time
- (seconds->time SECONDS [TIME-TYPE time-duration]) -> timeprocedure
Converts a SECONDS value, may be fractional, into a TIME-TYPE time object.
seconds->date
- (seconds->date SECONDS [TIMEZONE-INFO #t]) -> dateprocedure
Converts a SECONDS value, which may be fractional, into a date object. The TIMEZONE-INFO is #t for the local timezone, #f for the utc timezone, or a timezone-components object.
SECONDS is relative to 00:00:00 January 1, 1970 UTC.
time->nanoseconds
- time->nanoseconds TIMEprocedure
Returns the TIME object value as a nanoseconds value.
nanoseconds->time
- (nanoseconds->time NANOSECONDS [TIME-TYPE time-duration]) -> timeprocedure
Returns the NANOSECONDS value as a time TIME-TYPE object.
nanoseconds->seconds
- nanoseconds->seconds NANOSECONDSprocedure
Returns the NANOSECONDS value as an inexact seconds value.
time->milliseconds
- time->milliseconds TIMEprocedure
Returns the TIME object value as a milliseconds value.
milliseconds->time
- (milliseconds->time MILLISECONDS [TIME-TYPE time-duration]) -> timeprocedure
Returns the MILLISECONDS value as a time TIME-TYPE object.
milliseconds->seconds
- milliseconds->seconds MILLISECONDSprocedure
Returns the MILLISECONDS value as an inexact seconds value.
time->date
- time->date TIMEprocedure
Returns the TIME object value as a date. A shorthand for the (time-*->date...) procedures.
time->julian-day
- time->julian-day TIMEprocedure
Returns the julian day for the TIME object.
time->modified-julian-day
- time->modified-julian-day TIMEprocedure
Returns the modified julian day for the TIME object.
Time Arithmetic
make-duration
- (make-duration [#:days 0] [#:hours 0] [#:minutes 0] [#:seconds 0] [#:milliseconds 0] [#:microseconds 0] [#:nanoseconds 0]) -> timeprocedure
Returns a time-object of clock-type time-duration where the seconds and nanoseconds values are calculated by summing the keyword arguments.
one-second-duration
- one-second-durationprocedure
one-nanosecond-duration
- one-nanosecond-durationprocedure
zero-time
TIME-FINE-GRAIN
Most minimum positive amount of time, as a duration.
divide-duration
- divide-duration DURATION NUMBERprocedure
Returns a duration, from DURATION, divided by NUMBER, without remainder.
divide-duration!
- divide-duration! DURATION NUMBERprocedure
Returns DURATION, divided by NUMBER, without remainder.
multiply-duration
- multiply-duration DURATION NUMBERprocedure
Returns a duration, from DURATION, multiplied by NUMBER, truncated.
multiply-duration!
- multiply-duration! DURATION NUMBERprocedure
Returns DURATION, multiplied by NUMBER, truncated.
time-negative?
- time-negative? TIMEprocedure
Is TIME negative?
A time object will never have a negative nanoseconds value.
time-positve?
- time-positve? TIMEprocedure
Is TIME positive?
time-zero?
- time-zero? TIMEprocedure
Is TIME zero?
time-abs
- time-abs TIMEprocedure
Returns the absolute time value, from TIME.
time-abs!
- time-abs! TIMEprocedure
Returns the absolute TIME value.
time-negate
- time-negate TIMEprocedure
Returns the sign inverted time value, from TIME.
time-negate!
- time-negate! TIMEprocedure
Returns the TIME sign inverted value.
Time Comparison
time-compare
- time-compare TIME1 TIME2procedure
Returns -1, 0, or 1.
time-max
- time-max TIME1 #!optional TIME2...procedure
Returns the maximum time object from TIME1 TIME2....
time-min
- time-min TIME1 #!optional TIME2...procedure
Returns the minimum time object from TIME1 TIME2....
Dates
default-date-clock-type
- (default-date-clock-type [CLOCK-TYPE time-utc]) -> symbolparameter
Sets or gets the clock-type used by default for conversion of a date to a time.
copy-date
- copy-date DATEprocedure
Returns an exact copy of the specified DATE object.
date->seconds
- date->seconds DATE #!optional CLOCK-TYPE default-date-clock-typeprocedure
Returns the specified DATE as as an inexact seconds value, based on the CLOCK-TYPE.
The seconds value is relative to the TAI-EPOCH - 1 January 1970 CE at 00:00:00 UTC.
date->time
- date->time DATE #!optional CLOCK-TYPE default-date-clock-typeprocedure
Returns the specified DATE as a time-object of type CLOCK-TYPE.
date-zone-name
- date-zone-name DATEprocedure
Returns the timezone abbreviation of the specified DATE object. The result is either a string or #f.
date-dst?
- date-dst? DATEprocedure
Returns the daylight saving time flag of the specified DATE object.
Only valid for "current" dates. Historical dates will not have a correct setting. Future dates cannot have a correct setting.
Date Arithmetic
date-difference
- date-difference DATE1 DATE2 #!optional CLOCK-TYPEprocedure
Returns the time-duration between DATE1 and DATE2.
date-add-duration
- date-add-duration DATE DURATION #!optional CLOCK-TYPEprocedure
Returns a new date, the DATE plus the DURATION.
date-subtract-duration
- date-subtract-duration DATE DURATION #!optional CLOCK-TYPEprocedure
Returns a new date, the DATE minus the DURATION.
date-adjust
- date-adjust DATE AMOUNT DATE-KEY #!optional CLOCK-TYPEprocedure
Returns a new date, the DATE adjusted by the AMOUNT of DATE-KEY.
AMOUNT is an integer.
DATE-KEY is either 'years, 'quarters, 'months, 'days, 'hours, 'minutes, 'seconds, 'milliseconds, 'microseconds, or 'nanoseconds.
If the day of the month of DATE is greater than the number of days in the final month, the day of the month will change to the last day in the final month.
Adjusting a time DATE-KEY (ex: 'hours) follows the semantics of date-add-duration.
Date Comparison
date-compare
- date-compare DATE1 DATE2procedure
Returns -1, 0, or 1.
date=?
- date=? DATE1 DATE2procedure
Is DATE1 on DATE2?
date>?
- date>? DATE1 DATE2procedure
Is DATE1 after DATE2?
date<?
- date<? DATE1 DATE2procedure
Is DATE1 before DATE2?
date>=?
- date>=? DATE1 DATE2procedure
Is DATE1 after or on DATE2?
date<=?
- date<=? DATE1 DATE2procedure
Is DATE1 before or on DATE2?
Timezone
- Note that the daylight saving time (summer time) flag is always taken from the system, unless supplied. Any summer time rule component of a timezone-components object is not processed.
Remember that SRFI-19 timezone offset follows ISO 8601.
local-timezone-locale
- local-timezone-locale #!optional TZ-COMPONENTSparameter
Gets or sets the local timezone-locale object.
utc-timezone-locale
- utc-timezone-locale #!optional TZ-COMPONENTSparameter
Gets or sets the utc timezone-locale object.
Probably not a good idea to change the value.
timezone-locale-name
- timezone-locale-name #!optional TZ-COMPONENTSprocedure
Returns the timezone-locale name of the supplied TZ-COMPONENTS, or the (local-timezone-locale) if missing.
timezone-locale-offset
- timezone-locale-offset #!optional TZ-COMPONENTSprocedure
Returns the timezone-locale offset of the supplied TZ-COMPONENTS, or the (local-timezone-locale) if missing.
timezone-locale-dst?
- timezone-locale-dst? #!optional TZ-COMPONENTSprocedure
Returns the timezone-locale daylight saving time flag of the supplied TZ-COMPONENTS, or the (local-timezone-locale) if missing.
Input/Output Procedures
(require-extension srfi-19-io)
DATE->STRING conversion specifiers
The SRFI-19 document does not mention the padding character override feature for the normally zero-padded conversions f, H, I, j, m, M, N, S, y. If the tilde is followed by a - then padding is suppressed. If followed by a _ the space character is used for padding. Otherwise zero-padding is perfomed, the default.
~[-_][fHIjmMNSy]
format-date
- format-date DESTINATION DATE-FORMAT-STRING DATEprocedure
Displays a text form of the DATE on the DESTINATION using the DATE-FORMAT-STRING.
When the DESTINATION is #t the (current-output-port) is used, and the date object must be specified.
When the DESTINATION is a port it must be an output-port, and the date object must be specified.
When the DESTINATION is a number the (current-error-port) is the DESTINATION, and the DATE object must be specified.
When the DESTINATION is #f the result is returned as a string, and the DATE object must be specified.
- format-date DATE-FORMAT-STRING DATEprocedure
Result is returned as a string.
scan-date
- scan-date SOURCE TEMPLATE-STRINGprocedure
Reads a text form of a date from the SOURCE, following the TEMPLATE-STRING, and returns a date object.
When the SOURCE is #t the (current-input-port) is used.
When the SOURCE is a port it must be an input-port.
When the SOURCE is string it should be a date text form.
Time Period
Usage
(require-extension srfi-19-period)
A time-period is an interval, [begin end), where begin and end are time objects of the same clock type.
make-time-period
- make-time-period BEGIN END #!optional CLOCK-TYPE default-date-clock-typeprocedure
Returns a new time-period object. The clock types must be compatible.
BEGIN maybe a seconds value, a date, or a time (except time-duration). A seconds value or date are converted to CLOCK-TYPE.
END maybe a seconds value, a date, or a time. A seconds value or date are converted to the same clock type as BEGIN. A time-duration is treated as an offset from BEGIN.
copy-time-period
- copy-time-period TIME-PERIODprocedure
Returns a copy of TIME-PERIOD.
time-period-begin
- time-period-begin TIME-PERIODprocedure
Returns the start time for the TIME-PERIOD.
time-period-end
- time-period-end TIME-PERIODprocedure
Returns the end time for the TIME-PERIOD.
time-period-last
- time-period-last TIME-PERIODprocedure
Returns the last time for the TIME-PERIOD; (time-period-end - TIME-FINE-GRAIN).
time-period-type
- time-period-type TIME-PERIODprocedure
Returns the clock-type of the TIME-PERIOD.
time-period?
- time-period? OBJECTprocedure
Is OBJECT a time-period?
time-period-length
- time-period-length TIME-PERIODprocedure
Returns the time-duration of the TIME-PERIOD.
time-period-compare
- time-period-compare TIME-PERIOD-1 TIME-PERIOD-2procedure
Returns -1 when TIME-PERIOD-1 < TIME-PERIOD-2, 0 when TIME-PERIOD-1 = TIME-PERIOD-2 and 1 TIME-PERIOD-1 > TIME-PERIOD-2.
time-period=?
- time-period=? TIME-PERIOD-1 TIME-PERIOD-2procedure
Does TIME-PERIOD-1 begin & end with TIME-PERIOD-2?
time-period<?
- time-period<? TIME-PERIOD-1 TIME-PERIOD-2procedure
Does TIME-PERIOD-1 end before TIME-PERIOD-2 begins?
time-period>?
- time-period>? TIME-PERIOD-1 TIME-PERIOD-2procedure
Does TIME-PERIOD-1 begin after TIME-PERIOD-2 ends?
time-period<=?
- time-period<=? TIME-PERIOD-1 TIME-PERIOD-2procedure
Does TIME-PERIOD-1 end on or before TIME-PERIOD-2 begins?
time-period>=?
- time-period>=? TIME-PERIOD-1 TIME-PERIOD-2procedure
Does TIME-PERIOD-1 begin on or after TIME-PERIOD-2 ends?
time-period-preceding
- time-period-preceding TIME-PERIOD-1 TIME-PERIOD-2procedure
Return the portion of TIME-PERIOD-1 before TIME-PERIOD-2 or #f when it doesn't precede.
time-period-succeeding
- time-period-succeeding TIME-PERIOD-1 TIME-PERIOD-2procedure
Return the portion of TIME-PERIOD-1 after TIME-PERIOD-2 or #f when it doesn't succeed.
time-period-contains/period?
- time-period-contains/period? TIME-PERIOD-1 TIME-PERIOD-2procedure
Is TIME-PERIOD-2 within TIME-PERIOD-1?
time-period-contains/time?
- time-period-contains/time? TIME-PERIOD TIMEprocedure
Is TIME within TIME-PERIOD?
TIME is converted to a compatible clock-type if possible.
time-period-contains/date?
- time-period-contains/date? TIME-PERIOD DATEprocedure
Is DATE within TIME-PERIOD?
DATE is converted to a compatible time if possible.
time-period-contains?
- time-period-contains? TIME-PERIOD OBJECTprocedure
Is OBJECT within TIME-PERIOD?
OBJECT maybe a time, date, or time-period.
time-period-intersects?
- time-period-intersects? TIME-PERIOD-1 TIME-PERIOD-2procedure
Does TIME-PERIOD-2 overlap TIME-PERIOD-1?
time-period-intersection
- time-period-intersection TIME-PERIOD-1 TIME-PERIOD-2procedure
The overlapping time-period of TIME-PERIOD-2 and TIME-PERIOD-1, or #f when no overlap.
time-period-union
- time-period-union TIME-PERIOD-1 TIME-PERIOD-2procedure
Returns the time-period spanned by TIME-PERIOD-1 and TIME-PERIOD-2, or #f when they do not intersect.
time-period-span
- time-period-span TIME-PERIOD-1 TIME-PERIOD-2procedure
Returns the time-period spanned by TIME-PERIOD-1 and TIME-PERIOD-2, including any gaps.
time-period-shift
- time-period-shift TIME-PERIOD DURATIONprocedure
Returns a copy of TIME-PERIOD shifted by DURATION.
time-period-shift!
- time-period-shift! TIME-PERIOD DURATIONprocedure
Returns TIME-PERIOD shifted by DURATION.
Usage
- This module exports the time, date, timezone, and io APIs.
(require-extension srfi-19)
Examples
- Prevent default timezone initialization by explicitly setting the 'timezone.
;must be done before 1st invocation of a srfi-19 export (use locale) (set-locale-category! 'timezone (posix-timezone-string->timezone-components ;some acceptable posix tz form "XSX+2:00XDX+1:00:00" ;source of tz info '("POSIX" "TZ"))) ;now we can use srfi-19 in our runtime tz (use srfi-19 extras) (format #t "Present Day: ~A~%Present Time: ~A~%: Hah, hah, hah.~%" (current-date) (current-time))
Notes
- The string->date and scan-date procedures will not create an incomplete date. At a minimum the input must include day, month and year components; the time and timezone components default to 0 and the locale, respectively.
- 31 December 1 BCE + 1 day -> 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.
- The SRFI-18 current-time and time? bindings conflict with SRFI-19 bindings.
- A SRFI-18 time object is not accepted except by the conversion procedures.
- The expression (time=? (seconds->time (nanoseconds->seconds (time->nanoseconds <time-duration>))) <time-duration>) might be #f, due to the use of inexact arithmetic.
- Be careful using the procedures that return some form of 'julian-day'. These are implemented using the full numeric tower and will return rational numbers. Performing arithmetic with such a result will require the "numbers" egg. See the file "srfi-19-test.scm" in this egg for an example. This will be a problem with code that assumes fixnum and/or flonum only 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.
Bugs and Limitations
- 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!
- 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.
- Cannot swap SRFI 29 bundle. Fixed at load time.
- Using date-adjust for the same date-key MomentJS says:
If you are adding hours, minutes, seconds, or milliseconds, the assumption is that you want precision to the hour, and will result in a different hour.
var m = moment(new Date(2011, 2, 12, 5, 0, 0)); // the day before DST in the US m.hours(); // 5 m.add(24, 'hours').hours(); // 6
but this implementation says 1 day = 24 hours, so same hour.
Requirements
locale srfi-29 miscmacros numbers check-errors record-variants
Author
Version history
- 3.7.0
- Added date->seconds.
- 3.6.0
- Delay locale initialization.
- 3.5.0
- Document time-record-printer-format & date-record-printer-format.
- 3.4.3
- Fix #1000(?).
- 3.4.2
- .
- 3.4.1
- fix nanosecond squared value in date
- 3.4.0
- add TIME-FINE-GRAIN, generalize make-time, add date-adjust.
- 3.3.6
- Update leap second table.
- 3.3.5
- 3.3.4
- Fix for ticket #630.
- 3.3.3
- Fix for weekday name indexing, ticket #966.
- 3.3.2
- Fix for removed ##sys#double->number.
- 3.3.1
- Fix for time-monotonic->julian-day return, ticket #829.
- 3.3.0
- Uses compiled setup-helper-mod.
- 3.2.0
- Removed null time-period.
- 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]
- 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.
- 3.1.0
- Use of record-variants extension.
- 3.0.3
- Bug fix for missing seconds->time & seconds->date in srfi-19. (Reported by Alex Suraci)
- 3.0.2
- Bug fix for format-date output port check, format-date and scan-date argument type checks.
- 3.0.1
- Bug fix for ~y input conversion.
- 3.0.0
- Initial Chicken 4 release
License
Copyright (C) 2009-2018 Kon Lovett. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright (C) I/NET, Inc. (2000, 2002, 2003). All Rights Reserved. Copyright (C) Neodesic Corporation (2000). All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Scheme Request For Implementation process or editors, except as needed for the purpose of developing SRFIs in which case the procedures for copyrights defined in the SRFI process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the authors or their successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.