From: Kevin Ryde <user42@zip.com.au>
Subject: doc srfi1-19 date/time
Date: Wed, 03 Sep 2003 08:49:21 +1000 [thread overview]
Message-ID: <87znhmlsb2.fsf@zip.com.au> (raw)
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.
_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel
reply other threads:[~2003-09-02 22:49 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87znhmlsb2.fsf@zip.com.au \
--to=user42@zip.com.au \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).