From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Kevin Ryde Newsgroups: gmane.lisp.guile.devel Subject: doc srfi1-19 date/time Date: Wed, 03 Sep 2003 08:49:21 +1000 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <87znhmlsb2.fsf@zip.com.au> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1062623461 11587 80.91.224.253 (3 Sep 2003 21:11:01 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 3 Sep 2003 21:11:01 +0000 (UTC) Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Wed Sep 03 23:10:59 2003 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19ueu2-0000av-00 for ; Wed, 03 Sep 2003 23:10:58 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.22) id 19ueto-00056S-Ei for guile-devel@m.gmane.org; Wed, 03 Sep 2003 17:10:44 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.22) id 19uKws-0000MI-Jl for guile-devel@gnu.org; Tue, 02 Sep 2003 19:52:34 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.22) id 19uKr2-0007cn-Gi for guile-devel@gnu.org; Tue, 02 Sep 2003 19:46:40 -0400 Original-Received: from [199.232.41.8] (helo=mx20.gnu.org) by monty-python.gnu.org with esmtp (TLSv1:DES-CBC3-SHA:168) (Exim 4.22) id 19uKGJ-0006qG-G3 for guile-devel@gnu.org; Tue, 02 Sep 2003 19:08:35 -0400 Original-Received: from [61.8.0.36] (helo=snoopy.pacific.net.au) by mx20.gnu.org with esmtp (Exim 4.22) id 19uK8G-0002G4-Rv for guile-devel@gnu.org; Tue, 02 Sep 2003 19:00:17 -0400 Original-Received: from mongrel.pacific.net.au (mongrel.pacific.net.au [61.8.0.107]) by snoopy.pacific.net.au (8.12.3/8.12.3/Debian-6.4) with ESMTP id h82N0CBt019210 for ; Wed, 3 Sep 2003 09:00:12 +1000 Original-Received: from localhost (ppp97.dyn228.pacific.net.au [203.143.228.97]) by mongrel.pacific.net.au (8.12.3/8.12.3/Debian-6.4) with ESMTP id h82MwwBC023908 for ; Wed, 3 Sep 2003 08:58:59 +1000 Original-Received: from gg by localhost with local (Exim 3.35 #1 (Debian)) id 19uJxh-0000bU-00; Wed, 03 Sep 2003 08:49:21 +1000 Original-To: guile-devel@gnu.org Mail-Copies-To: never User-Agent: Gnus/5.090019 (Oort Gnus v0.19) Emacs/21.3 (gnu/linux) X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Developers list for Guile, the GNU extensibility library List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.devel:2743 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2743 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 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. _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel