doc srfi1-19 date/time

[Kevin Ryde]

This is some words for the srfi-19 section of the manual.

The eagle-eyed will notice I've got a julian day described as starting
from 1 Jan 4713 BC, where the spec and code have 24 Nov 4714 BC.  I
think the code incorrectly arrives at the latter through treating
centuries prior to 1582 as non leap years.  Anyone feeling brave could
have a go at fixing that if they like.




SRFI-19 - Time/Date Library
===========================

This is an implementation of the SRFI-19 time/date library.  The
functions and variables described here are provided by

     (use-modules (srfi srfi-19))

SRFI-19 Introduction
--------------------

This module implements time and date representations and calculations,
in various time systems, including universal time (UTC) and atomic time
(TAI).

   For those not familiar with these time systems, TAI is based on a
fixed length second derived from oscillations of certain atoms.  UTC
differs from TAI by an integral number of seconds, which is increased
or decreased at announced times to keep UTC aligned to a mean solar day
(the rotation of the earth is not quite constant).

   So far, only increases in the TAI <-> UTC difference have been
needed.  Such an increase is a "leap second", an extra second of TAI
introduced at the end of a UTC day.  When working entirely within UTC
this is never seen, every day simply has 86400 seconds.  But when
converting from TAI to a UTC date, an extra 23:59:60 is present, where
normally a day would end at 23:59:59 of course.  Effectively the UTC
second from 23:59:59 to 00:00:00 has taken two TAI seconds.

   In the current implementation, the system clock is assumed to be UTC,
and a table of leap seconds in the code converts to TAI.  See comments
in `srfi-19.scm' for how to update this table.

   Also, for those not familiar with the terminology, a "Julian Day" is
a real number which is a count of days and fraction of a day, in UTC,
starting from -4713-01-01T12:00:00Z, ie. midday Monday 1 Jan 4713 B.C.
And a "Modified Julian Day" is the same, but starting from
1858-11-17T00:00:00Z, ie. midnight 17 November 1858 UTC.

SRFI-19 Time
------------

A "time" object has type, seconds and nanoseconds fields representing a
point in time starting from some epoch.  This is an arbitrary point in
time, not just a time of day.  Although times are represented in
nanoseconds, the actual resolution may be lower.

   The following variables hold the possible time types.  For instance
`(current-time time-process)' would give the current CPU process time.

 - Variable: time-utc
     Universal Coordinated Time (UTC).

 - Variable: time-tai
     International Atomic Time (TAI).

 - Variable: time-monotonic
     Monotonic time, meaning a monotonically increasing time starting
     from an unspecified epoch.

     Note that in the current implementation `time-monotonic' is the
     same as `time-tai', and unfortunately is therefore affected by
     adjustments to the system clock.  Perhaps this will change in the
     future.

 - Variable: time-duration
     A duration, meaning simply a difference between two times.

 - Variable: time-process
     CPU time spent in the current process, starting from when the
     process began.

 - Variable: time-thread
     CPU time spent in the current thread.  Not currently implemented.


 - Function: time? obj
     Return `#t' if OBJ is a time object, or `#f' if not.

 - Function: make-time type nanoseconds seconds
     Create a time object with the given TYPE, SECONDS and NANOSECONDS.

 - Function: time-type time
 - Function: time-nanosecond time
 - Function: time-second time
 - Function: set-time-type! time type
 - Function: set-time-nanosecond! time nsec
 - Function: set-time-second! time sec
     Get or set the type, seconds or nanoseconds fields of a time
     object.

     `set-time-type!' merely changes that field, it doesn't convert the
     time value.  For conversions, see *Note SRFI-19 Time/Date
     conversions::.

 - Function: copy-time time
     Return a new time object, which is a copy of the given TIME.

 - Function: current-time [type]
     Return the current time of the given TYPE.  The default TYPE is
     `time-utc'.

     Note that the name `current-time' conflicts with the Guile core
     `current-time' function (*note Time::).  Applications wanting to
     use both will need to rename one of them.

 - Function: time-resolution [type]
     Return the resolution, in nanoseconds, of the given time TYPE.
     The default TYPE is `time-utc'.

 - Function: time<=? t1 t2
 - Function: time<? t1 t2
 - Function: time=? t1 t2
 - Function: time>=? t1 t2
 - Function: time>? t1 t2
     Return `#t' or `#f' according to the respective relation between
     time objects T1 and T2.  T1 and T2 must be the same time type.

 - Function: time-difference t1 t2
 - Function: time-difference! t1 t2
     Return a time object of type `time-duration' representing the
     period between T1 and T2.  T1 and T2 must be the same time type.

     `time-difference' returns a new time object, `time-difference!'
     may modify T1 to form its return.

 - Function: add-duration time duration
 - Function: add-duration! time duration
 - Function: subtract-duration time duration
 - Function: subtract-duration! time duration
     Return a time object which is TIME with the given DURATION added
     or subtracted.  DURATION must be a time object of type
     `time-duration'.

     `add-duration' and `subtract-duration' return a new time object.
     `add-duration!' and `subtract-duration!' may modify the given TIME
     to form their return.

