Time Library

• 1. Introduction
• 2. The Time Module
• 3. The Time-IO Module
• 4. Parse-Time Directives

The Time Library

1. Introduction

Time is a library of routines for working with time and dates. Time exports two modules:

Time

This module contains the basic time classes, functions to convert between them, and functions to get the current time.

Time-IO

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

<universal-time> [Class]

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 isn’t 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.

<seconds> [Type]
<minutes> [Type]
<hours> [Type]
<day-of-week> [Type]
<day-of-month> [Type]
<month> [Type]
<year> [Type]
<timezone> [Type]

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

format-time [Function]

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

parse-time [Function]

(input-stream, control-string)
=> decoded-time

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 can’t 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)

is not the same as

           let stream = make(<string-stream>, string: "0");

             parse-time(stream, "%w")

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:

%a

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.

%b

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.

%d

Day of the month.

%D

Date as either "%m/%d/%y" or "%m-%d-%y".

%H

Hour on a 24 hour clock (ie, 0-23).

%I

Hour on a 12 hour clock (ie, 1-12).

%m

Month number (1-12).

%M

Minute (0-59).

%p

Either "AM" or "PM". Case does not matter, but the "AM" or "PM" may not contain periods (‘.’).

%r

Equivalent to "%I:M:S %p". In other words, 12-hour time with AM/PM.

%S

Seconds (0-59). Unlike C’s strptime, leap-seconds and double-leap-seconds are not allowed.

%T

Equivalent to "%H:%M:%S"

%w

Weekday number, with 0 as Monday.

%y

Year. If less than 100, assume an implicit "19" in front of it.

%Y

Year. Do not assume any implicit "19".

%%

A single % character.

Send comments and bug reports to gwydion-bugs@cs.cmu.edu