Time Conversion
===============
These functions convert time values (lists of two or three integers)
to strings or to calendrical information. There is also a function to
convert calendrical information to a time value. You can get time
values from the functions `current-time' (Note:Time of Day) and
`file-attributes' (Note:File Attributes).
Many operating systems are limited to time values that contain 32
bits of information; these systems typically handle only the times from
1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
operating systems have larger time values, 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: format-time-string format-string &optional time universal
This function converts TIME (or the current time, if TIME is
omitted) to a string according to FORMAT-STRING. The argument
FORMAT-STRING may contain `%'-sequences which say to substitute
parts of the time. Here is a table of what the `%'-sequences mean:
`%a'
This stands for the abbreviated name of the day of week.
`%A'
This stands for the full name of the day of week.
`%b'
This stands for the abbreviated name of the month.
`%B'
This stands for the full name of the month.
`%c'
This is a synonym for `%x %X'.
`%C'
This has a locale-specific meaning. In the default locale
(named C), it is equivalent to `%A, %B %e, %Y'.
`%d'
This stands for the day of month, zero-padded.
`%D'
This is a synonym for `%m/%d/%y'.
`%e'
This stands for the day of month, blank-padded.
`%h'
This is a synonym for `%b'.
`%H'
This stands for the hour (00-23).
`%I'
This stands for the hour (01-12).
`%j'
This stands for the day of the year (001-366).
`%k'
This stands for the hour (0-23), blank padded.
`%l'
This stands for the hour (1-12), blank padded.
`%m'
This stands for the month (01-12).
`%M'
This stands for the minute (00-59).
`%n'
This stands for a newline.
`%p'
This stands for `AM' or `PM', as appropriate.
`%r'
This is a synonym for `%I:%M:%S %p'.
`%R'
This is a synonym for `%H:%M'.
`%S'
This stands for the seconds (00-59).
`%t'
This stands for a tab character.
`%T'
This is a synonym for `%H:%M:%S'.
`%U'
This stands for the week of the year (01-52), assuming that
weeks start on Sunday.
`%w'
This stands for the numeric day of week (0-6). Sunday is day
0.
`%W'
This stands for the week of the year (01-52), assuming that
weeks start on Monday.
`%x'
This has a locale-specific meaning. In the default locale
(named `C'), it is equivalent to `%D'.
`%X'
This has a locale-specific meaning. In the default locale
(named `C'), it is equivalent to `%T'.
`%y'
This stands for the year without century (00-99).
`%Y'
This stands for the year with century.
`%Z'
This stands for the time zone abbreviation.
You can also specify the field width and type of padding for any of
these `%'-sequences. This works as in `printf': you write the
field width as digits in the middle of a `%'-sequences. If you
start the field width with `0', it means to pad with zeros. If you
start the field width with `_', it means to pad with spaces.
For example, `%S' specifies the number of seconds since the minute;
`%03S' means to pad this with zeros to 3 positions, `%_3S' to pad
with spaces to 3 positions. Plain `%3S' pads with zeros, because
that is how `%S' normally pads to two positions.
The characters `E' and `O' act as modifiers when used between `%'
and one of the letters in the table above. `E' specifies using
the current locale's "alternative" version of the date and time.
In a Japanese locale, for example, `%Ex' might yield a date format
based on the Japanese Emperors' reigns. `E' is allowed in `%Ec',
`%EC', `%Ex', `%EX', `%Ey', and `%EY'.
`O' means to use the current locale's "alternative" representation
of numbers, instead of the ordinary decimal digits. This is
allowed with most letters, all the ones that output numbers.
If UNIVERSAL is non-`nil', that means to describe the time as
Universal Time; `nil' means describe it using what Emacs believes
is the local time zone (see `current-time-zone').
This function uses the C library function `strftime' to do most of
the work. In order to communicate with that function, it first
encodes its argument using the coding system specified by
`locale-coding-system' (Note:Locales); after `strftime' returns
the resulting string, `format-time-string' decodes the string
using that same coding system.
- Function: decode-time time
This function converts a time value into calendrical information.
The return value is a list of nine elements, as follows:
(SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
Here is what the elements mean:
SECONDS
The number of seconds past the minute, as an integer between
0 and 59.
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 savings time is effect, otherwise `nil'.
ZONE
An integer indicating the time zone, as the number of seconds
east of Greenwich.
*Common Lisp Note:* Common Lisp has different meanings for DOW and
ZONE.
- 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 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 and
its daylight savings time rules. If specified, it can be either a
list (as you would get from `current-time-zone'), a string as in
the `TZ' environment variable, or an integer (as you would get from
`decode-time'). The specified zone is used without any further
alteration for daylight savings 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.