diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 3ba3da459bf..3ab4b66ba30 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1800,19 +1800,51 @@ structure (@pxref{Time Conversion}). The argument @var{string} should resemble an RFC 822 (or later) or ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or ``1998-09-12T12:21:54-0200'', but this function will attempt to parse less well-formed time strings as well. + +Note that, unlike @code{decode-time} (@pxref{Time Conversion}), this +function does not interpret the time string, and in particular the +values of daylight-saving and timezone or UTC offset parts of the +@var{string} argument do not affect the returned value of date and time, +they only affect the last two members of the returned decoded time +structure. For example, if the time-zone information is present in +@var{string}, the decoded time structure will include it; otherwise the +time-zone member of the returned value will be @code{nil}. In other +words, this function simply parses the textual representation of date +and time into separate numerical values, and doesn't care whether the +input time is local or UTC. + +If a Lisp program passes the return value of this function to some other +time-related API, it should make sure the @code{nil} members of the +decoded time structure are interpreted correctly, and in particular the +lack of time-zone information is interpreted as UTC or local time, +according to the needs of the calling program. @end defun @vindex ISO 8601 date/time strings @defun iso8601-parse string For a more strict function (that will error out upon invalid input), -this function can be used instead. It can parse all variants of -the ISO 8601 standard, so in addition to the formats mentioned above, -it also parses things like ``1998W45-3'' (week number) and -``1998-245'' (ordinal day number). To parse durations, there's +Lisp programs can use this function instead. It can parse all variants +of the ISO 8601 standard, so in addition to the formats mentioned above, +it also parses things like ``1998W45-3'' (week number) and ``1998-245'' +(ordinal day number). To parse durations, there's @code{iso8601-parse-duration}, and to parse intervals, there's -@code{iso8601-parse-interval}. All these functions return decoded -time structures, except the final one, which returns three of them -(the start, the end, and the duration). +@code{iso8601-parse-interval}. All these functions return decoded time +structures, except the final one, which returns three of them (the +start, the end, and the duration). + +Like @code{parse-time-string}, this function does not interpret the time +string, and in particular the time-zone designator or UTC offset that is +part of the @var{string} argument does not affect the returned value of +date and time, it only affects the last two members of the returned +decoded time structure. The ISO 8601 standard specifies that date/time +strings that do not include information about UTC relation are assumed +to be in local time, but this function does not do that, because it +doesn't interpret the time values. For example, if the time-zone +information is present in @var{string}, the decoded time structure will +include it; otherwise the time-zone member of the returned value will be +@code{nil}. In other words, this function simply parses the textual +representation of date and time into separate numerical values, and +doesn't care whether the input time is local or UTC. @end defun @defun format-time-string format-string &optional time zone diff --git a/lisp/calendar/iso8601.el b/lisp/calendar/iso8601.el index a32b52564c9..bb319d54c8c 100644 --- a/lisp/calendar/iso8601.el +++ b/lisp/calendar/iso8601.el @@ -122,10 +122,18 @@ (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\", +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). +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)) diff --git a/lisp/calendar/parse-time.el b/lisp/calendar/parse-time.el index c34329a4002..f6fc7a8c162 100644 --- a/lisp/calendar/parse-time.el +++ b/lisp/calendar/parse-time.el @@ -157,6 +157,12 @@ return a \"likely\" value even for somewhat malformed strings. The values returned are identical to those of `decode-time', but any unknown values other than DST are returned as nil, and an unknown DST value is returned as -1. +Note that, unlike `decode-time', this function does not interpret +the time string, and in particular the values of DST and TZ do not +affect the returned value of date and time, they only affect 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." (condition-case ()