The Time Library
Designed by the Gwydion Project
Time is a library of routines for working with time and dates. Time exports two modules:
- This module contains the basic time classes, functions to convert between them, and functions to get the current time.
- This module contains functions for basic time input and output.
Note: The Time library is not available on all platforms. At present, it will work only under HP/UX and Microsoft Windows.
2. The Time Module
A <universal-time> is a simple <general-integer> representation of the number of seconds since 00:00:00 1 January 1970, UTC.
<decoded-time> [Sealed Immutable Class]
Decoded time is for representing absolute times in a nice human readable way. The <decoded-time> class contains the following constant slots: seconds, minutes, hours, day-of-week (0 represents Monday, 1 represents Tuesday, etc.), day-of-month, month, year, daylight-savings-time?, and timezone (in seconds west of UTC). Keywords of the same names are used to initialize these slots. A <decoded-time> may be incompletely specified; any of its slots may be #f. An additional init-keyword is default-from:. If default-from: is specified, any slot that isnt specified via an init-keyword will take its value of the default-from object. If default-from: is not specified, any slot not specified via an init-keyword will have a value of #f.
Note: If the timezone is specified in a <decoded-time>, the functions in the time library assume that it is the correct timezone and ignore the daylight-savings-time? flag. Therefore if you encode a <decoded-time> with the timezone representing EST and the daylight-savings-time? flag set to #t, it will convert the time assuming the local timezone is EST, not EDT.
These are all limited integers that represent the acceptable ranges for the respective slots in the <decoded-time> class.
get-universal-time () => universal-time [Function]
Returns the current time as a <universal-time>.
get-decoded-time (#key timezone) => decoded-time [Function]
Returns the current time as a completely specified <decoded-time>. The time returned is relative to the timezone indicated by the timezone keyword parameter. The timezone parameter is the number of seconds west of UTC, which defaults to the local timezone.
Known Bug: Mindy for MS-Windows will give an incorrect timezone. We have no idea why. (d2c under Windows gives the correct timezone)
decode-time (universal-time, #key timezone) => decoded-time [Function]
Returns the supplied <universal-time> as a completely specified <decoded-time>. The time returned is relative to the timezone indicated by the timezone keyword keyword paramter (in seconds west of UTC). The timezone defaults to the local timezone.
as(<decoded-time>, universal-time) => decoded-time [G.F. Method]
Equivalent to decode-time(universal-time).
encode-time(decoded-time) => universal-time [Function]
Returns the supplied <decoded-time> as a <universal-time>. Only completely specified decoded-times can be encoded (as determined by encodable-time?. An error is returned if the decoded-time is not encodable.
encodable-time?(decoded-time) => boolean [Function]
Returns #t if the time can be encoded. A <decoded-time> is encodable if all its slots are specified, except possibly day-of-week.
3. The Time-IO Module
(stream, format-string, decoded-time)
This is a wrapper for the C function strftime. Format-string is a string describing the format for the output written to stream.
This function is similar to the C function strptime, but contains considerably fewer directives. (See below for a complete list of directives) Parse-time works by trying to match things in input-stream up against things in the control-string. A whitespace character inside control-string will match zero or more whitespace characters in input-stream, a control-string directive will match as described below, and all other characters match themselves (case sensitive). If a directive expects a number, a leading zero is optional but not required. Two consecutive directives that expect numbers must be separated by something non-numeric (such as whitespace or characters like :, -, and /), otherwise parse-time cant tell where the first directive should stop parsing and the second one should begin. Similarly, two consecutive directives that expect words must be separated by something non-alphabetic.
If input-stream does not match control-string, a <time-parsing-error> will be signaled, and additional input will not be read from input-stream. An unknown control-string directive is an error, but is not a <time-parsing-error>.
Caveat: The C specification numbers days of the week differently from the Dylan Time library (C has Sunday as day 0, while Dylan uses Monday for day 0). The parse-time and format-time functions correctly convert between the two conventions, but this can have unexpected consequences:
make(<decoded-time>, day-of-week: 0)
let stream = make(<string-stream>, string: "0");
4. Parse-Time Directives
Control-strings consist of directives, much like format-strings from the Format library do. Unlike the Format library, parse-time directives are case sensitive. (This is mostly because "minute" and "month" start with the same letter) Parse-time supports the following directives:
Day of the week, as a name. Either the full name (ie, "Monday"), or the three letter abbreviation ("Mon") may be used; case does not matter.
Month of the year, as a name. Either the full name (ie, "January"), or the three letter abbreviation ("Jan") may be used; case does not matter.
Copyright 1994, 1995, 1996, 1997 Carnegie Mellon University. All rights reserved.
Send comments and bug reports to email@example.com