more revisions

["Will Fitzgerald" <fitzgerald@xxxxxxxxxxxx>]

I started coding up the proposed revisions to my draft. 
This resulted in more revisions.

Now, there are only two time-related data types: a 'time' object, and
seconds (as in SRFI 18).

The time object has the following components:

(time-second time) => real (0 to 61.0)
                      potentially includes leap seconds
(time-minute time) => integer (0 to 59)
(time-hour time)   => integer (0 to 23)
(time-day time)    => integer (1 to 31)
(time-month time)  => integer (1 to 12) (January=1, etc.)
(time-year time)   => integer
(time-zone-offset time) => integer 
 (the number of seconds east of GMT for this timezone)

Implementations can vary as to whether leap seconds are included. 
Range is implementation specific.

The 'second' object is a real, potentially inexact, 
corresponding to the number of seconds
from 0 to implementation specific upper range, with
the meaning of 0 implementation specific.

;; get the current values

(current-time)
(current-seconds)  

;; creator

(make-time second minute hour date month year zone-offset)

;; other readers

(time-year-day time) => integer. Day of year (0=1/1 , etc.)
(time-week-day time) => integer. Day of week (0=Sunday, etc.)

(julian-day time) => real returns the Julian day, where JD 0
JD 0 designates the 24 hours from noon UTC on 1 January 4713 BC
 to noon UTC on 2 January 4713 BC. 

(modified-julian-day time) => real. Returns the modified Julian
day; number of days since 17 Nov 1858 at 00:00:00 UTC.

;; writers

(set-time-second! time real)
(set-time-minute! time integer)
(set-time-hour! time integer)
(set-time-day! time integer)
(set-time-month! time integer)
(set-time-year! time integer)
(set-time-zone-offset! time integer)

;; converters. all strings are ISO formats.

(copy-time time) => time
(time->seconds time) => real
(seconds->time real) => time
(julian-day->time real) => time
(modified-julian-day->time real) => time
(time->universal-time! time) => time (side-effects); converts to GMT
(time->universal-time time) => time (copies)

(time->string time  . include-time-zone-offset?)  => string
(time->date-string time) => string e.g., 2000-01-31
(time->hour-string time) => string e.g. 12:34:56.789

(string->time string) => time


;; comparing procedures

The comparison procedures must take the time-zone-offset into
consideration. 

(time=? time1 time2) => boolean
(time>? time1 time2) => boolean
(time<? time1 time2) => boolean
(time>=? time1 time2) => boolean
(time<=? time1 time2) => boolean

;; data type probes

(time? time) => boolean

;; time arithmetic

(add-seconds! time real) => time adds number of seconds to date,
 side-effecting it
(add-seconds time real) => time adds number of seconds to date,
creating new date.


Here's a summary of the changes:


I dropped the 'machine time' procedures. They didn't fit very well 
in the overall scheme.

I dropped the daylights savings time flag. I had thought this 
typically changed the semantics of a time object for time arithmetic,
but this doesn't seem to be the case (at least for MzScheme). Besides,
it's not always very usefully defined. If (current-time) needs to 
adjust for daylights savings time, this should be reflected in the 
time-zone-offset.

I dropped the special 'Julian day' time object, and just made them
readers on the time object. I added the 'modified Julian day'
reader, which provides lower numbers (and starts at midnight).

I added the time->universal-time! and time->universal-time, which
takes a time object, and converts it to a 0 time-zone-offset.

I added the add-seconds! and add-seconds procedures. These are
procedures that allow you to add an arbitrary number of seconds
to a time object. (Marc, this means your threads could run until you
ran out of integers -- they might even stop using Cobol by then!). In
the code I've written so far, I think all the right things happen at
the time boundaries. Leap seconds are still a pain, though.

I added a couple of additional string output procedures, to get just
the date or the hour.

I'll post the code soon. Currently, the only system dependencies
are on CURRENT-SECONDS, knowing the time object corresponding to
(seconds->date 0) at GMT, and probing the local time-zone-offset. 

I'll also begin revising the proposal in earnest.