Function: iso8601-parse

iso8601-parse is a byte-compiled function defined in iso8601.el.gz.

Signature

(iso8601-parse STRING &optional FORM)

Documentation

Parse an ISO 8601 date/time string and return a decode-time structure.

The ISO 8601 date/time strings look like "2008-03-02T13:47:30" or "2024-04-05T14:30Z" or "2024-04-05T12:30−02:00", but shorter, incomplete strings like "2008-03-02" are valid, as well as variants like "2008W32" (week number) and
"2008-234" (ordinal day number).
Values returned are identical to those of decode-time, except that an unknown DST value is -1 and other unknown values are nil.

Note that, unlike decode-time, this function does not interpret the time string, and in particular the time-zone designator or UTC offset that is part of STRING does not affect the returned value of date and time, it only affects the last two members of the returned value. This function simply parses the textual representation of date and time into separate numerical values, and doesn't care whether the time is local or UTC.

See decode-time for the meaning of FORM.

View in manual

Probably introduced at or before Emacs version 27.1.

Source Code

;; Defined in /usr/src/emacs/lisp/calendar/iso8601.el.gz
(defun iso8601-parse (string &optional form)
  "Parse an ISO 8601 date/time string and return a `decode-time' structure.

The ISO 8601 date/time strings look like \"2008-03-02T13:47:30\"
or \"2024-04-05T14:30Z\" or \"2024-04-05T12:30−02:00\",
but shorter, incomplete strings like \"2008-03-02\" are valid, as
well as variants like \"2008W32\" (week number) and
\"2008-234\" (ordinal day number).
Values returned are identical to those of `decode-time', except
that an unknown DST value is -1 and other unknown values are nil.

Note that, unlike `decode-time', this function does not interpret
the time string, and in particular the time-zone designator or UTC
offset that is part of STRING does not affect the returned value of
date and time, it only affects the last two members of the returned
value.  This function simply parses the textual representation of
date and time into separate numerical values, and doesn't care
whether the time is local or UTC.

See `decode-time' for the meaning of FORM."
  (if (not (iso8601-valid-p string))
      (signal 'wrong-type-argument (list string))
    (let* ((date-string (match-string 1 string))
           (time-string (match-string 2 string))
           (zone-string (match-string 3 string))
           (date (iso8601-parse-date date-string)))
      ;; The time portion is optional.
      (when time-string
        (let ((time (iso8601-parse-time time-string form)))
          (setf (decoded-time-hour date) (decoded-time-hour time))
          (setf (decoded-time-minute date) (decoded-time-minute time))
          (setf (decoded-time-second date) (decoded-time-second time))))
      ;; The time zone is optional.
      (when zone-string
        (setf (decoded-time-zone date)
              ;; The time zone in decoded times are in seconds.
	      (* (iso8601-parse-zone zone-string) 60))
	(setf (decoded-time-dst date) (iso8601--zone-dst zone-string)))
      date)))