Flushed obsolete doc file.
This commit is contained in:
shivers
parent
79ee1de13c
commit
8e510db64c
|
|
@ -1,161 +0,0 @@
|
|||
Scsh time interface
|
||||
Olin Shivers
|
||||
November, 1994
|
||||
|
||||
* Discussion
|
||||
|
||||
Jargon:
|
||||
"UTC" and "UCT" stand for "universal coordinated time," which is the
|
||||
official name for what is colloquially referred to as "Greenwich Mean
|
||||
Time."
|
||||
|
||||
Posix allows a single time zone to specify *two* different offsets from
|
||||
UTC: one standard one, and one for "summer time." Summer time is frequently
|
||||
some sort of daylight savings time.
|
||||
|
||||
The scsh time package consistently uses this jargon: we never say
|
||||
"gmt" or "dst;" we always say "utc" and "summer time."
|
||||
|
||||
We have two types: time and date.
|
||||
|
||||
A TIME specifies an instant in the history of the universe.
|
||||
It is location and time-zone independent. A time is specified
|
||||
by giving the number of elapsed seconds since the Unix "epoch"
|
||||
(Midnight, January 1, 1970 UTC).
|
||||
|
||||
A DATE is a name for an instant in time that is specified
|
||||
relative to some location/time-zone in the world, for example
|
||||
Friday October 31, 1994 3:47:21 pm
|
||||
What instant this date specifies depends on where you are. If I phone a Hong
|
||||
Kong friend from Cambridge, Massachusetts, then the current TIME is the same
|
||||
for both of us, but it has different DATES -- Hong Kong is 12 hours ahead
|
||||
of Cambridge.
|
||||
|
||||
(define-record date ; A Posix tm struct
|
||||
seconds ; Seconds after the minute (0-59)
|
||||
minute ; Minutes after the hour (0-59)
|
||||
hour ; Hours since midnight (0-23)
|
||||
month-day ; Day of the month (1-31)
|
||||
month ; Months since January (0-11)
|
||||
year ; Years since 1900
|
||||
summer? ; Summer (e.g., Daylight Savings) time in effect?
|
||||
week-day ; Days since Sunday (0-6) These two fields
|
||||
year-day) ; Days since Jan. 1 (0-365) are redundant.
|
||||
|
||||
(make-date seconds minute hour month-day month year
|
||||
[summer? week-day year-day])
|
||||
When making a DATE, the last three elements of the record are optional,
|
||||
and default to #f, 0, and 0 respectively. This is useful when creating
|
||||
a DATE record to pass to TIME->DATE.
|
||||
|
||||
Notice that the value of SUMMER? resolves amiguous boundary cases. For
|
||||
example, on the morning of the Fall daylight savings change-over, 1:00am -
|
||||
2:00am happens twice. Hence the date 1:30:00 on this morning can specify two
|
||||
different seconds; the SUMMER? flag says which one.
|
||||
|
||||
Specifying time zones:
|
||||
Several time procedures time time zones as arguments. When optional,
|
||||
the time zone defaults to local time zone. Otherwise the time zone
|
||||
can be one of:
|
||||
#f Local time
|
||||
Integer Seconds of offset from UTC. For example,
|
||||
New York City is -18000 (-5 hours), San Francisco
|
||||
is -28800 (-8 hours).
|
||||
String A Posix time zone string understood by the OS
|
||||
(i.e., the sort of time zone assigned to the $TZ
|
||||
environment variable).
|
||||
An integer time zone gives the number of seconds you must add to UTC
|
||||
to get time in that zone. It is *not* "seconds west" of UTC -- that flips
|
||||
the sign.
|
||||
|
||||
To get UTC time, use a time zone of either 0 or "UCT0".
|
||||
|
||||
|
||||
* Procedures
|
||||
|
||||
(utime) -> [secs usecs]
|
||||
The current time. UTIME provies micro-second resolution.
|
||||
Sub-second resolution is not provided by Posix, but is in BSD.
|
||||
If the OS does not support sub-second resolution, the USECS value
|
||||
is always 0.
|
||||
|
||||
(date) -> date
|
||||
The current date, in the local time zone.
|
||||
(date [time tz]) -> date
|
||||
Converts the time to the date as specified by the time zone TZ.
|
||||
TIME defaults to the current time; TZ defaults to local time,
|
||||
and is as described above.
|
||||
|
||||
(time) -> int
|
||||
The current time.
|
||||
(time [date tz]) -> int
|
||||
Converts a date to a time as specified by the time zone TZ.
|
||||
DATE defaults to the current date; TZ defaults to local time,
|
||||
and is as described above.
|
||||
|
||||
A DATE record is overconstrained; TIME ignores the DATE's
|
||||
WEEK-DAY and YEAR-DAY fields.
|
||||
|
||||
When passed to TIME, the SUMMER? field has the following meaning:
|
||||
#f Resolve an ambiguous time in favor of non-summer time.
|
||||
#t Resolve an ambiguous time in favor of summer time.
|
||||
This is useful in boundary cases during the change-over. For example,
|
||||
in the Fall, when US daylight savings time changes over at 2:00 am,
|
||||
1:30 am happens twice -- it names two instants in time, an hour apart.
|
||||
|
||||
Outside of these boundary cases, the SUMMER? flag is *ignored*. For
|
||||
example, if the standard/summer change-overs happen in the Fall and the
|
||||
Spring, then the value of SUMMER? is ignored for a January or July date.
|
||||
A January date would be resolved with standard time, and a July date with
|
||||
summer time, regardless of the SUMMER? value.
|
||||
|
||||
The SUMMER? flag is also ignored if the time zone doesn't have a summer
|
||||
time -- for example, an integer time zone, or simple UTC.
|
||||
|
||||
|
||||
(date->string date) -> string
|
||||
(time->string time [tz]) -> string
|
||||
(format-date fmt date [tz]) -> string
|
||||
These have Posix analogs. FORMAT-DATE's time zone argument is only
|
||||
used when one requests the time zone in the formatted string.
|
||||
|
||||
(utc-offset [time tz])
|
||||
Returns the offset from UTC of time zone TZ at instant TIME.
|
||||
TIME defaults to the current time; TZ defaults to local time,
|
||||
and is as specified above.
|
||||
|
||||
The offset is the number of seconds you add to UTC time to get
|
||||
local time.
|
||||
|
||||
Note: Be aware that other time interfaces (e.g., the BSD C interface)
|
||||
give offsets as seconds *west* of UTC, which flips the sign. The scsh
|
||||
definition is chosen for arithmetic simplicity. It's easy to remember
|
||||
the definition of the offset: what you add to UTC to get local.
|
||||
|
||||
(time-zone [summer? tz])
|
||||
Returns the name of the time zone as a string. SUMMER? is
|
||||
used to choose between the summer name and the standard name (e.g.,
|
||||
"EST" and "EDT"). SUMMER? is interpreted as follows:
|
||||
Integer A TIME value. The variant in use at that time
|
||||
is returned.
|
||||
#f The standard time name is returned.
|
||||
Otherwise The summer time name is returned.
|
||||
SUMMER? defaults to the case that pertains at the time of the call.
|
||||
It is ignored if the time zone doesn't have a summer variant.
|
||||
|
||||
We need a general date/time parser.
|
||||
|
||||
DATE has two more fields: tz-secs and tz-name.
|
||||
TIME->DATE: These are set.
|
||||
tz-secs is the offset from UTC for the instant this date specifies.
|
||||
It includes summer time adjustments.
|
||||
|
||||
TZ=#f: tz-name is constructed from tzname[] and tz-secs.
|
||||
TZ string: tz-name is constructed from tzname[] and tz-secs.
|
||||
TZ int: tz-name is of form UTChh:mm:ss ?? or #f ??
|
||||
|
||||
DATE->TIME:
|
||||
tz-secs integer: It is used for conversion.
|
||||
summer? is ignored.
|
||||
otw: time zone taken from tz-name, with #f meaning "local time."
|
||||
summer? is used, if the time zone is a dual one.
|
||||
Loading…
Reference in New Issue