SRFI-19 Date
------------

A "date" object represents a date in the Gregorian calendar and a time
of day on that date in some timezone.

   The fields are year, month, day, hour, minute, second, nanoseconds
and timezone.  A date object is immutable, its fields can be read but
they cannot be modified once the object is created.

 - Function: date? obj
     Return `#t' if OBJ is a date object, or `#f' if not.

 - Function: make-date nsecs seconds minutes hours date month year
          zone-offset
     Create a new date object.

 - Function: date-nanosecond date
     Nanoseconds, 0 to 999999999.

 - Function: date-second date
     Seconds, 0 to 60.  0 to 59 is the usual range, 60 is for a leap
     second.

 - Function: date-minute date
     Minutes, 0 to 59.

 - Function: date-hour date
     Hour, 0 to 23.

 - Function: date-day date
     Day of the month, 1 to 31 (or less, according to the month).

 - Function: date-month date
     Month, 1 to 12.

 - Function: date-year date
     Year, eg. 2003.

 - Function: date-zone-offset date
     Time zone, an integer number of seconds east of Greenwich.

 - Function: date-year-day date
     Day of the year, starting from 1 for 1st January.

 - Function: date-week-day date
     Day of the week, starting from 0 for Sunday.

 - Function: date-week-number date dstartw
     Week of the year, ignoring a first partial week.  DSTARTW is the
     day of the week which is taken to start a week, 0 for Sunday, 1 for
     Monday, etc.

 - Function: current-date [tz-offset]
     Return a date object representing the current date/time UTC.
     TZ-OFFSET is seconds east of Greenwich, and defaults to the local
     timezone.

 - Function: current-julian-day
     Return the current Julian Day.

 - Function: current-modified-julian-day
     Return the current Modified Julian Day.

