elisp: Time Conversion
38.7 Time Conversion
====================
These functions convert time values (
Time of Day) into
calendrical information and vice versa.
Many 32-bit operating systems are limited to system times containing
32 bits of information in their seconds component; these systems
typically handle only the times from 1901-12-13 20:45:52 through
2038-01-19 03:14:07 Universal Time. However, 64-bit and some 32-bit
operating systems have larger seconds components, and can represent
times far in the past or future.
Time conversion functions always use the Gregorian calendar, even for
dates before the Gregorian calendar was introduced. Year numbers count
the number of years since the year 1 B.C., and do not skip zero as
traditional Gregorian years do; for example, the year number −37
represents the Gregorian year 38 B.C.
-- Function: decode-time &optional time zone
This function converts a time value into calendrical information.
If you don’t specify TIME, it decodes the current time, and
similarly ZONE defaults to the current time zone rule. Time
Zone Rules. The return value is a list of nine elements, as
follows:
(SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST UTCOFF)
Here is what the elements mean:
SECONDS
The number of seconds past the minute, as an integer between 0
and 59. On some operating systems, this is 60 for leap
seconds.
MINUTES
The number of minutes past the hour, as an integer between 0
and 59.
HOUR
The hour of the day, as an integer between 0 and 23.
DAY
The day of the month, as an integer between 1 and 31.
MONTH
The month of the year, as an integer between 1 and 12.
YEAR
The year, an integer typically greater than 1900.
DOW
The day of week, as an integer between 0 and 6, where 0 stands
for Sunday.
DST
‘t’ if daylight saving time is effect, otherwise ‘nil’.
UTCOFF
An integer indicating the Universal Time offset in seconds,
i.e., the number of seconds east of Greenwich.
*Common Lisp Note:* Common Lisp has different meanings for DOW and
UTCOFF.
-- Function: encode-time seconds minutes hour day month year &optional
zone
This function is the inverse of ‘decode-time’. It converts seven
items of calendrical data into a list-of-integer time value. For
the meanings of the arguments, see the table above under
‘decode-time’.
Year numbers less than 100 are not treated specially. If you want
them to stand for years above 1900, or years above 2000, you must
alter them yourself before you call ‘encode-time’.
The optional argument ZONE defaults to the current time zone rule.
Time Zone Rules. In addition to the usual time zone rule
values, it can also be a list (as you would get from
‘current-time-zone’) or an integer (as from ‘decode-time’), applied
without any further alteration for daylight saving time.
If you pass more than seven arguments to ‘encode-time’, the first
six are used as SECONDS through YEAR, the last argument is used as
ZONE, and the arguments in between are ignored. This feature makes
it possible to use the elements of a list returned by ‘decode-time’
as the arguments to ‘encode-time’, like this:
(apply 'encode-time (decode-time ...))
You can perform simple date arithmetic by using out-of-range values
for the SECONDS, MINUTES, HOUR, DAY, and MONTH arguments; for
example, day 0 means the day preceding the given month.
The operating system puts limits on the range of possible time
values; if you try to encode a time that is out of range, an error
results. For instance, years before 1970 do not work on some
systems; on others, years as early as 1901 do work.
Info Catalog
elisp: Time Zone Rules
elisp: System Interface
elisp: Time Parsing