238 lines
12 KiB
HTML
238 lines
12 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
|
||
|
|
<!Converted with LaTeX2HTML 0.6.5 (Tue Nov 15 1994) by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds >
|
||
|
|
<HEAD>
|
||
|
|
<TITLE>25.4.1. Time Functions</TITLE>
|
||
|
|
</HEAD>
|
||
|
|
<BODY>
|
||
|
|
<meta name="description" value=" Time Functions">
|
||
|
|
<meta name="keywords" value="clm">
|
||
|
|
<meta name="resource-type" value="document">
|
||
|
|
<meta name="distribution" value="global">
|
||
|
|
<P>
|
||
|
|
<b>Common Lisp the Language, 2nd Edition</b>
|
||
|
|
<BR> <HR><A NAME=tex2html4458 HREF="node233.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html4456 HREF="node231.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html4450 HREF="node231.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html4460 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html4461 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
||
|
|
<B> Next:</B> <A NAME=tex2html4459 HREF="node233.html"> Other Environment Inquiries</A>
|
||
|
|
<B>Up:</B> <A NAME=tex2html4457 HREF="node231.html"> Environment Inquiries</A>
|
||
|
|
<B> Previous:</B> <A NAME=tex2html4451 HREF="node231.html"> Environment Inquiries</A>
|
||
|
|
<HR> <P>
|
||
|
|
<H2><A NAME=SECTION002941000000000000000>25.4.1. Time Functions</A></H2>
|
||
|
|
<P>
|
||
|
|
<A NAME=TIMESECTION>Time</A>
|
||
|
|
is represented in three different ways in Common Lisp:
|
||
|
|
Decoded Time, Universal Time, and Internal Time.
|
||
|
|
The first two representations
|
||
|
|
are used primarily to represent calendar time and are
|
||
|
|
precise only to one second.
|
||
|
|
Internal Time is used primarily to represent measurements of computer
|
||
|
|
time (such as run time) and is precise to some implementation-dependent
|
||
|
|
fraction of a second, as specified by <tt>internal-time-units-per-second</tt>.
|
||
|
|
Decoded Time format is used only for absolute time indications.
|
||
|
|
Universal Time and Internal Time formats are used for both absolute
|
||
|
|
and relative times.
|
||
|
|
<P>
|
||
|
|
Decoded Time format represents calendar time as a number of components:
|
||
|
|
<UL><LI>
|
||
|
|
<i>Second</i>: an integer between 0 and 59, inclusive.
|
||
|
|
<P>
|
||
|
|
<LI>
|
||
|
|
<i>Minute</i>: an integer between 0 and 59, inclusive.
|
||
|
|
<P>
|
||
|
|
<LI>
|
||
|
|
<i>Hour</i>: an integer between 0 and 23, inclusive.
|
||
|
|
<P>
|
||
|
|
<LI>
|
||
|
|
<i>Date</i>: an integer between 1 and 31, inclusive (the upper limit actually
|
||
|
|
depends on the month and year, of course).
|
||
|
|
<P>
|
||
|
|
<LI>
|
||
|
|
<i>Month</i>: an integer between 1 and 12, inclusive; 1 means January,
|
||
|
|
12 means December.
|
||
|
|
<P>
|
||
|
|
<LI>
|
||
|
|
<i>Year</i>: an integer indicating the year A.D. However, if this integer
|
||
|
|
is between 0 and 99, the ``obvious'' year is used; more precisely,
|
||
|
|
that year is assumed that is equal to the integer modulo 100 and
|
||
|
|
within fifty years of the current year (inclusive backwards
|
||
|
|
and exclusive forwards). Thus, in the year 1978, year 28 is 1928
|
||
|
|
but year 27 is 2027. (Functions that return time in this format always return
|
||
|
|
a full year number.)
|
||
|
|
</UL>
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Compatibility note:</b> This is incompatible with the Lisp Machine Lisp definition
|
||
|
|
in two ways. First, in Lisp Machine Lisp a year between 0 and 99 always has 1900
|
||
|
|
added to it. Second, in Lisp Machine Lisp time functions return the abbreviated
|
||
|
|
year number between 0 and 99 rather than the full year number. The
|
||
|
|
incompatibility is prompted by the imminent arrival of the twenty-first
|
||
|
|
century. Note that <tt>(mod <i>year</i> 100)</tt> always reliably converts a
|
||
|
|
year number to the abbreviated form, while the inverse conversion can be
|
||
|
|
very difficult.
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
<UL><LI>
|
||
|
|
<i>Day-of-week</i>: an integer between 0 and 6, inclusive;
|
||
|
|
0 means Monday, 1 means Tuesday, and so on; 6 means Sunday.
|
||
|
|
<P>
|
||
|
|
<LI>
|
||
|
|
<i>Daylight-saving-time-p</i>: a flag that, if not <tt>nil</tt>, indicates that
|
||
|
|
daylight saving time is in effect.
|
||
|
|
<P>
|
||
|
|
<LI>
|
||
|
|
<i>Time-zone</i>: an integer specified as the number of hours west of GMT
|
||
|
|
(Greenwich Mean Time). For example, in Massachusetts the time zone is 5,
|
||
|
|
and in California it is 8. Any adjustment for daylight saving time is
|
||
|
|
separate from this.
|
||
|
|
</UL>
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in March 1989 (TIME-ZONE-NON-INTEGER) <A NAME=29143> </A>
|
||
|
|
to specify that the time zone part of Decoded Time need not be an integer,
|
||
|
|
but may be any rational number (either an integer or a ratio)
|
||
|
|
in the range -24 to 24 (inclusive on both ends)
|
||
|
|
that is an integral multiple of <tt>1/3600</tt>.
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Rationale:</b> For all possible time designations to be accommodated, it is
|
||
|
|
necessary to allow the time zone to be non-integral, for some places
|
||
|
|
in the world have time standards offset from Greenwich Mean Time
|
||
|
|
by a non-integral number of hours.
|
||
|
|
<P>
|
||
|
|
There appears to be no user demand for floating-point time zones. Since such
|
||
|
|
zones would introduce inexact arithmetic, X3J13 did not consider
|
||
|
|
adding them at this time.
|
||
|
|
<P>
|
||
|
|
This specification does require time zones to be represented as integral multiples
|
||
|
|
of 1 second (rather than 1 hour). This prevents problems that could otherwise
|
||
|
|
occur in converting Decoded Time to Universal Time.
|
||
|
|
<hr>
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
Universal Time represents time as a single non-negative integer.
|
||
|
|
For relative time
|
||
|
|
purposes, this is a number of seconds. For absolute time, this is the
|
||
|
|
number of seconds since midnight, January 1, 1900 GMT. Thus the time 1
|
||
|
|
is 00:00:01 (that is, 12:00:01 A.M.) on January 1, 1900 GMT.
|
||
|
|
Similarly, the time 2398291201 corresponds to time 00:00:01 on January 1,
|
||
|
|
1976 GMT.
|
||
|
|
Recall that the year 1900 was <i>not</i> a leap year; for the purposes of
|
||
|
|
Common Lisp, a year is a leap year if and only if its number is divisible by 4, except
|
||
|
|
that years divisible by 100 are <i>not</i> leap years, except that years
|
||
|
|
divisible by 400 <i>are</i> leap years. Therefore the year 2000 will
|
||
|
|
be a leap year.
|
||
|
|
(Note that the ``leap seconds'' that
|
||
|
|
are sporadically inserted by the world's official timekeepers as an additional
|
||
|
|
correction are ignored; Common Lisp assumes that every day is exactly 86400
|
||
|
|
seconds long.)
|
||
|
|
Universal Time format is used as a standard time
|
||
|
|
representation within the ARPANET; see reference [<A HREF="node368.html#KLHTIMESERVER">22</A>].
|
||
|
|
Because the Common Lisp Universal Time representation uses only
|
||
|
|
non-negative integers, times before the base time of midnight,
|
||
|
|
January 1, 1900 GMT cannot be processed by Common Lisp.
|
||
|
|
<P>
|
||
|
|
Internal Time also represents time as a single integer, but
|
||
|
|
in terms of an implementation-dependent unit.
|
||
|
|
Relative time is measured as a number of these units.
|
||
|
|
Absolute time is relative to an arbitrary time base, typically
|
||
|
|
the time at which the system began running.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>get-decoded-time</tt><P>The current time is returned in Decoded Time format. Nine values
|
||
|
|
are returned: <i>second</i>, <i>minute</i>, <i>hour</i>, <i>date</i>, <i>month</i>,
|
||
|
|
<i>year</i>, <i>day-of-week</i>, <i>daylight-saving-time-p</i>, and <i>time-zone</i>.
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Compatibility note:</b> In Lisp Machine Lisp <i>time-zone</i> is not currently returned.
|
||
|
|
Consider, however, the use of Common Lisp in some mobile vehicle.
|
||
|
|
It is entirely plausible that the time zone might change from time to time.
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>get-universal-time</tt><P>The current time of day is returned as a single integer
|
||
|
|
in Universal Time format.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>decode-universal-time <i>universal-time</i> &optional <i>time-zone</i></tt><P>The time specified by <i>universal-time</i> in Universal Time format
|
||
|
|
is converted to Decoded Time format. Nine values
|
||
|
|
are returned: <i>second</i>, <i>minute</i>, <i>hour</i>, <i>date</i>, <i>month</i>,
|
||
|
|
<i>year</i>, <i>day-of-week</i>, <i>daylight-saving-time-p</i>, and <i>time-zone</i>.
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Compatibility note:</b> In Lisp Machine Lisp <i>time-zone</i> is not currently returned.
|
||
|
|
Consider, however, the use of Common Lisp in some mobile vehicle.
|
||
|
|
It is entirely plausible that the time zone might change from time to time.
|
||
|
|
<hr>
|
||
|
|
The <i>time-zone</i> argument defaults to the current time zone.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in January 1989
|
||
|
|
(DECODE-UNIVERSAL-TIME-DAYLIGHT) <A NAME=29189> </A>
|
||
|
|
to specify that <tt>decode-universal-time</tt>,
|
||
|
|
like <tt>encode-universal-time</tt>, ignores daylight saving time information
|
||
|
|
if a <i>time-zone</i> is explicitly specified; in this case
|
||
|
|
the returned <i>daylight-saving-time-p</i> value will necessarily be
|
||
|
|
<tt>nil</tt> even if daylight saving time happens to be in effect in that
|
||
|
|
time zone at the specified time.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>encode-universal-time <i>second</i> <i>minute</i> <i>hour</i> <i>date</i> <i>month</i> <i>year</i> &optional <i>time-zone</i> </tt><P>The time specified by the given components of Decoded Time format is
|
||
|
|
encoded into Universal Time format and returned. If you do not specify
|
||
|
|
<i>time-zone</i>, it defaults to the current time zone adjusted for daylight
|
||
|
|
saving time. If you provide <i>time-zone</i> explicitly, no adjustment for
|
||
|
|
daylight saving time is performed.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Constant]</b><BR>
|
||
|
|
<tt>internal-time-units-per-second</tt><P>This value is an integer, the implementation-dependent
|
||
|
|
number of internal time units in a second. (The internal time unit must
|
||
|
|
be chosen so that one second is an integral multiple of it.)
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Rationale:</b> The reason for allowing the internal time
|
||
|
|
units to be implementation-dependent is so that
|
||
|
|
<tt>get-internal-run-time</tt> and <tt>get-internal-real-time</tt>
|
||
|
|
can execute with minimum overhead.
|
||
|
|
The idea is that it should be very likely that a fixnum will suffice as the
|
||
|
|
returned value from these functions. This probability can be
|
||
|
|
tuned to the implementation by trading off the speed of the machine
|
||
|
|
against the word size. Any particular unit will
|
||
|
|
be inappropriate for some implementations: a microsecond is too long
|
||
|
|
for a very fast machine, while a much smaller unit would
|
||
|
|
force many implementations to return bignums for most calls
|
||
|
|
to <tt>get-internal-time</tt>, rendering that function less useful for accurate
|
||
|
|
timing measurements.
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>get-internal-run-time</tt><P>The current run time is returned as a single integer in Internal Time
|
||
|
|
format.
|
||
|
|
The precise meaning of this quantity is implementation-dependent;
|
||
|
|
it may measure real time, run time, CPU cycles, or some other quantity.
|
||
|
|
The intent is that the difference between the values of two calls
|
||
|
|
to this function be the amount of time between the two calls
|
||
|
|
during which computational effort was expended on behalf of the
|
||
|
|
executing program.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>get-internal-real-time</tt><P>The current time is returned as a single integer in Internal Time
|
||
|
|
format. This time is relative to an arbitrary time base,
|
||
|
|
but the difference between the values of two calls
|
||
|
|
to this function will be the amount of elapsed real time between the two calls,
|
||
|
|
measured in the units defined by <tt>internal-time-units-per-second</tt>.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>sleep <i>seconds</i></tt><P><tt>(sleep <i>n</i>)</tt> causes execution to cease and become dormant for
|
||
|
|
approximately <i>n</i> seconds of real time, whereupon execution is resumed.
|
||
|
|
The argument may be any non-negative non-complex number.
|
||
|
|
<tt>sleep</tt> returns <tt>nil</tt>.
|
||
|
|
<P>
|
||
|
|
<BR> <HR><A NAME=tex2html4458 HREF="node233.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html4456 HREF="node231.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html4450 HREF="node231.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html4460 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html4461 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
||
|
|
<B> Next:</B> <A NAME=tex2html4459 HREF="node233.html"> Other Environment Inquiries</A>
|
||
|
|
<B>Up:</B> <A NAME=tex2html4457 HREF="node231.html"> Environment Inquiries</A>
|
||
|
|
<B> Previous:</B> <A NAME=tex2html4451 HREF="node231.html"> Environment Inquiries</A>
|
||
|
|
<HR> <P>
|
||
|
|
<HR>
|
||
|
|
<P><ADDRESS>
|
||
|
|
AI.Repository@cs.cmu.edu
|
||
|
|
</ADDRESS>
|
||
|
|
</BODY>
|