You are looking at historical revision 15789 of this page. It may differ significantly from its current revision.
Time Data Types and Procedures
- Core Procedures
- SRFI-19 Document Changes
- SRFI-18 Time
- Time Conversion
- Time Arithmetic
- Time Comparison
- Date Arithmetic
- Date Comparison
- Input/Output Procedures
- Time Period
- Core Procedures
- Bugs and Limitations
- Version history
This is a Chicken port of SRFI-19. This document only describes the extensions. For the SRFI-19 API see SRFI-19.
The core procedures are those pertaining to time, date, and timezone:
The core procedures can be separately accessed:
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[procedure] (make-date NANOSECOND SECOND MINUTE HOUR DAY MONTH YEAR ZONE-OFFSET [TZ-NAME #f] [DST-FLAG #f])
Same as SRFI-19 except for the optional parameters and allowing a timezone-components object for the ZONE-OFFSET.
read-leap-second-table[procedure] (read-leap-second-table FILENAME)
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?[procedure] (leap-year? DATE)
Does the specified DATE fall on a leap year?
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[procedure] (time->srfi-18-time TIME) => SRFI-18:TIME
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[procedure] (srfi-18-time->time => SRFI-18:TIME) => SRFI-19:TIME
Converts a SRFI-18 time object into a SRFI-19 time-duration object.
seconds->time[procedure] (seconds->time SECONDS [TIME-TYPE time-duration])
Converts a SECONDS value, may be fractional, into a TIME-TYPE time object.
Also known as seconds->time/type.
seconds->date[procedure] (seconds->date SECONDS [TIMEZONE-INFO #f])
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.
Also known as seconds->date/type.
time->nanoseconds[procedure] (time->nanoseconds TIME)
Returns the TIME object value as a nanoseconds value.
nanoseconds->time[procedure] (nanoseconds->time NANOSECONDS [TIME-TYPE time-duration])
Returns the NANOSECONDS value as a time TIME-TYPE object.
nanoseconds->seconds[procedure] (nanoseconds->seconds NANOSECONDS)
Returns the NANOSECONDS value as an inexact seconds value.
time->milliseconds[procedure] (time->milliseconds TIME)
Returns the TIME object value as a milliseconds value.
milliseconds->time[procedure] (milliseconds->time MILLISECONDS [TIME-TYPE time-duration])
Returns the MILLISECONDS value as a time TIME-TYPE object.
milliseconds->seconds[procedure] (milliseconds->seconds MILLISECONDS)
Returns the MILLISECONDS value as an inexact seconds value.
time->date[procedure] (time->date TIME)
Returns the TIME object value as a date. A shorthand for the (time-*->date...) procedures.
time->julian-day[procedure] (time->julian-day TIME)
Returns the julian day for the TIME object.
time->modified-julian-day[procedure] (time->modified-julian-day TIME)
Returns the modified julian day for the TIME object.
make-duration[procedure] (make-duration [#:days 0] [#:hours 0] [#:minutes 0] [#:seconds 0] [#:milliseconds 0] [#:microseconds 0] [#:nanoseconds 0])
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 and ONE-NANOSECOND-DURATION are pre-defined.
divide-duration[procedure] (divide-duration DURATION NUMBER)
Returns a duration, from DURATION, divided by NUMBER, without remainder.
divide-duration![procedure] (divide-duration! DURATION NUMBER)
Returns DURATION, divided by NUMBER, without remainder.
multiply-duration[procedure] (multiply-duration DURATION NUMBER)
Returns a duration, from DURATION, multiplied by NUMBER, truncated.
multiply-duration![procedure] (multiply-duration! DURATION NUMBER)
Returns DURATION, multiplied by NUMBER, truncated.
time-negative?[procedure] (time-negative? TIME)
Is TIME negative?
A time object will never have a negative nanoseconds value.
time-positve?[procedure] (time-positve? TIME)
Is TIME positive?
time-zero?[procedure] (time-zero? TIME)
Is TIME zero?
time-abs[procedure] (time-abs TIME)
Returns the absolute time value, from TIME.
time-abs![procedure] (time-abs! TIME)
Returns the absolute TIME value.
time-negate[procedure] (time-negate TIME)
Returns the sign inverted time value, from TIME.
time-negate![procedure] (time-negate! TIME)
Returns the TIME sign inverted value.
time-compare[procedure] (time-compare TIME1 TIME2)
Returns -1, 0, or 1.
time-max[procedure] (time-max TIME1 [TIME2...])
Returns the maximum time object from TIME1 TIME2....
time-min[procedure] (time-min TIME1 [TIME2...])
Returns the minimum time object from TIME1 TIME2....
default-date-clock-type[parameter] (default-date-clock-type [CLOCK-TYPE time-utc])
Sets or gets the clock-type used by default for conversion of a date to a time.
copy-date[procedure] (copy-date DATE)
Returns an exact copy of the specified DATE object.
date->time[procedure] (date->time DATE [CLOCK-TYPE (default-date-clock-type)])
Returns the specified DATE as a time-object of type CLOCK-TYPE.
date-zone-name[procedure] (date-zone-name DATE)
Returns the timezone abbreviation of the specified DATE object. The result is either a string or #f.
date-dst?[procedure] (date-dst? DATE)
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-difference[procedure] (date-difference DATE1 DATE2 [CLOCK-TYPE])
Returns the duration between DATE1 and DATE2.
date-add-duration[procedure] (date-add-duration DATE DURATION [CLOCK-TYPE])
Returns the DATE plus the DURATION.
date-subtract-duration[procedure] (date-subtract-duration DATE DURATION [CLOCK-TYPE])
Returns the DATE minus the DURATION.
date-compare[procedure] (date-compare DATE1 DATE2)
Returns -1, 0, or 1.
date=?[procedure] (date=? DATE1 DATE2)
Is DATE1 on DATE2?
date>?[procedure] (date>? DATE1 DATE2)
Is DATE1 after DATE2?
date<?[procedure] (date<? DATE1 DATE2)
Is DATE1 before DATE2?
date>=?[procedure] (date>=? DATE1 DATE2)
Is DATE1 after or on DATE2?
date<=?[procedure] (date<=? DATE1 DATE2)
Is DATE1 before or on DATE2?
- 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[parameter] (local-timezone-locale [TZ-COMPONENTS])
Gets or sets the local timezone-locale object.
utc-timezone-locale[parameter] (utc-timezone-locale [TZ-COMPONENTS])
Gets or sets the utc timezone-locale object.
Probably not a good idea to change the value.
timezone-locale-name[procedure] (timezone-locale-name [TZ-COMPONENTS])
Returns the timezone-locale name of the supplied TZ-COMPONENTS, or the (local-timezone-locale) if missing.
timezone-locale-offset[procedure] (timezone-locale-offset [TZ-COMPONENTS])
Returns the timezone-locale offset of the supplied TZ-COMPONENTS, or the (local-timezone-locale) if missing.
timezone-locale-dst?[procedure] (timezone-locale-dst? [TZ-COMPONENTS])
Returns the timezone-locale daylight saving time flag of the supplied TZ-COMPONENTS, or the (local-timezone-locale) if missing.
format-date[procedure] (format-date DESTINATION DATE-FORMAT-STRING [DATE])
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 string the DATE-FORMAT-STRING value must be a date object, the DESTINATION value is used as the DATE-FORMAT-STRING, and the result is returned as a string.
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.
scan-date[procedure] (scan-date SOURCE TEMPLATE-STRING)
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.
A time-period is an interval, [begin end), where begin and end are time objects of the same clock type. When end <= begin the interval is null.
make-null-time-period[procedure] (make-null-time-period [CLOCK-TYPE (default-date-clock-type)])
Returns a null interval for the specified CLOCK-TYPE.
make-time-period[procedure] (make-time-period BEGIN END [CLOCK-TYPE (default-date-clock-type)])
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[procedure] (copy-time-period TIME-PERIOD)
Returns a copy of TIME-PERIOD.
time-period-begin[procedure] (time-period-begin TIME-PERIOD)
Returns the start time for the TIME-PERIOD.
time-period-end[procedure] (time-period-end TIME-PERIOD)
Returns the end time for the TIME-PERIOD.
time-period-last[procedure] (time-period-last TIME-PERIOD)
Returns the last time for the TIME-PERIOD; (time-period-end - 1ns).
time-period-type[procedure] (time-period-type TIME-PERIOD)
Returns the clock-type of the TIME-PERIOD.
time-period?[procedure] (time-period? OBJECT)
Is OBJECT a time-period?
time-period-null?[procedure] (time-period-null? TIME-PERIOD)
Is the TIME-PERIOD null?
time-period-length[procedure] (time-period-length TIME-PERIOD)
Returns the time-duration of the TIME-PERIOD.
time-period-compare[procedure] (time-period-compare TIME-PERIOD-1 TIME-PERIOD-2) => INTEGER
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=?[procedure] (time-period=? TIME-PERIOD-1 TIME-PERIOD-2)
Does TIME-PERIOD-1 begin & end with TIME-PERIOD-2?
time-period<?[procedure] (time-period<? TIME-PERIOD-1 TIME-PERIOD-2)
Does TIME-PERIOD-1 end before TIME-PERIOD-2 begins?
time-period>?[procedure] (time-period>? TIME-PERIOD-1 TIME-PERIOD-2)
Does TIME-PERIOD-1 begin after TIME-PERIOD-2 ends?
time-period<=?[procedure] (time-period<=? TIME-PERIOD-1 TIME-PERIOD-2)
Does TIME-PERIOD-1 end on or before TIME-PERIOD-2 begins?
time-period>=?[procedure] (time-period>=? TIME-PERIOD-1 TIME-PERIOD-2)
Does TIME-PERIOD-1 begin on or after TIME-PERIOD-2 ends?
time-period-preceding[procedure] (time-period-preceding TIME-PERIOD-1 TIME-PERIOD-2)
Return the portion of TIME-PERIOD-1 before TIME-PERIOD-2 or #f when it doesn't precede.
time-period-succeeding[procedure] (time-period-succeeding TIME-PERIOD-1 TIME-PERIOD-2)
Return the portion of TIME-PERIOD-1 after TIME-PERIOD-2 or #f when it doesn't succeed.
time-period-contains/period?[procedure] (time-period-contains/period? TIME-PERIOD-1 TIME-PERIOD-2)
Is TIME-PERIOD-2 within TIME-PERIOD-1?
time-period-contains/time?[procedure] (time-period-contains/time? TIME-PERIOD TIME)
Is TIME within TIME-PERIOD?
TIME is converted to a compatible clock-type if possible.
time-period-contains/date?[procedure] (time-period-contains/date? TIME-PERIOD DATE)
Is DATE within TIME-PERIOD?
DATE is converted to a compatible time if possible.
time-period-contains?[procedure] (time-period-contains? TIME-PERIOD OBJECT)
Is OBJECT within TIME-PERIOD?
OBJECT maybe a time, date, or time-period.
time-period-intersects?[procedure] (time-period-intersects? TIME-PERIOD-1 TIME-PERIOD-2)
Does TIME-PERIOD-2 overlap TIME-PERIOD-1?
time-period-intersection[procedure] (time-period-intersection TIME-PERIOD-1 TIME-PERIOD-2)
The overlapping time-period of TIME-PERIOD-2 and TIME-PERIOD-1, or #f when no overlap.
time-period-union[procedure] (time-period-union TIME-PERIOD-1 TIME-PERIOD-2)
Returns the time-period spanned by TIME-PERIOD-1 and TIME-PERIOD-2, or #f when they do not intersect.
time-period-span[procedure] (time-period-span TIME-PERIOD-1 TIME-PERIOD-2)
Returns the time-period spanned by TIME-PERIOD-1 and TIME-PERIOD-2, including any gaps.
time-period-shift[procedure] (time-period-shift TIME-PERIOD DURATION)
Returns a copy of TIME-PERIOD shifted by DURATION.
time-period-shift![procedure] (time-period-shift! TIME-PERIOD DURATION)
Returns TIME-PERIOD shifted by DURATION.
- 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.
- The SRFI-18 time object is not accepted except by the conversion procedures.
- The expression (time=? (seconds->time/type (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.
- Initial Chicken 4 release
Copyright (C) 2009 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.