SRFI-19 Time/Date conversions
-----------------------------

 - Function: date->julian-day date
 - Function: date->modified-julian-day date
 - Function: date->time-monotonic date
 - Function: date->time-tai date
 - Function: date->time-utc date

 - Function: julian-day->date jdn [tz-offset]
 - Function: julian-day->time-monotonic jdn
 - Function: julian-day->time-tai jdn
 - Function: julian-day->time-utc jdn

 - Function: modified-julian-day->date jdn [tz-offset]
 - Function: modified-julian-day->time-monotonic jdn
 - Function: modified-julian-day->time-tai jdn
 - Function: modified-julian-day->time-utc jdn

 - Function: time-monotonic->date time [tz-offset]
 - Function: time-monotonic->time-tai time
 - Function: time-monotonic->time-tai! time
 - Function: time-monotonic->time-utc time
 - Function: time-monotonic->time-utc! time

 - Function: time-tai->date time [tz-offset]
 - Function: time-tai->julian-day time
 - Function: time-tai->modified-julian-day time
 - Function: time-tai->time-monotonic time
 - Function: time-tai->time-monotonic! time
 - Function: time-tai->time-utc time
 - Function: time-tai->time-utc! time

 - Function: time-utc->date time [tz-offset]
 - Function: time-utc->julian-day time
 - Function: time-utc->modified-julian-day time
 - Function: time-utc->time-monotonic time
 - Function: time-utc->time-monotonic! time
 - Function: time-utc->time-tai time
 - Function: time-utc->time-tai! time

     Convert between dates, times and days of the respective types.  For
     instance `time-tai->time-utc' accepts a TIME object of type
     `time-tai' and returns an object of type `time-utc'.

     For conversions to dates, TZ-OFFSET is seconds east of Greenwich.
     The default is the local timezone.

     The `!' variants may modify their TIME argument to form their
     return.  The plain functions create a new object.

SRFI-19 Date to string
----------------------

 - Function: date->string date [format]
     Convert a date to a string under the control of a format.  FORMAT
     should be a string containing `~' escapes, which will be expanded
     as per the following conversion table.  The default FORMAT is
     `~c', a locale-dependent date and time.

     Many of these conversion characters are the same as POSIX
     `strftime' (*note Time::), but there are some extras and some
     variations.

     ~~     literal ~
     ~a     locale abbreviated weekday, eg. `Sun'
     ~A     locale full weekday, eg. `Sunday'
     ~b     locale abbreviated month, eg. `Jan'
     ~B     locale full month, eg. `January'
     ~c     locale date and time, eg.
            `Fri Jul 14 20:28:42-0400 2000'
     ~d     day of month, zero padded, `01' to `31'
     ~e     day of month, blank padded, ` 1' to `31'
     ~f     seconds and fractional seconds, with locale decimal
            point, eg. `5.2'
     ~h     same as ~b
     ~H     hour, 24-hour clock, zero padded, `00' to `23'
     ~I     hour, 12-hour clock, zero padded, `01' to `12'
     ~j     day of year, zero padded, `001' to `366'
     ~k     hour, 24-hour clock, blank padded, ` 0' to `23'
     ~l     hour, 12-hour clock, blank padded, ` 1' to `12'
     ~m     month, zero padded, `01' to `12'
     ~M     minute, zero padded, `00' to `59'
     ~n     newline
     ~N     nanosecond, zero padded, `000000000' to `999999999'
     ~p     locale AM or PM
     ~r     time, 12 hour clock, `~I:~M:~S ~p'
     ~s     number of full seconds since "the epoch" in UTC
     ~S     second, zero padded `00' to `60'
            (usual limit is 59, 60 is a leap second)
     ~t     horizontal tab character
     ~T     time, 24 hour clock, `~H:~M:~S'
     ~U     week of year, Sunday first day of week, `00' to `52'
     ~V     week of year, Monday first day of week, `01' to `53'
     ~w     day of week, 0 for Sunday, `0' to `6'
     ~W     week of year, Monday first day of week, `00' to `52'
     ~y     year, two digits, `00' to `99'
     ~Y     year, full, eg. `2003'
     ~z     time zone, RFC-822 style
     ~Z     time zone symbol (not-implemented)
     ~1     ISO-8601 date, `~Y-~m-~d'
     ~2     ISO-8601 time+zone, `~k:~M:~S~z'
     ~3     ISO-8601 time, `~k:~M:~S'
     ~4     ISO-8601 date/time+zone, `~Y-~m-~dT~k:~M:~S~z'
     ~5     ISO-8601 date/time, `~Y-~m-~dT~k:~M:~S'

Conversions `~D', `~x' and `~X' are currently not described here, since
the specification and reference implementation differ.

   Currently Guile doesn't implement any localizations for the above,
all outputs are in English, and the `~c' conversion is POSIX `ctime'
style `~a ~b ~d ~H:~M:~S~z ~Y'.  This may change in the future.

SRFI-19 String to date
----------------------

 - Function: string->date input template
     Convert an INPUT string to a date under the control of a TEMPLATE
     string.  Return a newly created date object.

     Literal characters in TEMPLATE must match characters in INPUT and
     `~' escapes must match the input forms described in the table
     below.  "Skip to" means characters up to one of the given type are
     ignored, or "no skip" for no skipping.  "Read" is what's then
     read, and "Set" is the field affected in the date object.

     For example `~Y' skips input characters until a digit is reached,
     at which point it expects a year and stores that to the year field
     of the date.

            Skip to            Read                        Set
     ~~     no skip            literal ~                   nothing
     ~a     char-alphabetic?   locale abbreviated weekday  nothing
                               name                        
     ~A     char-alphabetic?   locale full weekday name    nothing
     ~b     char-alphabetic?   locale abbreviated month    date-month
                               name                        
     ~B     char-alphabetic?   locale full month name      date-month
     ~d     char-numeric?      day of month                date-day
     ~e     no skip            day of month, blank padded  date-day
     ~h     same as `~b'                                   
     ~H     char-numeric?      hour                        date-hour
     ~k     no skip            hour, blank padded          date-hour
     ~m     char-numeric?      month                       date-month
     ~M     char-numeric?      minute                      date-minute
     ~S     char-numeric?      second                      date-second
     ~y     no skip            2-digit year                date-year within
                                                           50 years
     ~Y     char-numeric?      year                        date-year
     ~z     no skip            time zone                   date-zone-offset

     Notice that the weekday matching forms don't affect the date object
     returned, instead the weekday will be derived from the day, month
     and year.

     Currently Guile doesn't implement any localizations for the above,
     month and weekday names are always expected in English.  This may
     change in the future.