Skip to main content

decode-universal-time

decode-universal-time Function

Syntax:

decode-universal-time universal-time &optional time-zone

→ second, minute, hour, date, month, year, day, daylight-p, zone

Arguments and Values:

universal-time—a universal time.

time-zone—a time zone.

second, minute, hour, date, month, year, day, daylight-p, zone—a decoded time.

Description:

Returns the decoded time represented by the given universal time.

If time-zone is not supplied, it defaults to the current time zone adjusted for daylight saving time. If time-zone is supplied, daylight saving time information is ignored. The daylight saving time flag is nil if time-zone is supplied.

Examples:

(decode-universal-time 0 0) → 0, 0, 0, 1, 1, 1900, 0, *false*, 0 
;; The next two examples assume Eastern Daylight Time. 
(decode-universal-time 2414296800 5) → 0, 0, 1, 4, 7, 1976, 6, *false*, 5 
(decode-universal-time 2414293200) → 0, 0, 1, 4, 7, 1976, 6, *true*, 5 
;; This example assumes that the time zone is Eastern Daylight Time 
;; (and that the time zone is constant throughout the example). 
(let\* ((here (nth 8 (multiple-value-list (get-decoded-time)))) ;Time zone 
	(recently (get-universal-time)) 
	(a (nthcdr 7 (multiple-value-list (decode-universal-time recently)))) 
	(b (nthcdr 7 (multiple-value-list (decode-universal-time recently here))))) 
       (list a b (equal a b))) → ((T 5) (NIL 5) NIL)

Affected By:

Implementation-dependent mechanisms for calculating when or if daylight savings time is in effect for any given session.

See Also:

encode-universal-time, get-universal-time, Section 25.1.4 (Time)

Expanded Reference: decode-universal-time​

Decoding a universal time into components​

decode-universal-time converts a universal time integer into nine values: second, minute, hour, date, month, year, day-of-week, daylight-saving-time-p, and time-zone.

(multiple-value-bind (sec min hour date month year dow)
    (decode-universal-time 0 0)
  (list sec min hour date month year dow))
=> (0 0 0 1 1 1900 0)

Decoding the current time​

Combined with get-universal-time, you can decode the current time.

(multiple-value-bind (sec min hour day month year)
    (decode-universal-time (get-universal-time))
  (stringp (format nil "~4D-~2,'0D-~2,'0D ~2,'0D:~2,'0D:~2,'0D"
                   year month day hour min sec)))
;; => T

Specifying a time zone​

The optional second argument specifies a time zone (hours west of Greenwich). Without it, the local time zone is used.

;; Decode in UTC (time zone 0)
(multiple-value-bind (sec min hour day month year)
    (decode-universal-time (encode-universal-time 0 0 12 15 4 2025 0) 0)
  (list year month day hour min sec))
=> (2025 4 15 12 0 0)

;; Decode in US Eastern time (zone 5)
(multiple-value-bind (sec min hour day month year)
    (decode-universal-time (encode-universal-time 0 0 12 15 4 2025 0) 5)
  (list year month day hour min sec))
=> (2025 4 15 7 0 0)

Day-of-week encoding​

The day-of-week value is an integer: 0 for Monday through 6 for Sunday.

(nth-value 6 (decode-universal-time
               (encode-universal-time 0 0 12 15 4 2025 0)))
=> 1