25.4.1. Time Functions

Common Lisp the Language, 2nd Edition

Next: Other Environment Inquiries Up: Environment Inquiries Previous: Environment Inquiries

25.4.1. Time Functions

Time 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 internal-time-units-per-second. Decoded Time format is used only for absolute time indications. Universal Time and Internal Time formats are used for both absolute and relative times.

Decoded Time format represents calendar time as a number of components:

Second: an integer between 0 and 59, inclusive.
Minute: an integer between 0 and 59, inclusive.
Hour: an integer between 0 and 23, inclusive.
Date: an integer between 1 and 31, inclusive (the upper limit actually depends on the month and year, of course).
Month: an integer between 1 and 12, inclusive; 1 means January, 12 means December.
Year: 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.)

Compatibility note: 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 (mod year 100) always reliably converts a year number to the abbreviated form, while the inverse conversion can be very difficult.

Day-of-week: an integer between 0 and 6, inclusive; 0 means Monday, 1 means Tuesday, and so on; 6 means Sunday.
Daylight-saving-time-p: a flag that, if not nil, indicates that daylight saving time is in effect.
Time-zone: 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.

change_begin
X3J13 voted in March 1989 (TIME-ZONE-NON-INTEGER) 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 1/3600.

Rationale: 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.

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.

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.

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 not 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 not leap years, except that years divisible by 400 are 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 [22]. 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.

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.

[Function]
get-decoded-time

The current time is returned in Decoded Time format. Nine values are returned: second, minute, hour, date, month, year, day-of-week, daylight-saving-time-p, and time-zone.

Compatibility note: In Lisp Machine Lisp time-zone 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.

[Function]
get-universal-time

The current time of day is returned as a single integer in Universal Time format.

[Function]
decode-universal-time universal-time &optional time-zone

The time specified by universal-time in Universal Time format is converted to Decoded Time format. Nine values are returned: second, minute, hour, date, month, year, day-of-week, daylight-saving-time-p, and time-zone.

The time-zone argument defaults to the current time zone.

change_begin
X3J13 voted in January 1989 (DECODE-UNIVERSAL-TIME-DAYLIGHT) to specify that decode-universal-time, like encode-universal-time, ignores daylight saving time information if a time-zone is explicitly specified; in this case the returned daylight-saving-time-p value will necessarily be nil even if daylight saving time happens to be in effect in that time zone at the specified time.
change_end

[Function]
encode-universal-time second minute hour date month year &optional time-zone

The time specified by the given components of Decoded Time format is encoded into Universal Time format and returned. If you do not specify time-zone, it defaults to the current time zone adjusted for daylight saving time. If you provide time-zone explicitly, no adjustment for daylight saving time is performed.

[Constant]
internal-time-units-per-second

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.)

Rationale: The reason for allowing the internal time units to be implementation-dependent is so that get-internal-run-time and get-internal-real-time 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 get-internal-time, rendering that function less useful for accurate timing measurements.

[Function]
get-internal-run-time

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.

[Function]
get-internal-real-time

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 internal-time-units-per-second.

[Function]
sleep seconds

(sleep n) causes execution to cease and become dormant for approximately n seconds of real time, whereupon execution is resumed. The argument may be any non-negative non-complex number. sleep returns nil.

Next: Other Environment Inquiries Up: Environment Inquiries Previous: Environment Inquiries

AI.Repository@cs.cmu.edu