1

After reading the documentation of encode-time and decode-time I'm not understanding how they work.

My trouble from comes from the fact that encode-time returns two values, whereas I'm expecting only one (the number of seconds since the UNIX epoch). What do these two values mean exactly?

ELISP> (encode-time 0 0 0 1 1 1970 t)
(0 0)
ELISP> (encode-time 0 0 0 1 1 1971 t)
(481 13184)

I get even more confused because these three calls work, but I don't understand how to interpret the argument in the first two cases:

;; Ok this is what I expect from the documentation
ELISP> (decode-time
        (encode-time 0 0 0 1 1 1971 t))
(0 0 0 1 1 1971 5 nil 0)

;; This is also what I expected, given it's the same than above, but I don't understand the meaning of the arguments
ELISP> (decode-time '(481 13184))
(0 0 0 1 1 1971 5 nil 0)

;; I kind of understand the following: here 481  is considered the seconds since UNIX epoch,
;; and 13184 is the difference in seconds from UTC.
;; The returned value, is the date (UNIX epoch + 481 seconds)
;; expressed in a timezone 13184 seconds ahead of UTC (45 47 3 1 1 1970 = 13665 seconds
;; and 13665−13184 = 481) 
ELISP> (decode-time 481 13184)
(45 47 3 1 1 1970 4 nil 13184)

Note that for all the examples above I have set (set-time-zone-rule t) to avoid having to deal with timezones.

2 Answers 2

2

(481 131184) represents the number of seconds as (HIGH LOW) where HIGH is the upper bits and LOW is the lower 16 bits. I.e. the real number of seconds is

(+ (* 481 65536) 13184) == 31536000
1

Looking at the documentation:

(decode-time &optional TIME ZONE)

Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST UTCOFF). The optional TIME should be a list of (HIGH LOW . IGNORED), as from ‘current-time’ and ‘file-attributes’, or nil to use the current time. It can also be a single integer number of seconds since the epoch. The obsolete form (HIGH . LOW) is also still accepted.

So we can see that the expected format is a list with the values "HIGH" and "LOW" (and maybe some extra information). Following that direction to current-time gives us further explanation:

(current-time)

Return the current time, as the number of seconds since 1970-01-01 00:00:00. The time is returned as a list of integers (HIGH LOW USEC PSEC). HIGH has the most significant bits of the seconds, while LOW has the least significant 16 bits. USEC and PSEC are the microsecond and picosecond counts.

Why does Emacs use this seemingly-complicated format? Undoubtedly the answer is simply that Emacs is old, and it needed to work with systems where only 16-bit integers were available.

Looking to the manual, M-x elisp-index-search for current-time takes us to (elisp)Time of Day:

Most of these functions represent time as a list of four integers ‘(SEC-HIGH SEC-LOW MICROSEC PICOSEC)’. This represents the number of seconds from the “epoch” (January 1, 1970 at 00:00 UTC), using the formula: HIGH * 2**16 + LOW + MICRO * 10**−6 + PICO * 10**−12. The return value of ‘current-time’ represents time using this form, as do the timestamps in the return values of other functions such as ‘file-attributes’ (*note Definition of file-attributes::). In some cases, functions may return two- or three-element lists, with omitted MICROSEC and PICOSEC components defaulting to zero.

Function arguments, e.g., the TIME argument to ‘current-time-string’, accept a more-general “time value” format, which can be a list of integers as above, or a single number for seconds since the epoch, or ‘nil’ for the current time. You can convert a time value into a human-readable string using ‘current-time-string’ and ‘format-time-string’, into a list of integers using ‘seconds-to-time’, and into other forms using ‘decode-time’ and ‘float-time’. These functions are described in the following sections.

Hence you can, for example, pass a single 32-bit Unix timestamp integer to decode-time

(decode-time 1554670400)
=> (20 53 8 8 4 2019 1 nil 43200)

You can also use format-time-string to obtain a single integer value:

(string-to-number (format-time-string "%s" (current-time)))

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.