This SRFI is currently in draft status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi-174@nospamsrfi.schemers.org. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.
This SRFI defines the trivial type timespec, which is used
to represent the struct timespec defined by the
POSIX <time.h> header.
The reason for putting this very simple and straightforward type into a SRFI (and library) of its own is that timespecs are part of the interface for more than one SRFI. If they are defined in just one SRFI and imported by the rest, that produces an otherwise useless and unnecessary dependency on the defining SRFI. This arises particularly in R6RS and R7RS because record types are generative (distinct definitions lead to distinct record types) and because most implementations report a warning or even an error if the same identifier is imported from different libraries, unless they have both imported it in turn from the same original library.
Timespec is a type that contains two values. The first is the number of seconds since a particular epoch, but normally excluding all leap seconds that have occurred since then. The second is the number of nanoseconds since the beginning of the specified second. It is recommended, but not required, that timespecs are a disjoint type, but for efficiency's sake they may be represented otherwise in particular implementations. If they are not disjoint, the exact representation (such as a pair) must be documented by the implementation.
(timespec seconds nanoseconds)
Returns a timespec containing seconds and nanoseconds.
(timespec? obj)
Returns #f if obj is definitely not a timespec,
and #t if it is most probably one.
If timespecs are a disjoint type, this procedure simply tests whether obj belongs to that type. If not, then each component is checked to see if it is an exact integer, and in the case of the nanoseconds component, whether it is a non-positive integer less than 1,000,000,000. In addition, on 64-bit Schemes, the integers will almost certainly be fixnums for all times in the past or future one billion years, which is certainly sufficient in practice, so a check for fixnum status (if possible) will provide additional certitude.
(timespec-seconds timespec)
Returns the seconds component of timespec.
(timespec-nanoseconds timespec)
Returns the nanoseconds component of timespec.
timespec-comparator
This variable (not a procedure) is a comparator object for timespecs, ordering them by the total number of nanoseconds. A simple hash function is also provided.
Note that it is an (undetectable) error to compare two timespecs that are relative to different epochs.
Two implementations of SRFI 174 are in the repository of this SRFI. The files are:
srfi/174.sld - uses a disjoint typesrfi/pair-174.sld - uses a pairchibi-tests.scm - Tests using (chibi tests)chibi-tests-pair.scm - Tests for (srfi pair-174)Discussions between me, Lassi Kortela, and Harold Ancell, mostly on the SRFI 170 mailing list, made the need for this SRFI clear.
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 (including the next paragraph) shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", 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.