From 7a828c938ca9daf37baa02a50bb6463e2b7c0b85 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Mon, 12 Aug 2024 14:31:19 -0700 Subject: [PATCH] Document time-parsing functions a bit better See --- doc/lispref/os.texi | 26 +++++++++++++++++++------- lisp/calendar/iso8601.el | 10 +++++----- lisp/calendar/parse-time.el | 5 ++--- 3 files changed, 26 insertions(+), 15 deletions(-) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 3ba3da459bf..5839de4a650 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1800,19 +1800,31 @@ Time Parsing 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. +It parses an incomplete string like ``2024-08-13'' to an incomplete +structure like @samp{(nil nil nil 13 8 2024 nil -1 nil)}, in which +an unknown DST value is @minus{}1 and other unknown values are @code{nil}. @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 +This function acts like @code{parse-time-string} except it is stricter +and errors out upon invalid input. 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). +``1998-245'' (ordinal day number). +@end defun + +@defun iso8601-parse-duration string +This function parses an ISO 8601 time duration @var{string} +and returns a decoded time structure. +@c FIXME: example? behavior on incomplete input? +@end defun + +@defun iso8601-parse-interval string +This function parses an ISO 8601 time interval @var{string} +and returns three decoded time structures +representing the start, the end, and the duration. +@c FIXME: example? behavior on incomplete input? @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..a31b60eaec2 100644 --- a/lisp/calendar/iso8601.el +++ b/lisp/calendar/iso8601.el @@ -121,11 +121,11 @@ iso8601--zone-dst (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\", -but shorter, incomplete strings like \"2008-03-02\" are valid, as -well as variants like \"2008W32\" (week number) and -\"2008-234\" (ordinal day number). +ISO 8601 date/time strings look like \"2008-03-02T13:47:30+05:30\", +or like shorter, incomplete strings like date \"2008-03-02\", +week number \"2008W32\", and ordinal day number \"2008-234\". +Values returned are identical to those of `decode-time', except +that an unknown DST value is -1 and other unknown values are nil. 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..9538ea92ee5 100644 --- a/lisp/calendar/parse-time.el +++ b/lisp/calendar/parse-time.el @@ -154,9 +154,8 @@ parse-time-string \"Wed, 15 Jan 2020 16:12:21 -0800\". This function is somewhat liberal in what format it accepts, and will attempt to 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. +Values returned are identical to those of `decode-time', except +that an unknown DST value is -1 and other unknown values are nil. See `decode-time' for the meaning of FORM." (condition-case () -- 2.43.0