chickadee » srfi-19

srfi-19

Time Data Types and Procedures

TOC »

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:

(import srfi-19-core)

Or separately:

(import srfi-19-time)
(import srfi-19-date)
(import srfi-19-timezone)
(import srfi-19-support)

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.

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 a 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 a 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
(zero-time [TIME-TYPE time-duration]) -> timeprocedure
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 a 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, 'weeks, '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

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

(import 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 DATEprocedure
format-date DATE-FORMAT DATEprocedure

Displays a text form of the DATE on the DESTINATION using the DATE-FORMAT.

DESTINATION
; the result is returned as a string.
DESTINATION
#f ; the result is returned as a string.
DESTINATION
#t ; the (current-output-port) is used.
DESTINATION
output-port ; text output port.
DESTINATION
number ; the (current-error-port) is the DESTINATION.
scan-date
scan-date SOURCE TEMPLATEprocedure

Reads a text form of a date from the SOURCE, following the TEMPLATE, and returns a date object.

SOURCE
#t ; (current-input-port).
SOURCE
input-port ; text input port.
SOURCE
string ; a date text form.

A partial date resulting from a time-only format, missing the d-m-y, is completed with from the (current-date), as is any timezone information, and missing h:m:s:ns are 0.

string->date
string->date SOURCE #!optional TEMPLATEprocedure
SOURCE
see scan-date.
TEMPLATE
string ; default (localized-template/default 'srfi-19 'date-time).
date->string
date->string DATE #!optional DATE-FORMATprocedure
DATE
date
DATE-FORMAT
string ; default "~c".

Date/Time Literals

Literal Date/Time forms.

Usage

(import srfi-19-literals)
date-literal-form
date-literal-form #!optional FORMparameter

The date literal format.

#f
#<srfi-19#date ...>
SRFI-10
#,(srfi-19-date ...)
#t
#@...
|#@|
#@...
time-literal-form
time-literal-form #!optional FORMparameter

The time literal format.

#f
#<srfi-19#time ...>
SRFI-10
#,(srfi-19-time ...)
read-date-literal
read-date-literal #!optional PORTprocedure

Read a date-literal from the PORT, in one of the supported forms, and return the object creation source form; '(make-date ....).

PORT
input-port ; default (current-input-port)

Supported forms:

"~Y-~m-~dT~H:~M:~S~z"
date time timezone
"~Y-~m-~dT~H:~M:~S"
date time
"~Y-~m-~d"
date
"~H:~M:~S~z"
time timezone; date components from (current-date)
"~H:~M:~S"
time; date components from (current-date)
write-date-literal
write-date-literal DATE #!optional PORTprocedure

Write the DATE to the PORT using a string ISO form; "~Y-~m-~dT~H:~M:~S~z".

PORT
output-port ; default (current-output-port)

Time Period

Usage

(import 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

(import srfi-19)

Examples

;must be done before 1st invocation of a srfi-19 export
(import 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
(import (chicken format))
(import srfi-19)
(format #t "Present Day: ~A~%Present Time: ~A~%: Hah, hah, hah.~%"
  (current-date) (current-time))

Notes

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.

Bugs and Limitations

Requirements

srfi-1 srfi-13 srfi-18 srfi-69 miscmacros locale srfi-29 record-variants check-errors

format

Author

Kon Lovett

Acknowledgments

Version history

4.4.0
Add Date/Time source literals via the srfi-19-literals module.
4.3.2
Allow partial (time only) date read.
4.3.1
.
4.3.0
Deprecate 'srfi-10 record print form. Fix record printing.
4.3.0
nanoseconds->seconds, milliseconds->seconds, & date->seconds do not necessarily return an inexact.
4.2.1
.
4.2.0
Fix make-date w/o tz.
4.1.2
.
4.1.1
Fix seconds->date flonum argument handling.
4.1.0
Variants.
4.0.2
Add dependencies.
4.0.1
Add dependencies.
4.0.0
C5 port.

License

Copyright (C) 2009-2020 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.

Contents »