The Time Module

This module contains the basic time classes, encoding and decoding helper classes, functions to convert between times, and functions to get the current time.


<universal-time>[Constant]

A simple <general-integer> representation of the number of seconds since 00:00:00 1 January 1970, UTC.

Type

<integer> or <extended-integer>

Description

Using <extended-integer>s guarantees that you can represent any date after 1 Jan 1970. Using <integer>s will break for dates after a certain date (depending on $maximum-integer) and can sometimes cause unpredictable behavior.


<seconds>[Constant]

An <integer> between 0 and 59 inclusive.

Type

limited(<integer>, min: 0, max: 59)

Description

Ensures the seconds slot of <decoded-time> is valid.


<minutes>[Constant]

An <integer> between 0 and 59 inclusive.

Type

limited(<integer>, min: 0, max: 59)

Description

Ensures the minutes slot of <decoded-time> is valid.


<hours>[Constant]

An <integer> between 0 and 23 inclusive.

Type

limited(<integer>, min: 0, max: 23)

Description

Ensures the hours slot of <decoded-time> is valid.


<day-of-week>[Constant]

An <integer> between 0 and 6 inclusive.

Type

limited(<integer>, min: 0, max: 6)

Description

Ensures the day-of-week slot of <decoded-time> is valid. The first day of the week (or 0) is Monday.


<day-of-month>[Constant]

An <integer> between 1 and 31 inclusive.

Type

limited(<integer>, min: 1, max: 31)

Description

Ensures the day-of-month slot of <decoded-time> is valid.


<month>[Constant]

An <integer> between 1 and 12 inclusive.

Type

limited(<integer>, min: 1, max: 12)

Description

Ensures the month slot of <decoded-time> is valid.


<timezone>[Constant]

An <integer> between -86400 and 86400 inclusive.

Type

limited(<integer>, min: -86400, max: 86400)

Description

Ensures the timezone slot of <decoded-time> is valid. A <timezone> is the seconds west of UTC.


<year>[Constant]

A named <integer>

Type

<integer>

Description

Since every other slot in <decoded-time> has a named type, we didn't want the year slot to be lonely.


<decoded-time>[sealed Class]

Decoded time is for representing absolute times in a nice human readable way.

Superclasses

<object>

Initialization Keywords

seconds:An instance of <seconds>. 0 to 59 Defaults to #f.
minutes:An instance of <minutes>. 0 to 59 Defaults to #f.
hours:An instance of <hours>. 0 to 23 Defaults to #f.
day-of-week:An instance of <day-of-week>. 0 to 6 Defaults to #f.
day-of-month:An instance of <day-of-month>. 1 to 31 Defaults to #f.
month:An instance of <month>. 1 to 12 Defaults to #f.
year:An instance of <year>. Year can be any integer (even negative ones); however, <decoded-time> starts from 1970. Defaults to #f.
daylight-savings-time?:An instance of <boolean>. Is this decoded time adjusted for daylight savings time Defaults to (uninitialized).
timezone:An instance of <timezone>. -86400 to 86400. If this keyword specified, 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. Defaults to #f.
default-from:An instance of <decoded-time>. Allows initialization from another <decoded-time> instance. If default-from: is specified, any slot that isn't specified via an init-keyword will take its value of the this slot's object. If this keyword is not specified, any slot not specified via an init-keyword will have a value of #f. Defaults to $null-decoded-time.

Description

Note that there's no point in not defining a print-object method, since the parse-time stuff already uses streams. Might as well use print and format, too.

We don't write "hh:mm:ss mm/dd/yy" or anything clever like that because it might not look so hot with undefined slots. (Besides, mm/dd/yy is rather ambiguous)


$null-decoded-time[Constant]

A <decoded-time> where all the slots are initialized to #f

Type

<decoded-time>

Description

This is an internal constant used to default the <decoded-time> when the default-from: keyword is used.


$default-time[Constant]

A <decoded-time> where all the slots are initialized to 0 or 1 (or, in the case of daylight-savings-time?, #f)

Type

<decoded-time>

Description

This constant gives a "0" <decoded-time>. Of note here is that the year slot is initialized to 0, not 1970. Is this an error?


get-universal-time[Method]

Return the current time as a <universal-time>.

Synopsis

get-universal-time () => (current-time)

Parameters

None.

Return Values

current-timeAn instance of <universal-time>.

Description

Recall that <universal-time> is an <integer> (seconds) from 01 Jan 00:00:00Z 1970. Use other functions to decode this value.


get-decoded-time[Method]

Return the current time as a <decoded-time>.

Synopsis

get-decoded-time (#key timezone) => (current-time)

Parameters

timezone:An instance of <timezone>. If supplied, uses the timezone to convert the current universal time.

Return Values

current-timeAn instance of <decoded-time>.

Description

This gives the current time, this time decoded into the appropriate slots. If timezone is supplied, then that time is converted to the time in that timezone.


decode-time[Method]

Decode a <universal-time>

Synopsis

decode-time (universal-time, #key timezone) => (decoded-time)

Parameters

universal-timeAn instance of <universal-time>. The time to be decoded
timezone:An instance of <timezone>. If supplied, uses the timezone to convert the current universal time.

Return Values

decoded-timeAn instance of <decoded-time>.

Description

Decode a <universal-time> into a <decoded-time> using the supplied timezone.


encode-time[Method]

Encode a <decoded-time>

Synopsis

encode-time (decoded-time) => (universal-time)

Parameters

decoded-timeAn instance of <decoded-time>. The time to be encoded

Return Values

universal-timeAn instance of <universal-time>.

Description

Encode a <decoded-time> into the universal time format.


encodable-time?[Method]

Sees if time can be encoded.

Synopsis

encodable-time? (time) => (result)

Parameters

timeAn instance of <decoded-time>. The time to be tested

Return Values

resultAn instance of <boolean>.

Description

Returns #t if time may be encoded. A <decoded-time> is encodable if all of its slots are specified, except possibly day-of-week.


as[Method]

Provides the as interface to get a <decoded-time>.

Synopsis

as (cls, universal-time) => (decoded-time)

Parameters

clsAn instance of singleton(<decoded-time>). The type of the instance returned
universal-timeAn instance of <universal-time>. the instance to decode

Return Values

decoded-timeAn instance of <decoded-time>.

Description

Decode a <universal-time> into a <decoded-time> the timezone is 0 for this method.